EDOC081

EUROGAM PROJECT

NSF DATA ACQUISITION SYSTEM EUROGAM Event Builder Language

Edition 1.1 September 1992

Nuclear Structure Software Support Group Liverpool University

Contents

1 Introduction 2

2 Data considerations 2 2.1 Groups and Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Trigger Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Single Itemnames vs Group Itemnames . . . . . . . . . . . . . . . . . . . . . . 4 2.4 Local Variables and Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Organisation 4

4 Command Syntax 6

5 Input Definitions 7

6 Output Definitions 9

7 Variable and Constant Initialisation 11

8 Commands 12 8.1 Arithmetic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8.2 Increment Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.3 Decrement Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.4 Moveqq Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 8.5 If … Else Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 8.6 Whenever Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 8.7 Reject Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 8.8 Suppress Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 8.9 Stream Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

9 Reserved Words 22

10 Example 1 23

A Appendix on Suppression File Format 25

EUROGAM Event Builder Language

John Cresswell and Linda Pratt

Edition 1.1 September 1992

1 Introduction

The EUROGAM project has defined a list of general actions for the event builder to process, together with suggestions of items it should not. It has been stated that it will be necessary to provide support for Compton suppression, new word formation, event filtering and simple arithmetic. It has also been stated that the event builder will not support operations that are not 100% reliable, such as gain matching and ballistic deficit correction.

The prime function of the event builder must be to build events containing the defined set of parameters in the defined format. There will need to be some consistency checking on the quality of events processed. For example, notification of parameter words that are not expected. In this case the user has wrongly identified the set of parameters to be collected, or the hardware has generated corrupt information. These checks are incorporated automatically into the event builder software and are not under the control of the user. (This document deals only with user-specific requirements. It will become the user manual for the language and is not intended as a complete technical manual.)

A second criterion for event builder processing would be to reduce the data volume for onward shipment. Since the event builder has to process 100% of a high data volume (by definition) then any processing has to be simple and effective. This should be remembered when the user defines the commands to be executed.

A third criterion might be to prevent confusion for the physicist as to what kind of processing should be done in the event builder and what in the sorter (see “EUROGAM Sort Language” (J. Sampson, EDOC033)). This should be achievable by limiting the functionality of the event builder and making the user interface different.

The efficiency of computation required to cope with the level of processing necessary suggests that code has to be specific to the EUROGAM array. Then the known structure of the array and the input format of the data can be used to maximise the efficiency of the software.

2 Data considerations

The document entitled “EUROGAM Hardware Event Format Usage” (J. Cresswell, EDOC064) describes the structure of the data stream on input to the event builder. The document describes two types of parameter – system control words and user data words. All parameters have the same general format (i.e. a 32 bit word divided into address and data fields). The system control words are removed by the event builder software, leaving only the data words for the user to deal with, i.e. the user is not concerned with which ROCO produced what data words.

2.1 Groups and Items

Each data word (or item) has a unique 14 bit address which is written into the data acquisition hardware during the set-up phase. In order to make the processing of the data words easier, it has been decided to divide the address logically into two parts: an 8 bit groupnumber and a 6 bit itemnumber. The repeated structure of the array apparatus is such that most parameters expected by the EUROGAM acquisition system will naturally fall into groups. In particular, the set of data from a single Ge and associated BGO detectors can be considered as a group of parameters to be treated together. For each Ge detector the associated group will have a maximum of 7 parameters or items with itemnumbers running from 0–6. Each group has a groupnumber. Each event will consist of several such groups preceded by a trigger or system group (number 255). Extra data acquisition devices (e.g. the recoil mass separator, FIFI, inner balls, …) will each provide a group of parameters with its own unique groupnumber.

Many of the groups described above will be identical because they all have the same type of data that is to be treated similarly. This suggests a further conceptual organisation of the data into sets of groups that are to be treated similarly. Each such groupset can be given a groupname in the language via a group format specification (§5). Each groupset covers a range of groupnumbers, thus allowing, say 45 identical Ge groups to be specified in one statement. In the same statement, itemnames are associated with the itemnumbers in a particular groupset, so avoiding the need for the user to refer to addresses. This ordering of parameters into associated groups should make the processing easier to accomplish.

Several of the functions to be applied to each event will be group oriented. For example, the sum energy calculation will include the same words from each of the Ge groups. Also, a typical operation may be to filter on all Ge TDC words – again the same operation is performed on the same word from each group.

2.2 Trigger Group

The trigger group is the only fixed group to appear in every event. The groupnumber will always be 255. The parameters available from the trigger module are more fully described in “EUROGAM Trigger System” and “EUROGAM Master Trigger Module” (I. Lazarus, EDOC022 and EDOC055). Following is a list of the data words available, but not necessarily activated, in the trigger group:

