This document provides some guidelines on how the stand-alone Unix-based channel access tools caget, caput, caGet1, caPut1, caInfo, and caInfo1 should be used. For casual users, these tools are designed simply for easy access of channel access operations on the Unix side; high performance is not an important issue in this application. If users want efficient and sophisticated channel access, they should write their own program and call the lower-level channel access functions directly.
The repeated usage of these commands on the same set of process variables (PV) within Unix scripts is not recommended. These tools need to do name resolution and TCP/IP connection setup every time they run. For many repeated puts and gets, these tools use the network bandwidth and the CPU of the server less efficiently than more efficiently coded clients.
The following typographical conventions are used in the command syntax:
Command Syntax
---------------------------------------------------------------------
Usage:
caget [-n] [-t] [-f n] [-e n] [-w sec] [-# no] <pv_name>
This command read a value or array of values from one or more IOC channels.
-n returns numerical value instead of string for DBR_ENUM field
-t Terse mode, process variable name not returned
-f n Use f format, n specifies number of digits after the decimal point
-e n Use e format, n specifies number of digits after the decimal point
-w sec Wait time, specifies bigger time out, default is 1.0 second
-# no The number 'no' specifies the number of values to be returned for
an array record. If this option is not used then the whole array
is returned. The first returned number is the size of the array ,
then it is followed with the array of values obtained.
<pv_name> a single or a list of PV names from IOC
Examples: caget pv_name
caget pv_name1 pv_name2 pv_name3
---------------------------------------------------------------------
Previously a default time of 0.3 second was used for timeout; however
since the channel access security implementation the caget timed
out more frequently. Now a default timeout of 1 second is used. This should
allow enough time for caget to finish successfully. If a longer time
out is required, the user can use the `-w sec' option.caget can be used to get native or numerical values back for an IOC database process variable. Normally it returns the process variable name and the value to the standard output device. If no process variable name is desired, the user can use the terse mode `-t' option.
A string representation is returned for the DBR_ENUM type field. If a numerical value is desired for ENUM type field, the user can use the `-n' option.
If the requested PV is a waveform record, caget returns the process variable name, the count of values defined in the database, and the array of values. The `-# no' option can be used to control the desired number of elements to be returned for a waveform record.
Command Syntax
------------------------------------------------------------------
Usage:
caput [-t] [-s] [-w sec] [-m] <pv_name> <pv_value>
This command writes a value or array of values to a channel.
It can also write an array of single values to an array of channels.
-t Terse mode, only the successfully put value is returned
-s pv_value entered as database defined enumeral string
-w sec Wait time, specifies bigger time out, default is 1 second
-m this option specified the input value string is
a comma separated values for a waveform record
<pv_name> requested database process variable name
(multiple PV names must be seperated by comma no space)
<pv_value> new value to put to IOC
(multiple PV values must be seperated by comma no space)
Examples: caput pv_name pv_value
caput pv_name1,pv_name2 pv_value1,pv_value2
caput -m pv_name v1,v2,v3,...
------------------------------------------------------------------
A default time out value of 1 second is used for getting and putting values
to IOC. This should allow enough time for caput to finish successfully. If a longer time out is required, the user can use the `-w sec' option.Normally caput returns the process variable name and both the old and new values to the standard output device. If the terse mode `-t' option is used, only the new value is returned.
Normally, the caput only writes a single value to an IOC PV name. For a waveform record, it can only write the first element to IOC by default. To write an array to a waveform record, please use `-m' option.
Command Syntax
--------------------------------------------------------------------
Usage:
caGet1 [-w sec] <infile> [outfile]
This tool uses CA to get values in DBR_STRING form for a list of PVs.
Output results are sent to stdout or saved in a output file.
[-w sec] - Optional wait time, specifies longer time out,
default is 10 seconds
<infile> - Required; contains a list of channel names,
each on a separate line.
[outfile] - Optional; records the values obtained
from IOC for the corresponding <infile> list.
This <outfile> can be used directly by caPut.
--------------------------------------------------------------------
On Unix it takes about 6 seconds to receive the values for 1000 process
variables. The default timeout used for caGet1 is 10 seconds.
If a user needs to set a longer time out value, the `-w sec' option
should be used.caGet1 has been modified so that it can accept input directly from the standard input device. The input file should contain a list of channel names, each on a separate line. Extra spaces, tabs, and blank lines are now allowed. For waveform records only the first element is returned.
Command Syntax
-------------------------------------------------------------------------
Usage:
caPut1 [-w sec] <infile>
This tool puts the set values to IOC channels. It reads an input
file which contains a list of pair values of channel_name & set_value
and puts the set_values into IOC through CA call. The set_value
must be in DBR_STRING form as created by caGet1.
[-w sec] - Optional wait time, specifies longer time out,
default is 10 seconds
<infile> - Required; contains a list of channel names each on
a separate line and followed by the corresponding
value to be put to IOC.
-------------------------------------------------------------------------
On Unix it takes about 6 seconds for to write 1000 values to a single IOC.
The default timeout used for caPut1 is 10 seconds. If a user needs to
set a longer time out value, the `-w sec' option should be used.caPut1 can accept input directly from the standard input device. The input file should contain a list of channel names, one per line, followed with at least one blank space, then followed with the set value. Each line should end with a carriage return. If a blank string is to be written to the process variable, at least one blank space is required after the process variable name.
caInfo continually reads in process variable names from the standard input until a keyword `q' or `Q' is encountered. A carriage return is expected after each process variable name.
A typical caInfo session run on the workstation `pan',is given below. The user input is shown in bold face. The process variable `chademoin1' is defined as a string type record in the database, therefore a warning message is generated.
--------------------------------------------------------------------
pan 166: caInfo
Enter PV_name or quit
PV? : chademoai1
chademoai1 17.00 HIGH MINOR 20.00 -20.00 Counts
PV?: chademobi1
chademobi1 1.00 STATE MINOR 0.00 0.00
PV? : chademoai2
chademoai2 1.00 NO_ALARM NO_ALARM 10.00 0.00 Volts
PV? : chademoin1
*** wrong type of record entered ***
PV? : q
pan 167:
--------------------------------------------------------------------
Command Syntax
------------------------------------------------------------------
Usage:
caInfo1 [-w sec] <infile> [outfile]
where
[-w sec] - Option to override the default timeout wait time,
default wait time is 10 seconds.
<infile> - Required; contains a list of channel names,
each on a separate line, followed by a carriage
return.
[outfile] - Optional output file; records the obtained
operating information from IOC for the requested
<infile> list
------------------------------------------------------------------
caInfo1 can take input directly from the standard input. The input file contains a list of channel names; each line can contain only a single channel name and must end with a carriage return. The printed results are send to the standard output device.
On Unix it takes about 9 seconds total CPU to receive the operating information for 1000 process variables. Printing results on the standard output device takes about 6 seconds. The default timeout used for caInfo1 is 10 seconds. If a user needs to set a longer timeout value, the `-w sec' option should be used.