Merge branch 'master' of ulmo:Instrument

1 files changed, 91 insertions, 90 deletions

diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm
index 65e544f..076c5a2 100644
--- a/libvxi11client/perlbits/Client.pm
+++ b/libvxi11client/perlbits/Client.pm
@@ -230,137 +230,138 @@ becomes the server). Starting the interrupt server creates an RPC server on the
 client that the instruments can connect to.
 
 =head2 USAGE
-  
-INT vxi_startinterruptserver();
 
-	Start the local RPC service for the instrument to connect to and deliver
-	interrupt/service requests to.
-	Make sure you have portmapper or rpcbind running and you aren't blocking
-	the ports it allocates.
+=over
 
-INT vxi_stopinterruptserver();
+=item $retcode = vxi_startinterruptserver();
 
-	Shutdown the local RPC server.
+Start the local RPC service for the instrument to connect to and deliver
+interrupt/service requests to.
+Make sure you have portmapper or rpcbind running and you aren't blocking
+the ports it allocates.
 
-INT INST = vxi_open( address => STRING, [device => STRING] );
+=item $retcode = vxi_stopinterruptserver();
 
-	Open a link to an instrument. Use the returned instance to call 
-	the object methods below.
+Shutdown the local RPC server.
 
-INT INST->vxi_close();
+=item $inst = vxi_open( address => STRING, [device => STRING] );
 
-	Destroy the link to the insturment and destroy the local RPC client.
-	You must not use an instance created with vxi_open(); after calling this.
+Open a link to an instrument. Use the returned instance to call 
+the object methods below.
 
-INT INST->vxi_lock([waitforlock => 'false'])
+=item $retcode = $inst->vxi_close();	
 
-	Lock the instrument. You can tell the instrument to try to wait for 
-	the lock to become free and lock it via waitforlock,
+Destroy the link to the insturment and destroy the local RPC client.
+You must not use an instance created with vxi_open(); after calling this.
 
-INT INST->vxi_unlock();
+=item $retcode = $inst->vxi_lock([waitforlock => 'false']);
 
-	Unlock the instrument. Only makes sense if you are holding the lock.
-              
-INT INST->vxi_write(STRING data, [ len => -1,
-                		   waitforlock => 0,
-                                   end => 1 ]);
-	Write data to the instrument. If the data is a terminated string you can 
-	pass -1 as the length to have it calculated for you. If the data is not 
-	terminated or for some reason you only want to write part of it you need
-	to provide a length. You can wait for the lock to be freed by via waitforlock.  
-	       
-(INT bytes, STRING string, INT reason) INST->vxi_read([ bufferlen => 1024,
-                     			    waitforlock => 0,
-                     			    termchrset => 0,
-                     			    termchr => 0,
-                     			    autochomp => 1]);
+Lock the instrument. You can tell the instrument to try to wait for 
+the lock to become free and lock it via waitforlock,
 
-	Read some data from the instrument. The default parameters should be fine
-	for most cases. If you need to read more than 1024 bytes you should pass 
-	in the required buffer size via bufferlen. This function will not read more 
-	than the buffer size. The number of bytes returned is what the instrument sent
-	not what was copied into the buffer. So if the number of bytes returned is
-	larger than bufferlen the data is truncated. If autochomp is set the newline
-	from the returned data will be automatically removed.
+=item $retcode = $inst->vxi_unlock();
 
-(INT ret, STRING dataout, INT dataoutlen) =  vxi_docmd (INT cmd, [ datain => "",
-						datainlen => -1,
-						dataoutbufferlen => 256,
-						waitforlock => 0,
-						autochomp => 1]);
+Unlock the instrument. Only makes sense if you are holding the lock.
 
-	Send a command to the instrument possibly with some data. The rules for write apply
-	to datain and the rules for read apply for dataout.
+=item $retcode = $inst->vxi_write(data, [ len => -1, waitforlock => 0, end => 1 ]);
 
-INT INST->vxi_abort();
-	Abort an in-progress operation.	
+Write data to the instrument. If the data is a terminated string you can 
+pass -1 as the length to have it calculated for you. If the data is not 
+terminated or for some reason you only want to write part of it you need
+to provide a length. You can wait for the lock to be freed by via waitforlock.  
 
-INT vxi_readstatusbyte([ waitforlock => 0 ]);
+=item ($bytes, $data, $reason) = $inst->vxi_read([ bufferlen => 1024, waitforlock => 0, termchrset => 0, termchr => 0, autochomp => 1]);
 
-	Read the instruments status byte.
+Read some data from the instrument. The default parameters should be fine
+for most cases. If you need to read more than 1024 bytes you should pass 
+in the required buffer size via bufferlen. This function will not read more 
+than the buffer size. The number of bytes returned is what the instrument sent
+not what was copied into the buffer. So if the number of bytes returned is
+larger than bufferlen the data is truncated. If autochomp is set the newline
+from the returned data will be automatically removed.
 
