Native SNOMAN commands

Now it is time to formally describe all the Native i.e. built in, SNOMAN commands. Note that all commands and keywords are case insensitive and may be truncated so long as they remain unambiguous. The character `*' is a comment delimitor, anything after it is ignored, as are blank lines.

Get into the habit of using comments freely. They get echoed into the log file and are a permanent record of the task you doing!

Any comment that starts in column 1 with:-

*Warning:

will be taken to introduce a serious warning. The remainder of the line is sent to a serious message warning system and will printed to the screen at the start of execution and again at the end of termination.

The @ Command.

Syntax: @filename

Example: @/usr/west/work/my_job

This command directs SNOMAN to take subsequent commands (which can include further @ commands) from the file specified. When the file is exhausted command processing will resume in the current file. If the file name does not contain a dot then the default extension .cmd is assumed.

The DEFINE Command.

This is currently used for starting a multi-line definition of the programmable event loop which is discussed in detail in section 9. A summary is given here for completeness.

Example:

  DEFINE event_loop
     call inp              * Input an event
     call flt(1)           * Apply filter test 1: nhits>40
     if_not_ok quit_event  * Quit event if test fails
     call ftt              * Try to fit
     if_ok goto fit_ok     * If fit successful, jump to fit_ok
     call out(3)           * Output fit failures on stream 3
     quit_event            * Quit the event
  fit_ok:                  * A label
     call out(2)           * Output fit successes on stream 2
  END_DEF

An event loop program tells SNOMAN how to process each event and is an alternative to the less sophisticated $processor_list command. The program appears between the lines DEFINE event_loop and END_DEF, and consists of labels, conditions and commands. Commands can be one of the following:-

call proc	Call processor proc
call proc(arg1,arg2,...)	Call processor proc with arguments
continue	Null command
goto label	Goto label
quit_event	Quit the event
quit_job	Terminate SNOMAN

If there is a preceeding condition (if_ok or if_not_ok) then the command is only executed if the return code from the last processor call satisfies the condition.

The event filter (FLT) plays an important role in the programmable event loop with the results of filter tests being used to steer the processing along different paths. It supports arguments in an event loop program that specify which tests to apply. The result is passed back as a processor return code (OK=true, NOT_OK=false). Tests are defined in FLTR titles banks and can be set up quickly with symbolic commands, such as

$enable_test 1
$define_test 1 $line_1 'nhits float_equals EV+$KEV_NPM:40 999;'

which tests for ( $40\leq N_{hits}\leq999$). See section 9.1 for more details on filter tests.

The ECHO/NOECHO Command.

These commands determine whether, after translating symbolic commands (see section 3.5.3), the translated line is copied to the standard output before processing. Initially echoing is on. Use echo to help learn what banks you are modifying when you use symbolic commands.

The END Command.

This command terminates command processing at once, even if the command appears in a file that was invoked with the @ command.

The FILE Command.

Syntax: FILE su_id stream_no file_spec options

Example: FILE INP 1 input.dat skip=5 max=100

Example: FILE OUT 1 output.dat device=$disk format=$zdab_only

This command is used to associate a file with a Software Unit (see 11.1), and in particular, INP and OUT, the event input and output processors. The FILE command is discussed in detail in section 3.9.2.

The HELP Command.

This gives brief summary of the available SNOMAN commands.

The QUIT Command.

This quits the program at once.

The SET BANK Command.

Syntax: SET BANK bank_name bank_no WORD bank_adr $\{$OFFSET$\}$ offset TO value value ...

Example: SET BANK JOB 1 WORD 2 TO 200

Example: SET BANK MCPI 1 WORD 67 OFFSET 9 TO 40 1. 1000000. 1.

This command can be used to change one or more words in a titles bank starting at the bank address specified. Up to 10 values can be provided which can be any of the following mixed in any order:-

• A signed integer. By default integers are assumed to have decimal radix. You can specify binary, octal or hexadecimal by appending the letters b, o, and h repectively e.g. 11001b, 777o, 0ffh. Note that for hexadecimal the first character must be numeric, so add a leading 0 if the first digit would otherwise be greater than 9.

• A signed floating point number with optional exponent e.g. 1.23e-6.

• A character string within single quotes. To store a quote double it up e.g. 'Don''t'. SNOMAN pads with blanks so that the number of characters is an exact multiple of 4 and then stores 4 characters per word in the bank.

The OFFSET clause is optional; if present, the offset it declares is added to the bank address. It is unlikely that user will want to use this feature directly, but it is useful in symbolic commands that access titles banks that form tables. Then the bank address can be used to select the row and the offset to select the column for that row, or vice versa.

The TITLES Command.

Syntax: TITLES filename

Example: TITLES /usr/west/work/my_titles

This command directs SNOMAN to read a titles file containing one or more titles banks. If the file name does not contain a dot the default extension .dat is assumed.