OAG:
EPICS TCL/TK Interface

Original author (et_wish) - Bob Daly
Updated by - Robert Soliday

Table of Contents

Argonne National Laboratory
Advanced Photon Source

1. Introduction

This document describes the tcl command (pv) and command operations (link, linkw, get, getw, put, putq, mon, umon, cmon, info, stat) which are used to interface with EPICS. This release of the CA extension has been tested with tcl releases 8.3 and 8.4. The reader of this document is assumed to be familiar with Tcl/Tk.

2. Loading CA extension

Start interactive use of the Tcl/Tk interpreter by typing:
oagwish
package require ca

3. Command Syntax

The command syntax consists of three or more words, with the first three words having the same meaning in each command. The words after the first three words are dependent on the type of command issued. A command example follows: 

 pv link {ai1 ai2 ai3} {IOC:ai1 IOC:ai2 IOC:ai3}
Examples of all supported operations:

  • pv link {c0 ai1 ai2 ai3 ai4} {T:calc T:ai1 T:ai2 T:ai3 T:ai4}
  • pv unlink ai1
  • pv get c0
  • pv getw ai1 11.1
  • pv put ai1
  • pv putw ai2
  • pv putq ai3
  • pv info {c0 ai1 ai2 ai3 ai4} {state status severity time units}
  • pv stat ai1
  • pv mon {c0 ai3 ai4} {puts "I can execute a script for you"}
  • pv umon ai1
  • pv cmon ai1

    • 4. pv Command Operations

    link, linkw, unlink

    Syntax: 
     pv link(w) tclVars iocVars <optional timeout>
    Description: Establish a link at run-time between tcl variables and process variables in existing IOC databases. The tcl variables are automatically created during the operation. For string and enum process variables, the tcl type created will be a string.(1) For float and double process variable types, the tcl variable type created is a double. For all other process variable types the tcl variable type is integer. A tcl variable may be subsequently linked with a different process variable (i.e. relinked). When relinked the old link is completely removed. A tcl variable may also be unlinked. Return:

    Comments: The user must always check the state of the link after link and linkw type commands, using either the `stat' or `info' command types. The state must be `OK' (see stat and info type commands) before further operations on the tcl or process variable(s) are made. When the link(w) is first issued `state' is set to `IO'. If a link to a database process variable is successful the state changes to `OK'. If the link was unsuccessful the state will be something other than `IO" or `OK', i.e. NC (Never Connected), LC (Lost Connection), RD (No Read Access), WR (No Write Access). For blocking links, i.e. linkw, the state can be checked immediately after the linkw command is issued. For non-blocking links, i.e. link, the state may still be in the `IO' state after the link command is issued and subsequently (asynchronously) change to another state. For the non-blocking command it is up to the user code to wait until a `state' transition or timeout has occurred. I recommend using blocking links because of their coding simplicity.

    Examples of correct forms of link(w), unlink
  • pv link ai1 IOC:beamVoltage
  • pv linkw {ai1 ao1 bi1} {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
  • set varList{ai1 ao1 bi1}
  • set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
  • pv linkw $varList $iocList
  • pv link $varList $iocList
  • if { [pv linkw ai1 IOC:beamVoltage] == 1} puts stdout $errorCode
  • pv unlink ai1
  • pv unlink $varList
    • 


    
get, getw
    
Syntax:

     pv get(w) tclvars <optional timeout>
    
Description: Update the linked tcl variables to the current values
stored in the IOC databases.
Return:

    

    

Comments: The user should always check state of the link after get
and getw type commands using either the `stat' or `info' command types.
The state must be `OK'. Additionally the severity of the process variable
should be checked to, at least, make sure that it is not INVALID. I recommend
using the `stat' command type for checking.
    

    
Examples of correct forms of get(w):

    

  • 
 set varList {ai1 ao1 bi1}
    • 


  • 
 set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
    • 


  • 
 pv link $varList $iocList
    • 


  • 
 pv get $varList
    • 


  • 
 pv getw $varList
    • 


  • 
 pv get {ai1 ao1}
    • 


  • 
 pv getw {ao1 bi1}
    • 


  • 
 pv get bi1
    • 


  • 
 pv getw bi1
    • 


    
