From b87d806354d4faafea4b27b7f31ab4db5216c5b1 Mon Sep 17 00:00:00 2001 From: daniel Date: Fri, 1 Feb 2013 00:10:28 +0900 Subject: clean up the function descriptions a bit --- libvxi11client/perlbits/Client.pm | 177 +++++++++++++++++++------------------- 1 file changed, 87 insertions(+), 90 deletions(-) (limited to 'libvxi11client/perlbits/Client.pm') diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm index a170c6c..3af8fdf 100644 --- a/libvxi11client/perlbits/Client.pm +++ b/libvxi11client/perlbits/Client.pm @@ -230,137 +230,134 @@ 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 INT 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 INT 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 VXI11::Client 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 INT 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 INT 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 INT 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 INT INST->vxi_write(STRING 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 (INT bytes, STRING string, INT 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 (INT ret, STRING dataout, INT 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 INT 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 INT 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 INT 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 INT 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 INT 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 INT 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 STRING 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 INT INST->vxi_remote([waitforlock => 0]); + +Lock out the instrument's display. - Clear the instruments's display. +=item INT INST->vxi_local([waitforlock => 0]); -INT INST->vxi_trigger([waitforlock => 0]); +Unlock the instrument's display. - Trigger the instrument. +=item INT INST->vxi_clear([waitforlock => 0]); +Clear the instruments's display. + +=item INT 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 -- cgit From 1f2c64beb20da6a635b2b5f610a6d747fadbfd7d Mon Sep 17 00:00:00 2001 From: daniel Date: Fri, 1 Feb 2013 00:25:43 +0900 Subject: make the function descriptions look more perl --- libvxi11client/perlbits/Client.pm | 40 +++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'libvxi11client/perlbits/Client.pm') diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm index 79f7029..1bbafc7 100644 --- a/libvxi11client/perlbits/Client.pm +++ b/libvxi11client/perlbits/Client.pm @@ -233,44 +233,44 @@ client that the instruments can connect to. =over -=item INT vxi_startinterruptserver(); +=item $retcode = 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. -=item INT vxi_stopinterruptserver(); +=item $retcode = vxi_stopinterruptserver(); Shutdown the local RPC server. -=item VXI11::Client vxi_open( address => STRING, [device => STRING] ); +=item $inst = vxi_open( address => STRING, [device => STRING] ); Open a link to an instrument. Use the returned instance to call the object methods below. -=item INT INST->vxi_close(); +=item $retcode = $inst->vxi_close(); 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. -=item INT INST->vxi_lock([waitforlock => 'false']); +=item $retcode = $inst->vxi_lock([waitforlock => 'false']); Lock the instrument. You can tell the instrument to try to wait for the lock to become free and lock it via waitforlock, -=item INT INST->vxi_unlock(); +=item $retcode = $inst->vxi_unlock(); Unlock the instrument. Only makes sense if you are holding the lock. -=item INT INST->vxi_write(STRING data, [ len => -1, waitforlock => 0, end => 1 ]); +=item $retcode = $inst->vxi_write(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. -=item (INT bytes, STRING string, INT reason) INST->vxi_read([ bufferlen => 1024, waitforlock => 0, termchrset => 0, termchr => 0, autochomp => 1]); +=item ($bytes, $data, $reason) = $inst->vxi_read([ bufferlen => 1024, waitforlock => 0, termchrset => 0, termchr => 0, autochomp => 1]); 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 @@ -280,25 +280,25 @@ 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 (INT ret, STRING dataout, INT dataoutlen) = vxi_docmd (INT cmd, [ datain => "", datainlen => -1, dataoutbufferlen => 256, waitforlock => 0, autochomp => 1]); +=item ($retcode, $dataout, $dataoutlen) = vxi_docmd (INT cmd, [ datain => "", datainlen => -1, dataoutbufferlen => 256, waitforlock => 0, autochomp => 1]); 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 INT INST->vxi_abort(); +=item $retcode = $inst->vxi_abort(); Abort an in-progress operation. -=item INT vxi_readstatusbyte([ waitforlock => 0 ]); +=item $retcode = $inst->vxi_readstatusbyte([ waitforlock => 0 ]); Read the instruments status byte. -=item INT INST->vxi_create_intr_chan(); +=item $retcode = $inst->vxi_create_intr_chan(); Creates an interrupt channel from the instrument to this client. This must be called after vxi_startinterruptserver. -=item INT INST->vxi_enable_srq(STRING handle); +=item $retcode = $inst->vxi_enable_srq(STRING handle); Tell the instrument to fire interrupts/service requests to the interrupt channel. Must be called after vxi_create_intr_chan(). @@ -306,18 +306,18 @@ 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. -=item INT INST->vxi_disable_srq(); +=item $retcode = $inst->vxi_disable_srq(); Tell the instrument that you don't want it to send interrupts/ service requests anymore. This does not destroy the interrupt channel. -=item INT INST->vxi_destroy_intr_chan(); +=item $retcode = $inst->vxi_destroy_intr_chan(); Tell the instrument to disconnect from the interrupt service that is running locally. This does not shut down the interrupt service. -=item STRING vxi_wait_for_interrupt([INT timeout => -1 | 0 | n]); +=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 @@ -326,19 +326,19 @@ 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 INT INST->vxi_remote([waitforlock => 0]); +=item $retcode = $inst->vxi_remote([waitforlock => 0]); Lock out the instrument's display. -=item INT INST->vxi_local([waitforlock => 0]); +=item $retcode = $inst->vxi_local([waitforlock => 0]); Unlock the instrument's display. -=item INT INST->vxi_clear([waitforlock => 0]); +=item $retcode = $inst->vxi_clear([waitforlock => 0]); Clear the instruments's display. -=item INT INST->vxi_trigger([waitforlock => 0]); +=item $retcode = $inst->vxi_trigger([waitforlock => 0]); Trigger the instrument. -- cgit From 4b9c77d31ba6d6dd80e9cc929a1ee565fa7a5179 Mon Sep 17 00:00:00 2001 From: daniel Date: Fri, 1 Feb 2013 00:55:21 +0900 Subject: Fix return codes section in the docs --- libvxi11client/perlbits/Client.pm | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'libvxi11client/perlbits/Client.pm') diff --git a/libvxi11client/perlbits/Client.pm b/libvxi11client/perlbits/Client.pm index 1bbafc7..076c5a2 100644 --- a/libvxi11client/perlbits/Client.pm +++ b/libvxi11client/perlbits/Client.pm @@ -346,15 +346,19 @@ Trigger the instrument. Return codes work like this: -1 - is a success -0 - means the request failed locally, the state inside the client is + +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 + +< 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 - Error as above or zero bytes read/written + > 0 - Number of bytes read/written =back -- cgit