The Tcl ring access package allows Tcl scripts direct access to the both local and remote ring buffers used to distribute data through the NSCL data acquisition system. This chapter will describe:
How to incorporate the ring access package in your scripts
Software patterns you may need to keep in mind when using this package.
The ring access package is a loadable package that is installed in the TclLibs directory tree of the NSCLDAQ installation directory tree. To use the package you must add the TclLibs directory tree to the Tcl package search path and you must execute the appropriate package require in your script
Starting with NSCLDAQ-11.0, the daqsetup.bash shell script can be run to define several useful environment variables that let you locate components of the NSCLDAQ system. It is recommended that you source this script in your .bashrc startup script to make these environment variables available to all bash sessions.
Once these environment variables are loaded the following Tcl script fragment will incorporate the Tcl ring access package in your script:
Example 57-1. Incorporating the ring access package into a Tcl script
lappend auto_path [file join $::env(DAQROOT) TclLibs]
package require TclRingBuffer
In the example above, the first command appends the TclLibs directory to the library search path. It make use of the DAQROOT environment variable defined by the daqsetup.bash script. DAQROOT points to the top level of the NSCLDAQ installation directory in which daqsetup.bash lives.
The second line actually requests the interpreter to load the package into the interpreter. The package also intializes and registers its commands at ths point.
Once registered, the package provides a command ensemble with the base command ring sub commands allow you to connect to specific rings, get data from those rings and disconnect from rings. The package allows you to connect to several rings simultaneously if your application requires it.
Detailed information about the ring command ensemble can found in the manual page ring.
The subcommands are:
Attaches to a ring buffer. The ring buffer is specified as a URI of the usual form (e.g. tcp://localhost/fox)
Detaches from a ring buffer you've already attached to. The ring buffer is again specified as a URI of the usual form. The package remembers which URIs represent rings that have been attached and will emit an error if you attempt to detach a ring that has not been attached.
Note that the URI used to detach a ring must be textually identical to the URI used to attach it. For example, tcp://LOCALHOST/fox won't match the ring described in the attach sub-command description.
Gets the next ring item from a ring buffer. A URI is used to specify the ring, which must already be attached. The command blocks until an appropriate ring item is available.
In addition to specifying a ring, you can optionally specify a list of ring item types. If specified, only those item types will be accepted, and all other item types will be skipped.
The ring items returned from ring get are transformed to Tcl dicts which makes them very easy to manipulate within Tcl programs. The actual dicts returned by each ring item are described in the manual page .