diff options
Diffstat (limited to 'libvxi11client/perlbits')
| -rw-r--r-- | libvxi11client/perlbits/Client.pm | 181 |
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 |