add a real sample script to the pod docsvxi

1 files changed, 108 insertions, 1 deletions

diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm
index 6e3d257..39020a2 100644
--- a/libvxi11client/perlbits/Client.pm
+++ b/libvxi11client/perlbits/Client.pm
@@ -202,7 +202,7 @@ VXI11::Client - Perl extension for interfacing with VXI-11 networked instruments
   my ($bytes, $buff, $reason) = $instr->vxi_read();
   print "got " . $bytes . ";" . $buff . " reason " . $reason ."\n";
 
-  my ($error, $statusbyte) = $instr->vxi_readstatusbyte(0);
+  my ($error, $statusbyte) = $instr->vxi_readstatusbyte();
   printf "status byte is " . $statusbyte . "\n";
 
   $instr->vxi_create_intr_chan();
@@ -222,6 +222,113 @@ VXI11::Client - Perl extension for interfacing with VXI-11 networked instruments
   vxi_stopinterruptserver();
 
 
+=head1 SAMPLE SCRIPT
+
+  #!/usr/bin/perl
+
+  use strict;
+  use warnings;
+  use VXI11::Client;
+
+  # This script tests communications to, and service requests from,
+  # an Avtech Electrosystems pulse generator (or any other instrument
+  # that accepts the "freq" command).
+
+  my $ip_addr = "192.168.0.62";          # IP address of the instrument,
+                                         # or VXI-to-GPIB gateway device.
+  my $device = 0;                        # Only revelant if a VXI-to-GPIB
+                                         # gateway is used.
+
+  vxi_startinterruptserver();            # Launch a server to handle
+                                         # interrupts from the instrument.
+  my $my_interrupt_handle = "Avtech";    # Each interrupt source needs a name.
+
+  my $instr = vxi_open( address => $ip_addr, device => $device );
+
+  if ( $instr->vxi_lock() > 0 ) {
+      print "Instrument is locked for our use.\n";
+
+      $instr->vxi_remote();              # Lock out the front panel (optional)
+
+      $instr->vxi_clear();               # Reset the device interface.
+      $instr->vxi_write("*rst");         # Load default settings.
+      $instr->vxi_write("*cls");         # Clear the error queue.
+
+      $instr->vxi_write("*idn?");
+      my ( $bytes, $idn, $reason ) = $instr->vxi_read();
+      printf "Name of device: $idn\n";
+
+      $instr->vxi_write("*ese 60");      # Flag command-related errors.
+      $instr->vxi_write("*sre 32");      # Request service on those errors.
+      $instr->vxi_create_intr_chan();    # Create interrupt channel.
+      $instr->vxi_enable_srq($my_interrupt_handle);
+                                         # Enable service requests on the
+                                         # interrupt channel
+  }
+  else {
+      die "We could not obtain a lock.\n";
+  }
+
+  # Generate a list of test frequencies
+  my @list;
+  foreach my $suffix ( "Hz", "kHz", "MHz" ) {
+      foreach my $step ( 1, 10, 100 ) {
+          foreach my $base ( 1, 2, 5 ) {
+              my $freq = ( $base * $step ) . " " . $suffix;
+              push @list, $freq;
+          }
+      }
+  }
+
+  # Go up the list, then down again, to ensure that the
+  # error system resets properly.
+  push @list, reverse(@list);
+
+  # Execute each frequency and see if any errors occur.
+  foreach my $freq (@list) {
+
+      print "\nTrying $freq.\n";
+      $instr->vxi_write("freq $freq");
+
+      # You could just call "syst:err?" to check for errors after
+      # each freq command, eliminating the need for the interrupt channel.
+      # That's up to you!
+
+      # Was an interrupt fired within the default wait period of 250 ms?
+      my $handle;
+      if (   ( $handle = vxi_wait_for_interrupt() )
+          && ( $handle eq $my_interrupt_handle ) )
+      {
+          my ( $error, $statusbyte ) = $instr->vxi_readstatusbyte();
+          printf( "Status byte: 0x%x\n", $statusbyte );
+
+          my $response = "";
+          until ( $response =~ /No error/i ) {
+              $instr->vxi_write("syst:err?");
+              ( my $bytes, $response, my $reason ) = $instr->vxi_read();
+              if ( $response !~ /No error/i ) {
+                  print "Error message: $response\n";
+              }
+          }
+
+          # clear the error reporting bits
+          $instr->vxi_write("*cls");
+      }
+  }
+
+  # These functions are also available, but aren't especially useful
+  # with the Avtech Electrosystems pulse generator.
+  $instr->vxi_abort();
+  $instr->vxi_trigger();
+
+  # Tidy up!
+  $instr->vxi_disable_srq();
+  $instr->vxi_destroy_intr_chan();
+  $instr->vxi_unlock();
+  $instr->vxi_local();
+  $instr->vxi_close();
+
+
 =head1 DESCRIPTION
 
 A client for VXI-11 networked instruments. To start talking to an instrument