item 48: Trigger type

item 49: Raw Ge sumbus ADC

item 50: Suppressed Ge sumbus ADC item 51: BGO sumbus ADC item 52: External sumbus ADC

Note the items for the trigger group are numbered starting from 48 (@30 in hex), rather than from 0 as for other groups input to the event builder. When the trigger group is written to output, then its items will be numbered implicitly from 0, as for all the other groups.

The trigger type parameter specifies which set of fast trigger acceptance conditions were valid for the event. This parameter can be passed through to the output trigger group unaltered, or it may be changed in the event builder subject to software filtering conditions.

This provides a mechanism for tagging events for later separation to different (tape) storage streams.

2.3 Single Itemnames vs Group Itemnames

The itemnames introduced in §2.1 may actually describe several items of data. These are termed group itemnames. It is possible to associate an itemname with an address specified explicitly and uniquely (see §5). This is a single itemname. An item is an item, no matter how it is specified, but the way the names are used is slightly different. Most of the parameters from an experiment will fall into groups. Groupsets with only one groupnumber and one group itemname are permitted.

2.4 Local Variables and Constants

A local variable is a variable that the user may define to perform calculations. It is local in the sense that it is entirely confined to the event builder: it is not expected as input and is never needed as output, unlike the items, etc described above. A local variable does not have an address associated with it.

There is the facility in the language to initialise the value of a variable at the start of each event (§7). Generally, however, a local variable is introduced by using it in a statement and is automatically initialised to zero at the start of processing each event.

Constants may also be declared. The value of a constant is set once during the set up phase and is local in the same way that a variable is.

3 Organisation

In order to define the operation of the event builder the user has to create a text file using any favourite text editor. The text file will be read by a program (compiler) to generate the software required. The specification of the language can be found in the following pages. A quick reference card for the syntax of the language is available in the document entitled “Reference Card for EUROGAM Event Builder Compiler” (L. Pratt and J. Cresswell, EDOC082).

The text file is essentially free format, subject to starting each separate command on a new line. The file is divided into 4 sections with the following titles, and in the following order:

input formats

Describes what items are expected as input to the event builder. output formats

Describes how the items are to be output. values

To initialise the user’s local variables and constants.

This section is optional. commands

Any processing required.

The file is terminated with the statement:

finish

The file specifies the expected input, what may be required as output from the event builder and what to do the data to turn the one into the other. However, the formats sections described the maximum set of data to be handled; only a subset of this data will be present in a given event. To handle this situation, the whenever command should be used (§8.6). It defines sets of commands to be executed for each group present that belongs to a specified groupset. It tests the address of items. An if statement (§8.5) can be used in one of 2 ways, either to test the data value of items, variables and constants or to test whether an item is present in the the event.

The output of a group is performed by associating common names and then ordering the items according to the output format. Output is performed by the stream command or by default on reaching the end of the event processing (see §8.9).

As processing is carried out, parts of the event may be discarded using the reject command (§8.7) according to whatever criteria the user sets. (The event may also be rejected altogether). This prevents output of the rejected data when it comes to using a stream command. The data rejected is no longer accessible via subsequent commands and has essentially been discarded. The suppress command (§8.8) is an exception to this statement. It accesses hit pattern words from groups that have been rejected earlier on in the processing. The data is, therefore, still present in the memory, even when it has been rejected.

4 Command Syntax

Within the syntax definitions, the following conventions are followed: All substitutable components are specified as < ⋯ >, for example <name>, <address>, etc… Where more than one occurrence of a component is possible, the repeat specifier is denoted as a lower case “r” following the component, for example <name>r .

Statements All statements must begin on a new line. Most statements are short enough to occupy only one line and it is recommended that they do so if possible. The syntax will allow longer commands to be continued on successive lines, but line breaks are only allowed at points between specified command components. Blank lines between (but NOT in the middle of) statements are simply ignored. Unnecessary white space between command components is also ignored.

Names All names consist of between 1 and 8 alphanumeric characters from the set A–Z, a–z, 0–9 and underscore( ). The first character must be alphabetic.

Case The compiler is not case-sensitive. For example, the forms MRAW, Mraw and mraw are all treated as the same name.

Numbers Only integers will be handled by the event builder. Numeric values may take any of the following forms:

Decimal integer 0 25 -33 Binary integer %00001110001 Hexadecimal integer @ffff @00001234

