APS_WISH User's Guide
Author: Ben-chin Cha
Table of Contents
aps_wish is an APS version of wish which includes all the tcl/tk commands plus the EZCA channel access interface commands listed below.
It is assumed that the Sun4 operating system is used throughout this document. And the aps_wish was built as an EPICS extensions tool and it is installed under the /usr/local/epics/extensions/bin/sun4 directory.
- setenv EPICS_EXTENSIONS /usr/local/epics/extensions
- Include /usr/local/epics/extensions/bin/sun4 in your search path
Available channel access commands in aps_wish are listed below:
The ezca channel access commands in aps_wish always return the appropriate or meaningful string for the command entered. This will minimize the intervene required from the user. In addition to the result string returned to the aps_wish each command also returns a return code which can be
A user always can use the TCL exception handling function catch to check the return code of each command. The catch command returns TCL_OK (i.e. 0) if the command execution succeeded, returns TCL_ERROR (i.e. 1) if the command execution failed.
Most of CA command returns a resultant string representation of the command execution. If the channel access failed, in the interactive mode the appropriate error message is displayed on the user terminal, in programming control mode a user can use the TCL exception handling function to catch the error.
Get the current value(s) back for the requested channel(s) This commands does not support waveform record, ezcagetwf supports waveform record.
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- <type> - Optional, use `string' to specify the return value in native string form.
- Return - If <type> not specified the value is returned as real number, if `string' is specified the value is returned in native form. If CA failed none is returned.
Example
ezcaget chademoai1
Put new value(s) to the requested channel(s), for single value it figures out type of put automatically. This commands does not support waveform record, ezcaputwf supports waveform record.
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- <value> - Required input, input value variable, which can be a single value or a list of values.
- <type> - Optional, ezcaput assumed array put in double precision form, use `string' to specify the input value is in the native string form instead of numerical form.
- Return - Returns actual value(s) puts to the IOC pvname. If CA failed none is returned.
Examples
ezcaput chademobi1 1
ezcaput chademobi1 "State 0" string
ezcaput {chademoai2 chademomask1} {111 222}
Get the current value setting and array of strings for the requested enum type field. This command can not support a list input.
- <pvname.field> - Required input, a enumerical type value field, e.g., the field can be `SCAN'
- Return - A literal string which consists of current enumeric value, status, severity, the number of enum strings, and the list of all enum strings returned by CA. If CA failed none is returned.
Example
ezcagetenumstrings chademoai1.SCAN
Get the database record type for the specified channels.
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - The database record native type(s) obtained for the specified channel(s). If CA failed none is returned.
Example
set x {chademoai1 chademoai2 chademobi1}
ezcagettype $x
Get the database element count(s) for the specified channel(s).
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - The nelem(s) of data in the array obtained for the specified channel(s). For waveform record it is > 1. If CA failed none is returned.
Example
set x {chademoai1 chademoai2 chademobi1}
ezcagetnelem $x
Get the database miscellaneous record control information for the specified channel(s).
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - The value(s) of specified channel(s) are returned. If CA failed non is returned. A user can set ezcadebug to print more information.
Comment
For each requested process variable the corresponding TCL global `Control_Info' array element is reset. The Control_Info variable consists of the following pieces of information :
- status,
- severity,
- precision,
- risc_pad0,
- units,
- upper_disp_limit,
- lower_disp_limit,
- upper_alarm_limit,
- upper_warning_limit,
- lower_warning_limit,
- lower_alarm_limit,
- upper_ctrl_limit,
- lower_ctrl_limit,
- value
If desired a user can extract the substring from the global `Control_Info' variable. Currently, these info are not automatically printed unless a `ezcadebug 2' is issued first.
Example
set x {chademoai1 chademoai2 chademobi1}
ezcadebug 2
ezcainfo $x
ezcadebug 0
set Control_Info(chademoai1)
set Control_Info(chademoai2)
set Control_Info(chademobi1)
This function can be used for getting the value back for a single device. If the get `type' is not specified, the native type is assumed. The ca_pend_io is automatically called for waveform record.
- <pvname> - required, specifies single channel or field name
- <type> - optional, specifies the type of get, defaults to native string type, `double' can be used.
- <nelem> - optional, specifies the no of elements returned or the waveform record
- Return - The native string value(s) or double value(s) obtained from IOC.
Example
ezcagetwf chademowf1
This function can be used for setting the value for a single channel. If the record is an array record (nelem > 1), that is if a waveform record, the string value is put to the waveform record. The ca_pend_io is automatically called for the waveform record.
- <pvname> - required, specifies the channel or field name
- <value> - required, specifies the value array or scalar
- <type> - optional, specifies the type of put, defaults to native string type, `double' can be used.
- <nelem> - optional, specifies the no of elements to be put to the waveform record, defaults to the no of element in the list of `value'
- Return - Returns 0 at normal completion, none if failed.
Example
ezcaputwf chademowf1 { 1 2 3}
Get the triplet value, status, severity back for the requested process variable name.
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- <type> - Optional, use `string' to specify the return value in database native string form instead of double precision form
- Return - Returns VAL,STAT,SEVR if succeeded, or returns none if CA failed.
Example
ezcagetvss chademoai1
Get the value, status, severity, and timestamp string back for the requested process variable name.
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- <type> - Optional, use `string' to specify the return value in database native string form instead of double precision form
- Return - Returns VAL,STAT,SEVR, text string of TS_STAMP if succeeded, or returns none if CA failed.
Example
ezcagetvsst chademoai1
Search the IOC network for the specified list of process variable names
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - None
Example
set x {chademoai1 chademoai2 chademobi1}
ezcasearch $x
Set the timeout will be used by the ca_pend_io function
- <secs> - Required, initially pend_io time is set to 0.5 and 3 seconds for single and list of channels, ezcapendio will reset both to `secs'.
- Return - real value of secs
Example
ezcapendio 2.
Delay for secs in calling ca_pend_event
- <secs> - optional, default to 0.001 seconds
- Return - None is returned.
Example
ezcapendevent 0.5
This command add a change of connection event for the specified channel.
- <pvname> - Required input, process variable name, can be a single process variable name only.
- Return - None
Example
ezcaconnect chademomask1
Set and add the pvname to the monitored list
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- <keyword> - Special keyword is only used for monitoring the waveform record. The valid keyword can be `HEX', `BINARY' or `DECIMAL' for waveform record. It defaults to decimal. The monitored value will be returned in either HEX, BINARY, or DECIMAL form. It is not recommended to monitor a very large waveform record instead use the get command.
- Return - None
For each process variable monitored the name is added to the monitored list and the corresponding TCL global `Control' array element is set. The Control variable consists of four pieces of information VAL, STAT, SERV, and TSTAMP string.
If the waveform record is monitored, in addition of `Control' array element is set, a TCL global `WF' array element is also set for the process variable. It returns the current values detected in the waveform record.
E.g. if `chademoai1' is added to the monitored list, then the global variable `Control(chademoai1)' is set in aps_wish. Whenever a new value is set or put to the channel, the array element `Control(chademoai1)' reflects the new current value, status, severity, and time stamp string of the value.
To use the value from Control(pvname), a user must ensure that pvname is currently monitored.
Examples
ezcasetmonitor chademoai1
set Control(chademoai1)
ezcasetmonitor chademowf6
ezcaputwf chademowf6 {1 2 3 4 5 6}
set Control(chademowf6)
set WF(chademowf6)
Clear the pvname from the monitored list
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - None
Example
ezcaclearmonitor chademoai1
Check and clear the event flag(s) of the monitored channel(s).
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - Returns event flag 1 if at least one new event occurs, return 0, if no new event, and returns none if CA failed.
Example
ezcacheckmonitor chademoai1
Wait for any new event for the specified channel until time out .
- <secs> - Required input, specifies the wait time in seconds
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - Returns 0 if at least one new event occurs, returns -1 if timed out, and returns none if CA failed.
Example
ezcawaitmonitor chademoai1
Get the triplet value, status, severity back for the monitored process variable(s) and clear the new event flag(s) for the monitored channel(s).
- <pvname> - Required input, process variable name, can be a single channel or a list of channels.
- Return - Returns VAL,STAT,SEVR for the requested channel(s), and returns none if CA failed.
Example
ezcagetmonitorvss chademoai1
Set the debug printing level
- <n> - Required input, 0 turns debug off, n specifies the debug level to n
- Return - Returns n
Example
ezcadebug 1
- (Run on a sun4 SPARC)
FUNCTION Microseconds / Iteration
------------------------------------------------------
ezcasearch 500
ezcaconnect 372
ezcasetmonitor 453
ezcacheckmonitor 484
ezcagetmonitorvss 3708
ezcaclearmonitor 469
ezcagetvss 3660
ezcagetvsst 4097
ezcaget 3241
ezcaput 1390
ezcagetenumstrings 4550
ezcagettype 482
ezcagetnelem 479
ezcainfo 4350
ezcagetwf 3811
ezcaputwf 2070
[In above table 1000 iterations were performed on a single PV. ]
FUNCTION LTS.ioc(554 PVs) type Microseconds/iterations
--------------------------------------------------------------
ezcasearch $x 313090 (*)
ezcasetmonitor $x 133750 (*)
ezcacheckmonitor $x 74776
ezcagetmonitorvss $x 152476
ezcagetmonitorvss $x 152476
ezcaclearmonitor $x 76263 (*)
ezcagettype $x 72607
ezcagetnelem $x 84881
ezcaget $x string 206803
ezcagetvss $x string 239824
ezcagetvsst $x string 296612
ezcagetmonitorvss $x 162879
ezcainfo $x 1326867 (*)
[In above table, x contains an array of 544 PVs from a database, 100 iterations were performed, cases marked with (*) only one iteration is performed. ]
FUNCTION PV Nelem Native_Type Microseconds/iteration
--------------------------------------------------------------
ezcagetwf chademowf1 20 DBF_STRING 5223
7292 (*)
ezcagetwf chademowf2 20 DBF_CHAR 4231
6288 (*)
ezcagetwf chademowf3 20 DBF_UCHAR 3856
5366 (*)
ezcagetwf chademowf4 20 DBF_SHORT 4068
5552 (*)
ezcagetwf chademowf5 20 DBF_USHORT 5459
5532 (*)
ezcagetwf chademowf6 20 DBF_LONG 4153
5520 (*)
ezcagetwf chademowf7 20 DBF_ULONG 5669
5726 (*)
ezcagetwf chademowf8 20 DBF_FLOAT 5470
5500 (*)
ezcagetwf chademowf9 20 DBF_DOUBLE 5585
5617 (*)
ezcagetwf chademowf10 20 DBF_ENUM 4121
5418 (*)
ezcagetwf chademowfmax 2000 DBF_DOUBLE 193505
ezcagetwf chademowfmax7 4000 DBF_FLOAT 387273
ezcagetwf chademowfmax6 4000 DBF_LONG 117259
ezcagetwf chademowfmax5 8000 DBF_SHORT 204854
4000 103371
ezcagetwf chademowfmax1 16000 DBF_CHAR 310953
8000 157103
4000 80088
[ In the above table 100 iterations were performed for waveform record, case marked with (*) double precision type is requested. As shown above requested the waveform record as native type is more efficient. Bigger array takes more time to get. Same array size, the time perfomance is propotional to the word size. ]