tweaked the pod docs

1 files changed, 100 insertions, 116 deletions

diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm
index 0b63212..c58ed19 100644
--- a/libvxi11client/perlbits/Client.pm
+++ b/libvxi11client/perlbits/Client.pm
@@ -183,7 +183,7 @@ __END__
 
 =head1 NAME
 
-VXI11::Client - Perl extension for interfacing with VXI-11 networked instruments
+VXI11::Client - Perl module for interfacing with VXI-11 networked test and measurement equipment
 
 =head1 SYNOPSIS
 
@@ -218,113 +218,6 @@ 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
@@ -461,24 +354,115 @@ The only exceptions to this are the read and write methods
 0   - Error as above or zero bytes read/written
 > 0 - Number of bytes read/written
 
-=head2 EXPORT
+=head1 SAMPLE SCRIPTS
+
+=head2 MINIMAL IDENTIFICATION SCRIPT
+
+  #!/usr/bin/perl
+  use strict;
+  use warnings;
+  use VXI11::Client;
+
+  my $instr = vxi_open( address => "192.168.0.62" );
+  $instr->vxi_write("*idn?");
+  my ( $bytes, $idn, $reason ) = $instr->vxi_read();
+  printf "This instrument is: $idn\n";
+  $instr->vxi_close();
+
+=head2 INTERACTIVE CLIENT #1
+
+  #!/usr/bin/perl
+  use strict;
+  use warnings;
+  use VXI11::Client;
+
+  # This script provides a simple line-based shell for communicating with
+  # a VXI-11.3 instrument. Errors and esponses to queries are signaled to
+  # this script using the interrupt channel. The rpcbind/portmapper service
+  # must be running on your system for this to work. If not, see the
+  # sample script that does not use the interrupt channel. Tested with an
+  # Avtech Electrosystems pulse generator.
+
+  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.
+
+  my $prompt = "\n> ";
+  print "\nType your commands. Ctrl+C to exit\n" . $prompt;
+
+  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 ) or die "Could not open instrument at $ip_addr.";
+
+  $instr->vxi_write("*ese 60");          # Flag command-related errors.
+  $instr->vxi_write("*sre 48");          # Request service when a response is
+                                         # available, or an error has occurred.
+  $instr->vxi_create_intr_chan();        # Create interrupt channel.
+  $instr->vxi_enable_srq($my_interrupt_handle);
+                                         # Enable service requests on the
+                                         # interrupt channel
+  while (1) {
+
+      # check for user input
+      if ( defined( my $line = <STDIN> ) ) {
+          $instr->vxi_write($line);
+      }
+
+      # was a message response or error reported within
+      # the default timeout period of 250 ms?
+      my $handle;
+      if (   ( $handle = vxi_wait_for_interrupt() )
+          && ( $handle eq $my_interrupt_handle ) )
+      {
+          my ( $error, $statusbyte ) = $instr->vxi_readstatusbyte();
+
+          # query-response message available according to status byte
+          if ( $statusbyte | 0x10 ) {
+              my ( $bytes, $response, $reason ) = $instr->vxi_read();
+              print $response. "\n";
+          }
 
-vxi_startinterruptserver
-vxi_stopinterruptserver
-vxi_open
-vxi_wait_for_interrupt
+          # error occurred according to status byte
+          if ( $statusbyte | 0x20 ) {
+              my $response = "";
+
+              # cycle through all errors in the error queue
+              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");
+          }
+      }
+      print $prompt;
+  }
+
+  # Tidy up!
+  $instr->vxi_disable_srq();
+  $instr->vxi_destroy_intr_chan();
+  $instr->vxi_unlock();
+  $instr->vxi_local();
+  $instr->vxi_close();
 
 =head1 SEE ALSO
 
-The vxi-11 spec.
+The VXI-11.3 specifications.
 
 =head1 AUTHOR
 
-daniel, E<lt>daniel@E<gt>
+Dr. Michael J. Chudobiak, mjc@avtechpulse.com
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2013 by daniel
+Copyright (C) 2013 by Avtech Electrosystems Ltd.
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.14.2 or,