For all three integer formats the number of characters is variable, and assumes the least significant digit is to the right. The maximum number of digits accepted is 32 for the binary representation, 10 for the decimal representation and 8 for the hexadecimal representation. These limits are all subject to generating a legal 32 bit integer value.

Comments Comments may be incorporated into the text subject to the following rules. Any text following an exclamation mark (!) up to the end of the line is ignored by the command compiler. Hence whole lines or part of lines after commands may be used for commenting the text.

5 Input Definitions

The user must specify the set of parameters expected to be received from the data acquisition hardware. This specification relates a user-defined name to a particular data acquisition channel address. The address is the 14 bit value as defined in other documentation.

Input Section Syntax

input formats

The input section consists of the above statement, which should be the first statement in the EUROGAM event builder language source file (excluding comments), followed by one or more format specification statements. The order in which things are specified in the input section is not significant.

Format Specification Syntax

<item-name> <address>

or

group <group-name> [<range>] (<item-list>)

where:

<item-name> is a user-provided name for a parameter,

<address> is the 14 bit hardware address of the parameter, <group-name>is a user-provided name for a group of parameters, <range> is the set of groupnumbers and <item-list> is a list of <item-name>s separated by commas.

The set of groupnumbers may be specified as a single number, as an inclusive range of consecutive numbers i : j (where i < j) or a mixture of both, for example [5,7:15,31:46]. The group ranges should not overlap, neither should the same groupnumber be declared in different groupsets, i.e. each groupnumber should be unique within a given groupset, and within the input formats section.

The itemnames specified in the group itemlist should not clash with each other, itemnames specified in other groupsets, itemnames declared using the single item format (the first format statement type given above) or groupnames, i.e. itemnames and groupnames should be unique within the input formats section.

The group statement implicitly declares consecutive item numbers for the group items. Sometimes, there may be missing item numbers from the expected list, for example, the trigger words can be activated or inactivated independently of one another. To facilitate this, a keyword blank may appear in <item-list>. It is used as a spacer instead of an <itemname>. The <item-list> may contain the keyword several times, but it is an error for it to consist entirely of spacers. The keyword should not be used as the last element in <item-list>. The keyword blank is thus a reserved word and may not be used for any other purpose. It is not an <item-name>: for example, references to “blank” in an expression (see §8.1) will cause an error.

Example:

         TAC @0103
         GROUP TRG[255](PARAM1, BLANK, PARAM3, PARAM4)
         GROUP GERM[1:70](E1,E2,T1,EBGO,TBGO,HIT)

Valid line break points:

• after the right square bracket (]) following <range>,

• after one of the commas (,) in <item-list>.

6 Output Definitions

The user must specify the set of parameters to be written to the output event buffer. The list of parameters to be output may include all or a subset of those input together with any new parameters created during event building. If an item in the input parameter list is also specified in the output list then it must remain in the same groupnumber. Names used as item or group names in the input definitions may not be used as group or item names respectively in the output definitions. The syntax is similar to that for the input formats section. The order in which things are specified in the output section is the order in which they will be written to the output buffer (if the data is present in the event).

Output Section Syntax

output formats

The output formats section follows on from the input section and consists of the above statement, followed by one or more format specification statements.

Format Specification Syntax

<item-name> <address>

or

group <group-name> [<range>] (<item-list>)

where:

<item-name> is a user-provided name for a parameter, <address> is the 14 bit hardware address of the parameter, <group-name>is a user-provided name for a groupset, <range> is the set of groupnumbers and <item-list> is a list of <item-name>s separated by commas.

The set of groupnumbers may be specified as a single number, as an inclusive range of consecutive numbers i : j (where i < j), or a mixture of both, for example [5,7:15,31:46]. The group ranges should not overlap, neither should the same groupnumber be declared in different named groupsets, i.e. each groupnumber should be unique within a given groupset, and within the output groupsets. It is further necessary that the addresses specified in the single item format do not refer to combinations of groupnumber and itemnumber implicitly specified in a group format statement. A groupset that appears in both input and output sections must have identically matching groups numbers. An additional restriction is that if the groupname appears only in the output formats section, then the groupset is only allowed to contain one groupnumber.

The itemnames specified in the group itemlist should not clash with item names specified in other groupsets or itemnames declared using the single item format (the first format given above) or groupnames, i.e. item and group names should be unique within the output definitions section.

Example:

         TAC @0103
         GROUP GERM[1:70](E1,T1)

Valid line break points:

• after the right square bracket (]) following <range>,

• after one of the commas (,) in <item-list>.

7 Variable and Constant Initialisation