-INT INST->vxi_create_intr_chan();   
+=item ($retcode, $dataout, $dataoutlen) =  vxi_docmd (INT cmd, [ datain => "", datainlen => -1, dataoutbufferlen => 256, waitforlock => 0, autochomp => 1]);
 
-	Creates an interrupt channel from the instrument to this client.
-	This must be called after vxi_startinterruptserver.
+Send a command to the instrument possibly with some data. The rules for write apply
+to datain and the rules for read apply for dataout.
 
-INT INST->vxi_enable_srq(STRING handle);
+=item $retcode = $inst->vxi_abort();	
 
-	Tell the instrument to fire interrupts/service requests to the 
-	interrupt channel. Must be called after vxi_create_intr_chan().
-	You should give a unique channel handle for each instrument as
-	you will need this to work out which device set an interrupt/service 
-	request. 
+Abort an in-progress operation.	
 
-INT INST->vxi_disable_srq();
+=item $retcode = $inst->vxi_readstatusbyte([ waitforlock => 0 ]);
 
-	Tell the instrument that you don't want it to send interrupts/
-	service requests anymore. This does not destroy the interrupt 
-	channel.
+Read the instruments status byte.
 
-INT INST->vxi_destroy_intr_chan();
+=item $retcode = $inst->vxi_create_intr_chan();   
 
-	Tell the instrument to disconnect from the interrupt service that
-	is running locally. This does not shut down the interrupt service.
+Creates an interrupt channel from the instrument to this client.
+This must be called after vxi_startinterruptserver.
 
-STRING vxi_wait_for_interrupt([INT timeout -1 : 0 : n])
+=item $retcode = $inst->vxi_enable_srq(STRING handle);
 
-	Waits for an interrupt/service request to be received from a connected 
-	instrument. When an interrupt is caught the handle of the interrupt will
-	be returned. If no interrupt is caught undef will be returned.
-	You can pass a timeout in ms (the default is 250ms), or 0 to never block
-	and only return interrupts that have already happened or -1 to block until
-	an interrupt is caught (could block forever!).
+Tell the instrument to fire interrupts/service requests to the 
+interrupt channel. Must be called after vxi_create_intr_chan().
+You should give a unique channel handle for each instrument as
+you will need this to work out which device set an interrupt/service 
+request. 
 
-INT INST->vxi_remote([waitforlock => 0]);      
+=item $retcode = $inst->vxi_disable_srq();
 
-	Lock out the instrument's display.
+Tell the instrument that you don't want it to send interrupts/
+service requests anymore. This does not destroy the interrupt 
+channel.
 
-INT INST->vxi_local([waitforlock => 0]);
+=item $retcode = $inst->vxi_destroy_intr_chan();
 
-	Unlock the instrument's display.
-	
-INT INST->vxi_clear([waitforlock => 0]);
+Tell the instrument to disconnect from the interrupt service that
+is running locally. This does not shut down the interrupt service.
+
+=item $handle = vxi_wait_for_interrupt([INT timeout => -1 | 0 | n]);
+
+Waits for an interrupt/service request to be received from a connected 
+instrument. When an interrupt is caught the handle of the interrupt will
+be returned. If no interrupt is caught undef will be returned.
+You can pass a timeout in ms (the default is 250ms), or 0 to never block
+and only return interrupts that have already happened or -1 to block until
+an interrupt is caught (could block forever!).
+
+=item $retcode = $inst->vxi_remote([waitforlock => 0]);      
+
+Lock out the instrument's display.
+
+=item $retcode = $inst->vxi_local([waitforlock => 0]);
+
+Unlock the instrument's display.
 
-	Clear the instruments's display.
+=item $retcode = $inst->vxi_clear([waitforlock => 0]);
 
-INT INST->vxi_trigger([waitforlock => 0]);
+Clear the instruments's display.
 
-	Trigger the instrument.
+=item $retcode = $inst->vxi_trigger([waitforlock => 0]);
 
+Trigger the instrument.
+
+=item Integer return codes
 
 Return codes work like this:
 
-	1   - is a success
-	0   - means the request failed locally, the state inside the client is
-	incorrect, i.e. calling to enable interrupts before creating the channel
-	or that the server couldn't be contacted
-	< 0 - Any negative value is the negated VXI-11 error code from the server
+
+1 - is a success
+
+0 - means the request failed locally, the state inside the client is
+incorrect, i.e. calling to enable interrupts before creating the channel
+or that the server couldn't be contacted
+
+< 0 - Any negative value is the negated VXI-11 error code from the server"
 
 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
+0 - Error as above or zero bytes read/written
+
+> 0 - Number of bytes read/written
+
+=back
 
 =head1 SAMPLE SCRIPTS