Using the Run Time Sequencer

 

 

 

 

In the previous chapter you learned how to create and compile some simple state programs. In this chapter you will be introduced to the run-time sequencer so that you can execute your state program.

VxWorks-specific instructions

Note that the latest sequencer version has not, at the time of writing, been fully checked out under VxWorks.

Loading the sequencer

The sequencer is unbundled from EPICS base and so must be loaded separately. The sequencer is loaded into an IOC by the VxWorks loader from object files on the UNIX file system. Assuming the IOC's working directory is set properly, the following command will load the sequencer object code:

ld < pvLibrary

ld < seqLibrary

Loading a State Program

State programs are loaded into an IOC by the VxWorks loader from object files on the UNIX file system. Assuming the IOC's working directory is set properly, the following command will load the object file "example.o":

ld < example.o

This can be typed in from the console or put into a script file, such as the VxWorks start-up file.

Executing the State Program

Let's assume that the program name (from the program statement in the state program) is "level_check". Then to execute the program under VxWorks you would use the following command:

seq &level_check

This will create one task for each state set in the program. The task ID of the first state set task will be displayed. You can find out which tasks are running by using the VxWorks " i " command.

Examining the State Program

You can examine the state program by typing:

seqShow level_check

This will display information about each state set ( e.g. state set names, current state, previous state). You can display information about the control system variables associated with this state program by typing either of:

seqChanShow level_check

seqChanShow level_check, "DTL_6:CM_2:ai1"

seqChanShow level_check, "-"

You can display information about monitor queues by typing:

seqQueueShow level_check

The first parameter to seqShow , seqChanShow and seqQueueShow is either the task identifier (tid) or the unquoted task name of the state program task. If the state program has more than one tid or name, then any one of these can be used. The second parameter is a valid channel name, or " - " to show only those channels which are disconnected, or " + " to show only those channels which are connected. The seqChanShow and seqQueueShow utilities will prompt for input after showing the first or the specified channel; enter <Enter> or a signed number to view more channels or queues; enter " q " to quit.

If you wish to see the task names, state set names, and task identifiers for all state programs type:

seqShow

Stopping the State Program Tasks

You can no longer directly delete state program tasks. Instead, you must use seqStop .

seqStop level_check

The parameter to seqStop is either the task identifier (tid) or the unquoted task name of the state program task.

A state program can no longer delete itself.

Unix-specific instructions

Executing the State Program

Under Unix, you execute the state program directly. You might type the following:

level_check

Once the state set threads have been created, the console remains active and you can type commands as described below.

Examining the state program

The following commands can be issued under Unix (hit " ? " to obtain the list):

commands (abbreviable):

i - show all threads

all - show all sequencers

channels - show all channels

+ - show conn. channels

- - show disc. channels

queues - show queues

statesets - show state-sets

<EOF> - exit

As you see, all commands can be abbreviated to a single character.

Stopping the State Program Tasks

A state program may be killed by sending it a SIGTERM ( Ctrl-C ) signal (this is an untidy exit, but who cares?) or by entering an <EOF> ( Ctrl-D ) character. The latter calls seqStop and is a tidy exit.

Specifying Run-Time Parameters

You can specify run-time parameters to the sequencer. Parameters serve three purposes:

  1. macro substitution in process variable names,
  2. for use by your state program, and
  3. as special parameters to the sequencer.

You can pass parameters to your state program at run time by including them in a string with the following format:

" param1 = value1 , param2 = value2 , ... "

This same format can be used in the program statement's parameter list (See State Program). Parameters specified on the command-line override those specified in the program statement.

VxWorks

For example, if we wish to specify the value of the macro "unit" in the example in the last chapter, we would execute the program with the following command:

seq &level_check, "unit=DTL_6:CM_2"

Unix

This works just the same under Unix. The above example becomes:

level_check "unit=DTL_6:CM_2"

Access within program

Parameters can be accessed by your program with the function macValueGet , which is described in See macValueGet. The following built-in parameters have special meaning to the sequencer:

debug = level

Sets a logging level. level-1 is passed on to the PV API. Can be used in user code.

logfile = filename

This parameter specifies the name of the logging file for the run-time tasks associated with the state program. If none is specified then all log messages are written to stdout .

name = thread_name

Normally the thread names are derived from the program name. This parameter specifies an alternative base name for the run-time threads.

priority = task_priority

This parameter specifies the initial task priority when the tasks are created. The value task_priority must be an integer between 0 and 99 (it's ignored under Unix).

stack = stack_size

This parameter specifies the stack size in bytes (its use is deprecated, and it is in any case ignored under Unix).

Sequencer Logging

The sequencer logs various information that could help a user determine the health of a state program. Logging uses the errlogPrintf function and will be directed to the IOC log file if the IOC log facility has been initialized. Under VxWorks this is done automatically but under Unix it must be done by the programmer. This can be done in the main program (if you are writing it yourself) or in the entry handler, which is executed in the context of the first state set before the remaining state sets have been created. For example:

entry {

#ifdef UNIX

%%#include "logClient.h"

iocLogInit();

#endif

}

The programmer may log information using errlogPrintf directly or else by using the seqLog function. By default, seqLog output goes to stdout , but it may be directed to any file by specifying the logfile parameter as described above.

What Triggers an Event?

There are five types of sequencer event:

When one of these events occur, the sequencer executes the appropriate when statements based on the current states and the particular event or events. Whenever a new state is entered, the corresponding when statements for that state are executed immediately, regardless of the occurrence of any of the above events.

Prior to Version 1.8 of the sequencer, event flags were cleared after a when statement executed. Currently, event flags must be cleared with either efTestAndClear or efClear , unless the -e compiler option was chosen.