Any names that have not been defined in the input or output definitions section are treated as local to the event builder. By default the names are assumed to be local variables and are set to zero at the start of processing each event. The values section allows the user to specify an alternative value to this default or to declare a constant that does not have to be set every event.

Items that are defined only in the output formats section may also be initialised in this section, as they are also initialised to zero by default.

Values Section Syntax

values

The values section is optional. It follows on from the output formats section and consists of the above statement, followed by one or more value specification statements.

Value Specification Syntax

set <variable-name> = <integer>

or

set <item-name> = <integer>

or

constant <constant-name> = <integer>

where:

<variable-name> is a user-provided name for a local variable,

<item-name> is the name of an item defined only in the output section, <integer> is the value specified and <constant-name> is a user-provided name for a local constant.

The <variable-name> or <constant-name> should be unique within the values section and must not be in use as an itemname in the input formats section or as a groupname in either format section.

The set statement ensures that the local variable or item is reset to the given value at the start of every event. The constant statement causes the value of the constant to be defined at set-up time. A constant can not subsequently be redefined with an assignment statement, say, whereas a variable can be.

Example:

     CONSTANT EMIN = 50
     CONSTANT EMAX = 10000
     SET NTEST = 9

This defines EMIN and EMAX to have fixed values as shown, and ensures that NTEST is set to 9 on starting to process each event.

8 Commands

The available processing functions fall into various categories: e.g. those that can be applied to an individual item, to an individual group and those that can only be applied after the whole event has been read in. There is no formal division between these types of command, they are all used within the commands section. However, a structured approach is necessary to make sense of group processing. Conceptually, the processing falls into 2 stages: first look at and process the data from all the groups that come in and then take decisions based on the data. The user’s commands only take effect once the input data has been scanned once. Some functions will require information to be extracted during processing of the event, but resulting in a decision only when all the event has been read in. For example, a filter on the Ge TDC words could result in a count incremented for each TDC word inside a given window, but a filter on the count itself could only be applied at the end of event processing. Similarly, the shared suppression algorithm will process hit pattern words as they are encountered during input of the event, but will not be able to take action immediately as the particular Ge word to be suppressed may occur later in the event.

Actions that apply to groups of parameters of a similar type can only be applied in whenever blocks (§8.6). The group range facility in the input format specification (§5) allows all the groups in an event satisfying the range criteria to be acted upon by the same commands.

Commands Section Syntax

commands

The commands section comes after the values section if present, or otherwise after the output formats section. It consists of the above statement followed by any number of command statements. The commands section is compulsory, but it may be empty, ie the user may wish to do no special processing at all. The possible commands are detailed in the following sections.

Qualification Bits

There are two of these, named q0 (most significant bit) and q1 (next most significant bit) at the front of every word received by the event builder that are not part of the 14 bit address or the 16 bit data value. They may be accessed in the commands section by adding .q0 or .q1 to any valid reference to an itemname in an expression or assignment. They are discarded on output.

The qualification bits can be copied onto the top of the dataword with the moveqq command (see §8.4).

Example:

          IF E1.Q0 eq 1 THEN REJECT GROUP

See §8.5 for the explanation of the if command and §8.7 for the reject command.

8.1 Arithmetic Expressions

<variable> = <expression>

where

<variable> can be an <item-name> from either the input or output parameter

lists or a local variable and

<expression> is any arithmetic expression obeying C operator precedence (see table below) involving <item-name>s, local variables and constants.

The operands in <expression> may be <item-name>s, integers or local variables and constants. If not listed in at least one of input formats, output formats or values section then <variable> is assumed to be a local variable, and similarly for any undeclared names in <expression>. Parameter variables which are only defined in the output formats section are automatically initialised to zero at the start of processing every event. An arithmetic operation on a groupname is not allowed.

Up to 6 levels of parentheses are allowed in <expression> and the operators given in the following precedence table may be used:

associativity

not bitwise NOT (complement) right

∗  multiply  /  divide  left
+  plus  −  minus  left
<  shift bits left  >  shift bits right  left
&  bitwise AND  left

xor exclusive bitwise OR left ior inclusive bitwise OR left

Operators on the same row have the same precedence; the first row has the highest precedence. (FORTRAN precedence is, in fact, a subset of C, since the bitwise operators do not exist as such in FORTRAN.)

Example:

         SUMENERGY = (SUMENERGY + EBG0)/2 + E2

Valid line break points:

• after the equivalence sign (=),

• after one of the operators.

8.2 Increment Command

increment <variable>

where <variable> has the same definition as for arithmetic commands.

This is the simple arithmetic operation of adding one to the value of a variable, item or group item. It is provided in this form only as a more efficient alternative to using A = A + 1.

