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