put, putw, putq
    
Syntax:

     pv put(w,q) tclvars <optional timeout>
    
Description: Update the current process variable values stored in
the IOC databases to the linked tcl variable values. The put and putw types
require notification from the IOC that record processing has completed
for all the linked variables in the command. The putw blocks until all
notifications have been received. The putq returns to the application as
soon as the proper requests have been forwarded to the IOC. I recommend
using the putq type unless there is a compelling reason for wanting to
wait for record processing associated with a process variable to complete.
    

    
Return:

    

Comments: User should always check state of the link after put,
putw, and putq type commands. The state must be `OK'. I recommend using
the `stat' command.
    

    
Examples of correct forms of put(w,q):

    

  • 
set varList {ai1 ao1 bi1}
    • 


  • 
set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
    • 


  • 
pv link $varList $iocList
    • 


  • 
pv put ao1
    • 


  • 
pv putw ao1
    • 


  • 
pv putq ao1
    • 


  • 
pv put {ai1 ao1 bi1}
    • 


  • 
pv putw {ai1 ao1 bi1}
    • 


  • 
pv putq {ai1 ao1 bi1}
    • 


  • 
pv put $varList
    • 


  • 
pv putw $varList
    • 


  • 
pv putq $varList
    • 


    
mon, umon, cmon
    
Syntax:

    

  • 
 pv mon tclVars <optional script>
    • 


  • 
 pv umon tclVars <optional script>
    • 


  • 
 pv cmon tclVars
    • 


    


    

    
Description: Establish/Clear an EPICS database monitor for the
linked tcl variable(s). The linked tcl variable is updated immediately
with umon. The use of umon is convenient when TK widgets are used
to display the value of a variable. However, with mon, the linked tcl variable
is updated only when the tcl variable is read. An optional tcl script,
when defined in the command, will be executed whenever a monitored event
is received from an IOC. Using the optional script, the user can implement
an completely event driven application.
    

    
Return:

    

    

Examples of correct forms of mon umon, and cmon:

    

    

  • 
 set varList {ai1 ao1 bi1}
    • 


  • 
 set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
    • 


  • 
 pv link $varList $iocList
    • 


  • 
 pv link {c0 ai1 ai2 ai3 ai4} {T:calc T:ai1 T:ai2 T:ai3 T:ai4}
    • 


  • 
 pv mon $varList
    • 


  • 
 pv mon $varList {puts "Print this every event"}
    • 


  • 
 pv mon $varList tclProcedureName
    • 


  • 
 pv umon ai1
    • 


  • 
 pv umon ai1 {puts "Print this every event"}
    • 


  • 
 pv mon ai1 tclProcedureName
    • 


  • 
 pv mon {ai1 bi1}
    • 


  • 
 pv mon {ai1 bi1} {puts "Print this every event"}
    • 


  • 
 pv mon {ai1 bi1} tclProcedureName
    • 


  • 
 pv cmon $varList
    • 


  • 
 pv cmon ai1
    • 


  • 
 pv cmon {ai1 bi1}
    • 


    
info
    
Syntax:

     pv info tclVars requestedInfo
    
Description: Obtain information in the form of a list of lists about
linked tcl variables stored in the interface. Any or all of the following
information may be requested in any order. Information is available for:

    

    

Return:

    

    

Examples of correct forms of info:

    

    

  • 
set varList {ai1 ao1 bi1}
    • 


  • 
set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
    • 


  • 
pv link $varList $iocList
    • 


  • 
pv link {c0 ai1 ai2 ai3 ai4} {T:calc T:ai1 T:ai2 T:ai3 T:ai4}
    • 


  • 
pv getw $varList
    • 


  • 