Example:

         increment A

8.3 Decrement Command

decrement <variable>

where <variable> has the same definition as for arithmetic commands.

This is a simple arithmetic operation of subtracting one from the value of a variable. It is provided in this form only as a more efficient alternative to using A = A - 1.

Example:

         decrement A

8.4 Moveqq Command

moveqq <item-name>

where <item-name> is the name of an item defined in input or output section.

This command causes a copy of the qualifying bits to be taken and put on the top 2 bits of the dataword. The <item-name> must not be qualified with access to specific qualifier bits. If the bits on the input data word are numbered 0–31, with bits 0–15 being the data value, then: (q0) bit 31 → bit 15 (q1) bit 30 → bit 14 Both bits 31 and 30 are always copied, even if they are not set or are never used and the copy overwrites bits 15 and 14, regardless of their values.

Moving the bits changes the value of the data, both in expressions in subsequent event builder code and further on down the datapath, eg for the sorter.

It should be noted that the tagging mode of shared suppression (see the suppress command, §8.8) also allows the top bit (15) of the data value to be set, which could be a source of confusion.

Example:

         moveqq E1

8.5 If … Else Construct

if <condition> then <statements>

where <statements> may be a single statement or {<statement>r} <condition> is one of

<variable> <test> <value>

<variable> passes [<value>,<value>] <variable> fails [<value>,<value>]

where <variable> is an itemname or local variable name, <test> is one of eq (equality), ne (not equal to), lt (less than)

le (less than/equal) gt (greater than), ge (greater than/equal)

<value> is an integer value, an itemname a local variable name or a constant name.

This allows the execution of blocks of code conditional on the values of the data in the event. Up to 6 if blocks may be nested inside one another. Note that the condition may not contain an expression. The limits on the gate are inclusive.

An alternative form of the if statement allows the execution of blocks of code depending on whether or not an item is present in the current event.

if <item-name> exists then <statements>

where <item-name> is an itemname defined in the input formats section.

This is to allow the user to control what happens if a particular item is not present in a group, etc, rather than the value defaulting to zero or the result of whole statements containing missing itemnames becoming undefined. This command should not be used to test for the presence of qualification bits.

Finally, an if block may be followed by an else block:

else <statements>

The else block is optional and is executed if the condition in the if is not fulfilled. When using nested if … else constructs there can be some ambiguity about which if condition the else matches. This is resolved in the same way as in C and FORTRAN: the condition from the most recent (innermost) elseless if is used. This arises when the single statement form is used, and is eliminated by using braces round the statement.

Example:

         IF MRAW LT 8 THEN REJECT EVENT
         IF SUMENER PASSES [50,345] THEN
            {
            IF NGE LT 5 THEN REJECT EVENT
            SUMENER = SUMENER/10
            }
         IF TAC FAILS[20,403] THEN REJECT EVENT
         ELSE INCREMENT TCOUNT

If SUMENERGY has value 50, then the second condition is fulfilled and the statements in braces are executed. If TAC has value 20, then the third condition is not fulfilled and the event is not rejected, but TCOUNT is incremented instead. Valid line break points:

