This is a tutorial for the following command line tools implemented in pvAccessCPP:
pvAccessCPP provides command line tools. Each provides help. For example:
pvlist -help
The examples shown in this section assume that your PATH environment variable includes the appropriate bin directory from pvAccessCPP. For example:
export PATH=$PATH:${EPICSV7}/pvAccessCPP/bin/${EPICS_HOST_ARCH}
The examples also assume that you have cloned exampleCPP as follows:
git clone https://github.com/epics-base/exampleCPP.git
After building exampleCPP start an example database as follows:
mrk> pwd /home/epicsv4/masterCPP/exampleCPP/database/iocBoot/exampleDatabase mrk> ../../bin/linux-x86_64/exampleDatabase st.cmd
After the exampleDatabase is started the iocshell command line supports many commands. A few important commands are:
The options are:
mrk> pvlist -help Usage: pvlist [options] [server address or GUID starting with '0x']... options: -h: Help: Print this message -V: Print version and exit -i Print server info (when server address list/GUID is given) -w <sec>: Wait time, specifies timeout, default is 3.000000 second(s) -q: Quiet mode, print only error messages -d: Enable debug output examples: pvlist pvlist ioc0001 pvlist 10.5.1.205:10000 pvlist 0x83DE3C540000000000BF351F
Without any arguments this shows the location of all V4 servers it can locate. For example:
pvlist GUID 0xC50BFC5B000000003E347E33 version 1: tcp@[10.0.0.111:5075, 192.168.124.1:5075]
This only shows one line because only the exampleDatabase server is running. In an operational system the output could be quite extensive.
Once the location of a server is known the list of channel names can be shown by asking for either the GUID or tcp address. Thus either:
pvlist 0xC50BFC5B000000003E347E33or
pvlist 10.0.0.111:5075produces:
DBRao01 DBRdouble00 ...
pvinfo retrieves the introspection interface for selected channels
The options are:
mrk> pvinfo -help Usage: pvinfo [options] <PV name>... options: -h: Help: Print this message -V: Print version and exit -w <sec>: Wait time, specifies timeout, default is 3.000000 second(s) -p <provider>: Set default provider name, default is 'pva' -d: Enable debug output -c: Wait for clean shutdown and report used instance count (for expert users) Example: pvinfo double01
Some examples:
mrk> pvinfo PVRdouble
PVRdouble
Server: 10.0.0.26:5075
Type:
epics:nt/NTScalar:1.0
double value
alarm_t alarm
int severity
int status
string message
time_t timeStamp
long secondsPastEpoch
int nanoseconds
int userTag
mrk> pvinfo DBRdouble
DBRdouble
Server: 10.0.0.26:5075
Type:
epics:nt/NTScalar:1.0
double value
alarm_t alarm
int severity
int status
string message
time_t timeStamp
long secondsPastEpoch
int nanoseconds
int userTag
structure display
double limitLow
double limitHigh
string description
string units
int precision
enum_t form
int index
string[] choices
control_t control
double limitLow
double limitHigh
double minStep
valueAlarm_t valueAlarm
boolean active
double lowAlarmLimit
double lowWarningLimit
double highWarningLimit
double highAlarmLimit
int lowAlarmSeverity
int lowWarningSeverity
int highWarningSeverity
int highAlarmSeverity
byte hysteresis
mrk> pvinfo PVRpowerSupply
PVRpowerSupply
Server: 10.0.0.194:42997
Type:
structure
alarm_t alarm
int severity
int status
string message
time_t timeStamp
long secondsPastEpoch
int nanoseconds
int userTag
structure power
double value
structure voltage
double value
structure current
double value
The following describes pvget.
pvmonitor is the same as:
pvget -m
pvget provides functionality similar to caget. But it can use either provider pva or ca to access a channel. This it can accesss both DBRecords and PVRecords.
For example:
mrk> caget DBRdouble DBRdouble 1 mrk> pvget DBRdouble DBRdouble 2019-04-15 15:24:08.357 1 mrk> caget PVRdouble Channel connect timed out: 'PVRdouble' not found. mrk> pvget PVRdouble PVRdouble 2019-04-15 15:29:27.826 1 mrk>
The options are:
mrk> pvget -help Usage: pvget [options] <PV name>... options: -h: Help: Print this message -V: Print version and exit -r <pv request>: Request, specifies what fields to return and options, default is '' -w <sec>: Wait time, specifies timeout, default is 5.000000 second(s) -p <provider>: Set default provider name, default is 'pva' -M <raw|nt|json>: Output mode. default is 'nt' -v: Show entire structure (implies Raw mode) -q: Quiet mode, print only error messages -d: Enable debug output deprecated options: -q, -t, -i, -n, -F: ignored -f <input file>: errors Output details: -m -v: Monitor in Raw mode. Print only fields marked as changed. -m -vv: Monitor in Raw mode. Highlight fields marked as changed, show all valid fields. -m -vvv: Monitor in Raw mode. Highlight fields marked as changed, show all fields. -vv: Get in Raw mode. Highlight valid fields, show all fields. example: pvget double01
Some examples are:
mrk> pvget PVRdouble
PVRdouble 5
mrk> pvget PVRdoubleArray
PVRdoubleArray 5 1 2 3 4 5
mrk> pvget PVRenum
PVRenum zero
mrk> pvget -v PVRenum
PVRenum epics:nt/NTEnum:1.0
enum_t value (1) one
int index 1
string[] choices ["zero", "one"]
alarm_t alarm
int severity 0
int status 0
string message
time_t timeStamp 2018-11-26 10:19:40.278
long secondsPastEpoch 1543245580
int nanoseconds 277571561
int userTag 0
Multiple channels can be accessed witn a single command. For example:
mrk> pvget PVRdouble01 PVRdouble02 PVRdouble01 0 PVRdouble02 0
The above examples all use channel provider pva, i. e. the pvAccess server for network communication.
It is also possible to use ca. Thus it can access a V3 IOC even if the IOC has no V4 support.
mrk> pvget -p ca DBRdouble01 DBRdouble01 0 mrk> pvget -p ca -r "value,alarm,timeStamp" DBRdouble01 DBRdouble01 2019-04-16 05:48:31.010 0
pvget can also monitor, i. e. it has functionality similer to camonitor.
mrk> pvget -m -r "value,alarm,timeStamp" PVRdouble PVRdouble 2019-04-16 05:50:20.004 1 PVRdouble 2019-04-16 05:51:19.018 2
When a DBRecord is accessed via provider pva, qsrv is the server side provider that provides access to the DBRecord. When provider ca is used the channel access network protocol, which has existed since the early days of EPICS, is used to access the DBRecord. One difference is that qsrv does not honor the client request to select a subset of the fields in the DBRecord.
For example:
mrk> pvget -r "value" -p ca -v DBRdouble
DBRdouble structure
double value 1
mrk> pvget -r "value" -p pva -v DBRdouble
DBRdouble epics:nt/NTScalar:1.0
double value 1
alarm_t alarm
int severity 0
int status 0
string message NO_ALARM
time_t timeStamp 2019-04-16 08:46:04.215
long secondsPastEpoch 1555418764
int nanoseconds 214583119
int userTag 0
structure display
double limitLow -10
double limitHigh 10
string description
string units volts
int precision 2
enum_t form (0) Default
int index 0
string[] choices ["Default", "String", "Binary", "Decimal", "Hex", "Exponential", "Engineering"]
control_t control
double limitLow -9
double limitHigh 9
double minStep 0
valueAlarm_t valueAlarm
boolean active false
double lowAlarmLimit -8
double lowWarningLimit -6
double highWarningLimit 6
double highAlarmLimit 8
int lowAlarmSeverity 0
int lowWarningSeverity 0
int highWarningSeverity 0
int highAlarmSeverity 0
byte hysteresis 0
mrk>
pvDatabaseCPP provides support for filters attached to fields.
For a complete description see: pluginSupport
The following shows an example that uses the array filter:
mrk> pvget PVRdoubleArray PVRdoubleArray 2019-04-16 06:06:14.841 [1,2,3,4,5,6,7,8,9,10] mrk> pvget -r "value[array=2:6],alarm,timeStamp" PVRdoubleArray PVRdoubleArray 2019-04-16 06:06:14.841 [3,4,5,6,7] mrk> pvget -r "value[array=2:2:10],alarm,timeStamp" PVRdoubleArray PVRdoubleArray 2019-04-16 06:06:14.841 [3,5,7,9]
The EPICS 7 releases of epics-base support Channel Filters.
See filters
The following shows an example that uses the array filter:
mrk> pvget DBRdoubleArray DBRdoubleArray 2019-04-16 08:59:37.622 [1,2,3,4,5] mrk> pvget DBRdoubleArray.[2:3] DBRdoubleArray.[2:3] 2019-04-16 08:59:37.622 [3,4] mrk> caget DBRdoubleArray.[2:3] DBRdoubleArray.[2:3] 2 3 4 mrk> pvget -p ca DBRdoubleArray.[2:3] DBRdoubleArray.[2:3] [3,4]
pvput provides functionality similar to caput. For example:
mrk> caput DBRdouble01 1.0 Old : DBRdouble01 0 New : DBRdouble01 1 mrk> pvput DBRdouble01 2.0 Old : DBRdouble01 1 New : DBRdouble01 2
To see all options enter:
mrk> pvput -help
Usage: pvput [options] <PV name> <value>
pvput [options] <PV name> <size/ignored> <value> [<value> ...]
pvput [options] <PV name> <field>=<value> ...
pvput [options] <PV name> <json_array>
pvput [options] <PV name> <json_map>
options:
-h: Help: Print this message
-V: Print version and exit
-r <pv request>: Request, specifies what fields to return and options, default is ''
-w <sec>: Wait time, specifies timeout, default is 5.000000 second(s)
-p <provider>: Set default provider name, default is 'pva'
-M <raw|nt|json>: Output mode. default is 'nt'
-v: Show entire structure (implies Raw mode)
-q: Quiet mode, print only error messages
-d: Enable debug output
Deprecated options:
default: Auto - try value as enum string, then as index number
-n, -s, -F, -t: ignored
-f <input file>: error
JSON support is present
Examples:
pvput double01 1.234 # shorthand
pvput double01 value=1.234
pvput arr:pv X 1.0 2.0 # shorthand (X is arbitrary and ignored)
pvput arr:pv "[1.0, 2.0]" # shorthand
pvput arr:pv value="[1.0, 2.0]"
Field values may be given with JSON syntax.
Complete structure
pvput double01 '{"value":1.234}'
Sub-structure(s)
pvput group:pv some='{"value":1.234}' other='{"value":"a string"}'
Here are some examples:
mrk> pvput PVRdouble 5 Old : PVRdouble 0 New : PVRdouble 5 mrk> pvput PVRdoubleArray '[1,2,3]' Old : 2019-04-16 09:17:22.694 [1,2,3,4,5,6,7,8] New : 2019-04-16 09:17:58.103 [1,2,3] mrk> pvput PVRdoubleArray '[1,2,3,4,5,6,7,8]' Old : 2019-04-16 09:17:58.103 [1,2,3] New : 2019-04-16 09:18:06.830 [1,2,3,4,5,6,7,8] mrk> pvput PVRstring 'hello world' Old : 2019-04-16 09:20:16.703 hhh New : 2019-04-16 09:20:44.622 hello world mrk> pvput PVRstringArray '["a a","bbb bbb","cc ccc"]' Old : 2019-04-16 09:21:23.936 [] New : 2019-04-16 09:22:36.855 ["a a", "bbb bbb", "cc ccc"] mrk> pvput PVRstringArray '["a a","bbb bbb","cc ccc"]' Old : 2019-04-16 09:21:23.936 [] New : 2019-04-16 09:22:36.855 ["a a", "bbb bbb", "cc ccc"]
pvput can write to multiple fields using JSON syntax. It can write to any field type except for union and unionArray.
For example
mrk> pvinfo PVRpowerSupply
PVRpowerSupply
Server: 10.0.0.194:42997
Type:
structure
alarm_t alarm
int severity
int status
string message
time_t timeStamp
long secondsPastEpoch
int nanoseconds
int userTag
structure power
double value
structure voltage
double value
structure current
double value
mrk> pvput -r "voltage" PVRpowerSupply voltage='{"value":"5"}'
Old : structure
structure voltage
double value 0
New : structure
structure voltage
double value 5
mrk> pvput -r "voltage,power" PVRpowerSupply power='{"value":1.2}' voltage='{"value":1.2}'
Old : structure
structure voltage
double value 5
structure power
double value 0
New : structure
structure voltage
double value 1.2
structure power
double value 1.2
mrk> pvinfo PVRBigRecord
PVRBigRecord
Server: 10.0.0.26:5075
Type:
structure
time_t timeStamp
long secondsPastEpoch
int nanoseconds
int userTag
structure scalar
structure boolean
boolean value
structure byte
byte value
structure long
long value
structure double
double value
structure string
string value
structure scalarArray
structure boolean
boolean[] value
structure byte
byte[] value
structure long
long[] value
structure double
double[] value
structure string
string[] value
structure[] structureArray
structure
string name
string value
union restrictedUnion
string string
string[] stringArray
any variantUnion
mrk> pvput PVRBigRecord scalar='{"boolean":{"value":true},"double":{"value":5}}'
Old : structure
...
New : structure
...
structure scalar
structure boolean
boolean value true
structure byte
byte value 0
structure long
long value 0
structure double
double value 5
structure string
string value
...
mrk> pvput PVRBigRecord scalar='{"string":{"value":"Hi"}}' scalarArray='{"string":{"value":["aa","bb"]}}'
Old : structure
...
New : structure
time_t timeStamp 2019-04-16 09:46:50.379
long secondsPastEpoch 1555422410
int nanoseconds 379367681
int userTag 0
structure scalar
structure boolean
boolean value true
structure byte
byte value 0
structure long
long value 0
structure double
double value 5
structure string
string value Hi
structure scalarArray
structure boolean
boolean[] value []
structure byte
byte[] value []
structure long
long[] value []
structure double
double[] value []
structure string
string[] value ["aa", "bb"]
structure[] structureArray
union restrictedUnion
(none)
any variantUnion
(none)
mrk> pvput PVRBigRecord '{"structureArray":[{"name":"marty","value":"Kraimer"},{"name":"bob","value":"Dalesio"}]}'
Old : structure
...
New : structure
...
structure[] structureArray
structure
string name marty
string value Kraimer
structure
string name bob
string value Dalesio
union restrictedUnion
(none)
any variantUnion
(none)
An example using the array filter is:
mrk> pvget PVRdoubleArray PVRdoubleArray 2019-04-16 13:55:38.384 [1,2,3,4,5,6,7,8,9,10] mrk> pvput -r "value[array=1:3]" PVRdoubleArray [100,200,300] Old : [2,3,4] New : [100,200,300] mrk> pvget PVRdoubleArray PVRdoubleArray 2019-04-16 13:57:02.736 [1,100,200,300,5,6,7,8,9,10] mrk>
mrk> pvput DBRdoubleArray [1,2,3,4,5] Old : 2021-05-07 10:20:22.373 [1,2,3,4,5] New : 2021-05-07 10:22:07.437 [1,2,3,4,5] mrk> pvget DBRdoubleArray.[2:3] DBRdoubleArray.[2:3] 2021-05-07 10:22:07.437 [3,4]