Tcl-IOC

Tcl-IOC provides a Tcl shell for an EPICS R3.14 IOC. It is a replacement for iocsh that comes with EPICS base. This adds the full capability of a scripting programming language to EPICS iocCore. Access to registered EPICS functions and variables is supported similar to iocsh.

Requirements

Tcl is required and TclX is recommended for its capability to switch from scripting mode to interactive mode. Alternatively, wish, the graphical extension to the Tcl shell, can be used. To build Tcl-IOC, the sources or the development rpm of Tcl (tcl-devel) is required (i.e. the header file tcl.h is needed). To run Tcl-IOC, a run time installation of Tcl and TclX is sufficient.

EPICS R3.14.7 is required (higher versions might also work).

Download the tclioc.tgz package. See below how to install it.

Tcl-IOC has been tested on the following systems:

It has not yet been tested on Windows systems. If you make it run on other systems, feedback is welcome.

Features

Tcl-IOC consistes of a shared library that can be linked with an IOC application and loaded into any Tcl shell (tclsh, tcl, wish, wishx, bltwish, ...) with the load command. Loading the library automatically adds iocCore, including all EPICS functions and variables to the Tcl shell.

Functions

For each registered EPICS function, a Tcl command with the same name is created. Thus, any EPICS function available in iocsh can be called from the Tcl shell. Since iocsh functions have void results, the corresponding Tcl commands normally return an empty string. Many EPICS functions write to stdout, but input and output can be redirected:

< filename

Stdin of the function is read from the file filename which is opened for reading

> filename

Stdout of the function is written to the file filename which is opened for writing (and truncated).

>> filename

Stdout of the function is written to the file filename which is opened for appending.

2> filename

Stderr of the function is written to the file filename which is opened for writing (and truncated).

2>> filename

Stderr of the function is written to the file filename which is opened for appending.

<@ fileId

Stdin of the function is read from fileId which refers to a file, pipe, or socket that must already be opened for reading. (see open and socket)

>@ fileId

Stdout of the function is written to fileId which refers to a file, pipe, or socket that must already be opened for writing or appending. (see open and socket)

2>@ fileId

Stderr of the function is written to fileId which refers to a file, pipe, or socket that must already be opened for writing or appending. (see open and socket)

>$ varName

Stdout of the function is written to the variable varName. Its previous contents are cleared. If the variable does not yet exist, it is created.

>>$ varName

Stdout of the function is appended to the variable varName. If the variable does not yet exist, it is created.

2>$ varName

Stderr of the function is written to the variable varName. Its previous contents are cleared. If the variable does not yet exist, it is created.

2>>$ varName

Stderr of the function is appended to the variable varName. If the variable does not yet exist, it is created.

>$$

Stdout of the function is written to the return value.

2>$$

Stderr of the function is written to the return value.

Note that most EPICS functions also write error messages to stdout instead of stderr.

Variables

Each registered EPICS variable is mapped to a global Tcl variable with the same name. Reading and writing of those Tcl variables is redirected to the corresponding EPICS variable. EPICS variables cannot be unset.

Installing Tcl-IOC

Tcl-IOC comes as a BaseApp-style EPICS R3.14 project. It contains the following files:

tclioc
|-- Makefile
|-- myTclIocApp
|   |-- Makefile
|   |-- example.subs
|   |-- example.template
|   |-- exampleiocsh.tcl
|   |-- myTclIocAppInclude.dbd
|   `-- simpleiocsh.tcl
`-- src
    |-- Makefile
    |-- README
    |-- iocUtil.c
    `-- iocsh.cpp

Unpack the project it in a <TOP> location and run make. This will create a loadable library and an example application. For further information on EPICS projects and <TOP> directories, please refer to the EPICS IOC Application Developer's Guide (download PDF), Chapter 4.

Building a Tcl-IOC application

A Tcl-IOC application is similar to any other EPICS IOC application. The differences are in the Makefile and the startup script. An example application can be found in the myTclIocApp subdirectory.

Makefile changes

1. Instead of a PROD executable, create a LOADABLE_LIBRARY.
   This means, change lines like
   PROD = myApplication
   to
   LOADABLE_LIBRARY = myApplication
   Replace PROD_SRCS, etc. by LIBS_SRCS or myApplication_SRCS.
2. Instead of linking the application to $(EPICS_BASE_IOC_LIBS), link it to tclioc.
   That means replace
   myApplication_LIBS += $(EPICS_BASE_IOC_LIBS)
   with
   myApplication_LIBS += tclioc

Example Makefile

Differences to a standard application Makefile are marked blue.

TOP=../..
include $(TOP)/configure/CONFIG

LOADABLE_LIBRARY = myApplication

DBD += myApplication.dbd
myApplication_SRCS += myApplication_registerRecordDeviceDriver.cpp

myApplication_LIBS += tclioc

include $(TOP)/configure/RULES

Startup script changes

1. Use /usr/bin/tcl (or wherever TclX is installed) as the interpreter. That means the first line should be
   #!/usr/bin/tcl
2. Load the application library into the Tcl interpreter and tell it that it is a tclioc application. Make sure that the library can be found (e.g. set LD_LIBRARY_PATH accordingly):
   load libmyApplication.so tclioc
3. While setting up the IOC as usual (using dbLoadDatabase, myApplication_registerRecordDeviceDriver, dbLoadTemplate or dbLoadRecords, iocInit), it is possible to use Tcl language constructs. This allows loops and conditionals, access to variables, etc.
4. At the end of the script, switch to interactive mode (this is where TclX is required):
   commandloop -prompt1 {puts -nonewline "epics> "}

Example startup script

#!/usr/bin/tcl

load libmyApplication.so tclioc
dbLoadDatabase myApplication.dbd
myApplication_registerRecordDeviceDriver

#create records using TCL programming
set scan "1 second"
for {set n 1} {$n <= 100} {incr n} {
    dbLoadRecords example.template "number=$n,scan=$scan"
}

#set an EPICS variable
set asCaDebug 1

#some EPICS commands with output redirection
set logfile iocboot.log
iocInit > $logfile
dbnr 1 >> $logfile
dbl >> $logfile

# go interactive
commandloop -prompt1 {puts -nonewline "epics> "}