OAG:
EPICS TCL/TK Interface

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

Table of Contents

  1. 1. Introduction
  2. 2. Loading CA extension
  3. 3. Command Syntax
  4. 4. pv Command Operations
  5. 5. Variable Mapping : EPICS Native->TCL
  6. 6. Usage
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:

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

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):

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):

mon, umon, cmon

Syntax:

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 a completely event driven application.

Return:

Examples of correct forms of mon, umon, and cmon:

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:

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 a 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:

5. Variable Mapping : EPICS Native->TCL

EPICS NATIVE TYPE TCL TYPE
stringstring
enum (with string elements)enum string
enum (no string elements defined)value string
charlong
integerlong
longlong
floatfloat
doubledouble

6. Usage

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

  1. Establish a link between a tcl variable and a process variable (sometimes called channel) and check that the link has been established OK. This operation uses a link type and an info or stat type.
  2. Either update the tcl variable to reflect the current value of the process variable via a get type command or update the process variable to reflect the value of the tcl variable via a put type command and check that the update has completed OK. This operation uses a get or put type and a stat type.
  3. In the case of the get type operation, ensure that the data received from the process variable is valid (i.e. not INVALID). This operation uses a stat/info type.

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 ensure that the operation was successful. In addition, when the command type is a get the user must ensure 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 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 tcl/tk commands 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/O in Progress, OK -> OK