pv info ai1 state
    • 


  • 
pv info ai1 {state ioc name units severity status}
    • 


  • 
pv info ai1 {units state name ioc}
    • 


  • 
pv info $varList {state severity status time}
    • 


  • 
pv info $varList severity
    • 


  • 
pv info {ai1 bi1} {name choices hopr lopr precision units lo lolo
ioc access}
    • 


    
stat
    
Syntax:

    

     pv stat tclVar associative_array_name
    
Description: Obtain state, status, severity, and time information
about a single process variable as elements (state, status, severity and
time) of an tcl associative array named in command. The array is created
if it doesn't exist.
    

    
Return:

    

    

Comments: In tcl scripts `stat' provides a more convenient command type
than `info'.
    

    
Examples of correct forms of stat:

  • 
set varList {ai1 ao1 bi1}
    • 


  • 
set iocList {IOC:beamCurrent IOC:outputCurrent IOC:beamStatus}
    • 


  • 
pv link $varList $iocList
    • 


  • 
pv link {c0 ai1 ai2 ai3 ai4} {T:calc T:ai1 T:ai2 T:ai3 T:ai4}
    • 


  • 
pv getw $varList
    • 


  • 
pv stat ai1 arrayName1
    • 


  • 
pv stat bi1 arrayName2
    • 


  • 
pv stat ao1 arrayName3
    • 


  • 
set arrayName1(state)
    • 


  • 
set arrayName2(severity)
    • 


  • 
set arrayName3(status)
    • 



    
5. Variable Mapping : EPICS Native->TCL
    


    

    
EPICS NATIVE TYPE

TCL TYPE

    


    
string

string

    


    
enum( with string elements)

enum string

    


    
enum( no string elements defined)

value string

    


    
char

long

    


    
integer

long

    


    
long

long

    


    
float

float

    


    
double

double

    

    


    
6. Usage
    
There are typically only three steps needed to communicate with an EPICS
database:

    

    

The user must keep in mind that command types link, get, and put involve
transferring data over a network which means that the user must check that
the network operation has successfully completed. The return result (either
0 or 1) of these command types together with the stat/info command type
are used to insure that the operation was successful. In addition, when
the command type is a get the user must insure that the data is valid (the
network operation might have succeeded but the GPIB instrument timed out
during a GPIB read). The stat/info command type is also used to check the
validity of data.
The user must keep in mind that both the process variable in an
IOC and the tcl linked variable can change at any time and are only
synchronized only during a get or put type command.
Use of lists is encouraged in link, get, put and mon types to
improve the efficiency of the network communications.
Use of mon types is encouraged for process variables which change
infrequently (at least less frequently than referenced in script) and for
applications which are designed to be event driven.
When checking the state, status, severity, and time in scripts,
it is usually easier to use the stat command type. Info works well for
interactive use.
The put and putw command types require notification from the IOC
that the record has processed before completion. It is much better to rely
on readback process variables to ensure that a put operation has successfully
completed. With a readback available use of putq is preferred. The putq
does not require IOC notification before completing.
When using asynchronous forms of link, get and put, the application
must give the X-event loop time to process before each check on completion.
The tcl/tk event loop processes whenever user code is not running, or whenever
certain tck/tk command are issued as described in the tcl/tk documentation.
Otherwise, the application code will end up in an endless loop testing
for something (state, status, severity, time) that never gets updated.
In the script associated with monitors, THE SYNCHRONOUS COMMAND
TYPES LINKW, PUTW and GETW SHOULD NOT BE USED (this is a network software
limitation related to code reentrancy).


    

    
Footnotes
    


    

    
(1)
    


    
For ENUM database process variables which DO NOT have strings defined,
use of numbers is supported.
    


    
(2)
    


    
`state' is a two-character string, whose possible values are: NC->NeverConnected,
LC->LostConnection, RD->NoReadAccess, WR->NoWriteAccess, IO->I/OinProgress,
OK->OK