• before the left brace ({),

• after the left brace ({),

• at a valid line break point in <statement>. NB: the right brace (}) must be on a line on its own (apart from a trailing comment).

8.6 Whenever Command

whenever <condition> then <statements>

where <statements> may be a single statement or {<statement>r}, <condition> is one of

group = <group-number>, group = <group-name> or item = <sitem-name>

where <group-number> is an integer groupnumber between 1 and 255, <group-name> is the group name of a groupset defined in the input or

output section and

<sitem-name> is an itemname declared with the single item format in the input or output section.

The whenever command executes a block of code (<statement-list>) for the <groupnumber> or <sitem-name> given if they are present in the event. The block is executed for every group present in the event that fulfills a <groupname> condition, i.e. this type of whenever statement implies looping over the block of code.

Whenever blocks may be nested within each other. Also, ifs inside whenevers and vice versa is allowed. A whenever command implies looking for the presence of word(s) in the event. The if command tests the value of data. (<sitem-name> may not have a qualification bit, that would not make sense.)

Example:

         WHENEVER GROUP = GERM THEN INCREMENT NDET
         WHENEVER GROUP = GERM THEN
            {
            INCREMENT NGE
            SUMENER = SUMENER + (EBGO/2) + E2
            IF T1 FAILS [100,250] THEN REJECT GROUP
            }

The statement(s) shown are executed for all groups found in the event that belong to the groupset with groupname GERM. Note the use of group itemnames like T1 and EBGO is only valid in a whenever statement or block, as shown in the example. (See §8.7 for the explanation of the reject command.)

Valid line break points:

• after the THEN,

• after the left brace ({),

• at a valid line break point in <statement>.

NB: the right brace (}) must be on a line on its own (apart from a trailing comment).

8.7 Reject Command

reject <group-name>

or

reject <sitem-name>

or

reject event

where <group-name> is the groupname of a groupset <sitem-name> is the itemname of an item defined with a single item format

statement.

The first form of the reject command may be used with if and whenever commands to prevent all data from groups present in the event that belong to the specified groupset from being output or used in processing. The second form prevents the specified item from being output if it is present. The 3rd form effectively terminates processing for the current event. Any data already written to the output streams will be passed on. A further form of the reject command:

reject group

is only valid within a whenever block. It rejects the current group being processed. If there are nested whenever statement blocks, any ambiguity is resolved by taking the current group of the innermost whenever block where the condition uses the whenever group = syntax.

It does not matter whether the item or groupset is defined in the input or output format sections.

If the rejection command causes any whenever condition in force no longer to be true, that whenever block is exited. The user should be aware that code inside the block is executed up until the rejection command takes effect. Thus a multiplicity counter for a groupset might have the value 3 because 3 groups were processed in a whenever group = groupname block and on the 4th group, the groupset was rejected, so the number of valid groups in the groupset is 0.

A rejected item or group has not been wiped from memory. It is simply prevented from being output by a stream command or in the default output that occurs at the end of event processing. The data is still available and the BGO hit patterns will be used by the suppress command but subsequent whenever access to other items of rejected data is not available.

8.8 Suppress Command

suppress scheme <scheme-number> file <data-file> tag

where <scheme-number>is an integer code for the suppression scheme, <data-file> contains suppression information and tag is an optional keyword to select tagging mode.

This command performs the (shared) suppression on the event according to the instructions in <data-file>. The filename should be a Unix filename. The <scheme-number> is to allow the user to choose between different possible suppression schemes described in the same file. In general, the higher the code, the more BGO detectors are allowed to suppress a given detector.

The keyword tag is optional. It specifies that the effect of the suppress command is to tag one of the datawords in each suppressed group by marking the first bit of the data value as a 1. Note that this is one of the 16 bits of the data value and any subsequent calculations using a tagged item will use a value that includes the tag bit. The data is then still available to be output by a stream command. Note that the tagged item must be one that gets output in order for the suppression information to be passed on. This is tagging mode suppression. In the absence of the tag keyword, suppressed groups are marked as discarded as if they had been the subject of a reject command. The data for the suppressed groups are not then written to the output streams. This is rejection mode suppression.

Appendix A contains a description of the format of <data-file> contents accepted. It details what different <scheme-number>s mean and how to specify which item in a group should be tagged and which item is to be taken as the hit pattern.

8.9 Stream Command

stream <stream-number> <output-list>

or

stream <stream-number> event

where <stream-number>is an integer stream number between 0 and 4 inclusive, <output-list> is a list of <groupname>s and <item-name>s defined in the output section, separated by commas,

event is a keyword specifying the whole event.

This command allows streamed output from the event builder. (The sorter also has the facility to stream data.) The specified data items are written in the given order to stream <stream-number> if they are present in the event at the current stage of processing. The format in which the data is written is described in “Event Format [Sorting + Storage]” (J. Cresswell, EDOC074).

If the event keyword is specified, the data for the entire event is output as specified in the output formats section (aside from groups that have been discarded with the reject or suppress commands). The same data may be written to different streams. There are 4 streams numbered 1–4 which can send data to the sorter, to tape or both. (The mechanism for specifying which stream goes where is not part of the event builder language.) The responsibility for supervising streaming lies with the data router.

There is a default setting: if no stream commands are used in the source file, then the event is written to stream 1 at the end of processing. This guarantees output will be passed on without the user having to say anything. This default does not apply if there are any stream commands used, even if none have been executed for the given event. If, because for example, the source file contains a single stream command inside an if block of statements for which the condition was not fulfilled by the event, then no output would result for that event. A single stream statement in the source file means that all further output must be specified explicitly.

Example:

         STREAM 1 TRIGGER, GERM
         STREAM 2 RECOIL
         STREAM 3 EVENT

This will write the data for any groups present in groupnames trigger and ge to stream 1, and that for recoil to stream 2.

Valid line break points:

• after <stream-number>,

• after one of the commas (,) in <output-list>.

9 Reserved Words

The following is a list of reserved words which should not be used as names of items, variables, groups, etc.

asm             event           lt              then
auto            extern          main            typedef
blank           fails           moveqq          union
break           file            ne              unsigned
case            finish          output          values
char            float           passes          void
commands        for             register        volatile
const           formats         reject          whenever
constant        fortran         return          while
continue        ge              scheme
debuga          goto            set
debugl          group           short
debugp          gt              signed
decrement       if              sizeof
default         increment       static
do              input           stream
double          int             struct
else            item            suppress
enum            le              switch
eq              long            tag

10 Example 1

! This is taken from the document by Beausang and Fallon entitled `A Mind
! Experiment with EUROGAM'.  It is not intended to be a complete example,
! but to give a flavour.
INPUT FORMATS
group TRIGGER[255] (TYPE,Mraw)
group GERM[1:70] (E1,E2,T,TBD,EBGO,TBGO,HIT)
OUTPUT FORMATS
group TRIGGER[255] (TYPE,Mraw,NGE)
group GERM[1:70] (E1,T)
VALUES
constant a = 2000
constant b = 15000
constant c = 300
constant d = 10000
constant e = 8000
constant f = 30000
COMMANDS
whenever group = TRIGGER then
   {
   if Mraw lt 8 then reject event
   }
whenever group = GERM then
   {
   SUMENER=SUMENER+(E2+EBG0)
   suppress scheme 1 file /event-builder/shared-suppression
   if E1 fails [a,b] then reject event
   increment nge
   if T1 passes [c,d] then increment FT1
   }
! Final processing stage.
if SUMENER fails [e,f] then reject event
if FT1 lt 1 then reject event
stream 0 event                      ! Send data to the sorter only.
FINISH

Named parameters (e.g. SUMENER, FT1 ) which are not defined in the input formats section are assumed by usage to be zeroed at start of each event and do not require zeroing specifically at the start of the commands section.

A Appendix on Suppression File Format

The suppression file has to convey a large volume of information, i.e. denote which BGO detector suppresses which Ge detector for every Ge detector present in the EUROGAM array. Additional information needed is which word contains the BGO hit pattern and which word should be tagged with a bit in the event of the tag keyword being used with the suppress command. By way of an illustration, a sample suppression file is shown on page 27.

The defaults line is optional. It specifies default values for which item in the input format of the group contains the hit pattern and which item in the output format of the group is to be tagged if the suppression is done in tagging mode. These values will be applied to every group if no other values are specified for that group. In the absence of the defaults line, the item numbers must be specified for every group. The defaults line finishes with a backslash (\) or end row character.

The remainder of the suppression file format uses the numbering scheme for array positions (as distinct from the names of the detectors occupying those positions) as given in the document “Detector Position Numbering Scheme” (J. Simpson, EDOC046). Each Ge position has a unique number in the range 1–72. Each BGO position around the Ge position has a unique letter in the range a–j. So specifying 27 refers to the Ge data from position 27 and 34e refers to the BGO data from position e round Ge position 34.

It should be noted that the Ge array position numbers are the same as the group numbers described in the main body of this document.

Suppression Specification Syntax

defaults hititem = <item-number> tagitem = <item-number> \
<row> r

where <row> is given by: <Ge-position> <item-number> <item-number> | <<BGO-list> | > r \

and where <item-number> is an integer item number in the range 0–6, <Ge-position> is an integer value in the range 1–72, <BGO-list> is a list of <BGO-range>s separated by spaces, <BGO-range> is either

<Ge-position><BGO-position>

or

<Ge-position><BGO-position> – <BGO-position> and <BGO-position> is a letter in the range a–j.

The suppression specification is a table of rows. With the exception of the defaults line, each row in the table has 2 or more columns. The file is essentially free format with unnecessary white space between components being ignored but it makes things easier to follow to line the data up in some way as has been done in the example. Blank lines and line breaks are ignored and comments are allowed as specified for the event builder language. This is also illustrated in the example: a blank line has been left between EUROGAM faces. Columns are separated by a column separator character, | , referred to as a bar. The first column does not start with a bar, but the last column must finish with a bar. A row of data (as opposed to a line in the file) is finished with an end row character, \.

Each row of the table pertains to the suppression of a particular Ge group. The first column in a row contains the Ge group number, followed by two item numbers. If there is a defaults line at the start of the file, then these 2 item numbers are optional: otherwise they are compulsory. The first item number is that of the hit pattern word in the group as specified in the input formats section. The second is that of the item as specified in the output formats section that should be tagged with a suppression bit if the suppress command is invoked with the optional tag keyword. Note that if tagging mode suppression is desired, then the tag keyword must be specified in the suppress command: specification of the tagged item in the suppression file is not sufficient. (Remember also that items are numbered consecutively from zero).

The data for each Ge position must start on a new line. There must be a row in the table present for every group from which data is expected. There may be data for additional groups present, but no group may have 2 rows of data.

The second and subsequent columns specify sets of BGO positions that suppress the Ge group. Each column is associated with a scheme (column 2 for scheme 1, column 3 for scheme 3, etc.). The BGO positions specified in later columns are in addition to those in earlier columns, so no BGO position should be specified twice in the same row. A column may be blank, which says that no additional BGOs suppress the Ge on the current row for the next scheme. The letter ranges should be sensible, i.e. the limits should be in alphabetical order and ranges for the same Ge position should not overlap. The compiler is case-insensitive, so upper or lower case letters may be used to specify BGO positions indiscriminately.

Example

      69 6 0 | 69a-j | 64A-B 45i 45k 48f 48g |       | 70d 68A |\

This example just illustrates the syntax, rather than being realistic. This is a line from a table describing 4 suppression schemes for Ge group 69. The hit pattern is to be found in item 6 and any tagging will be on item 0. In scheme 1 the Ge detector is only suppressed by its own BGO’s. In scheme 2, it is also suppressed by some of the BGO’s from neighbouring groups. No additional BGO’s can do the suppression in scheme 3, but another 2 may do so in scheme 4.

A more substantial example is shown below. This file starts with a defaults line, so for most groups the hit pattern is received as item 6 and tagging will be on output item 0. Detector 4 is different to the others for some reason: its suppression bit will be on item 1 instead.

! This example shows how to specify the schemes shown in the document
! ``EUROGAM'' Suppression (J. Simpson, EDOC045).  Scheme 1 is what is
! referred to as ``individual suppression'' and scheme 2 is the
! ``shared suppression''.
DEFAULTS HITITEM = 6 TAGITEM = 0 \
  1 |  1a-j |  2f  2g  2h  6a  6e  5c  5d  5e 35a 35b  7i  7j |\
  2 |  2a-j |  3f  3g  3h  6a  6b  1c  1d  1e 11a 11b 13i 13j |\
  3 |  3a-j |  4f  4g  4h  6b  6c  2c  2d  2e 17a 17b 19i 19j |\
  4 6 1 |  4a-j |  5f  5g  5h  6c  6d  3c  3d  3e 23a 23b 25i 25j |\
  5 |  5a-j |  1f  1g  1h  6d  6e  4c  4d  4e 29a 29b 31i 31j |\
  7 |  7a-j |  8f  8g  8h 12e 12a 11c 11d 11e  1a  1b 35i 35j |\
  8 |  8a-j |  9f  9g  9h 12a 12b  7c  7d  7e 34a 34b 37i 37j |\
  9 |  9a-j | 10f 10g 10h 12b 12c  8c  8d  8e 39a 39b 42i 42j |\
 10 | 10a-j | 11f 11g 11h 12c 12d  9c  9d  9e 41a 41b 14i 14j |\
 11 | 11a-j |  7f  7g  7h 12d 12e 10c 10d 10e 13a 13b  2i  2j |\
 12 | 12a-e  7e  7f  8e  8f  9e  9f 10e 10f 11e 11f |         |\
 13 | 13a-j | 14f 14g 14h 18e 18a 17c 17d 17e  2a  2b 11i 11j |\
 14 | 14a-j | 15f 15g 15h 18a 18b 13c 13d 13e 10a 10b 41i 41j |\
 15 | 15a-j | 16f 16g 16h 18b 18c 14c 14d 14e 43a 43b 46i 46j |\
 16 | 16a-j | 17f 17g 17h 18c 18d 15c 15d 15e 45a 45b 20i 20j |\
 17 | 17a-j | 13f 13g 13h 18d 18e 16c 16d 16e 19a 19b  3i  3j |\
 18 | 18a-e 13e 13f 14e 14f 15e 15f 16e 16f 17e 17f |         |\
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 37 | 37a-j | 38f 38g 38h 41c 41d 41e 8a 8b 34i 34j           |\
 38 | 38a-j | 37c 37d 37e 33a 33b 65i 65j                     |\
 41 | 41a-j | 37f 37g 37h 44a 44b  6i  6j                     |\

43 | 43a-j | 44f 44g 44h 47c 47d 47e 14a 14b 10i 10j         |\
44 | 44a-j | 43c 43d 43e  9a  9b 41i 41j                     |\
47 | 47a-j | 43f 43g 43h 50a 50b 15i 15j                     |\
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
                         etc