\documentstyle[a4wide,11pt,twoside]{article} \title{EUROGAM Event Builder Language} \author{John Cresswell and Linda Pratt} \date{Edition 2.1\\August 1994} % Define thick bracket chacters for denoting optional syntax. \gdef\lb{\mbox{$\lbrack\!\lbrack$}} \gdef\rb{\mbox{$\rbrack\!\rbrack$}} \addtolength{\topmargin}{-0.5in} \newcounter{lcpexample} \begin{document} \begin{titlepage} { \hoffset=1truein \hsize=5.25truein \vsize=10.25truein \font\small=cmssbx10 at 14.4truept \font\medium=cmssbx10 at 17.28truept \font\large=cmssbx10 at 20.74truept \hrule height 0pt \parindent=0pt %\parskip=0pt \hskip 3.9truein \large EDOC081\par \vskip .5truein \large EUROGAM PROJECT\par \vskip 1.5truein \hrule height 2pt \vskip 20pt \large NSF DATA ACQUISITION SYSTEM\par \vskip .5truein EUROGAM Event Builder Language\par \vskip 20pt \hrule height 2pt \vskip 1truein \medium Edition 2.1\par \vskip 5pt August 1994\par \vfill \medium Nuclear Structure Software Support Group\par \vskip 5pt Liverpool University\par \vskip .5truein } \end{titlepage} \tableofcontents \maketitle \section{Note on Revision 2.1} The first release of this document was originally produced as the specification for the event builder language before the software was written. Hence much of it was in the future tense and it discussed matters from a design point of view. Subsequent releases reflected new commands and features in the language, but the discussion parts of the document were not updated. Hence the early sections have now been substantially rewritten, but may still prove helpful to the user in explaining concepts behind the language. New language features have been necessary for phase II of EUROGAM to handle the clover detectors: the main one is the {\bf groupcopy} command. Some additional changes have been needed to make sense of this command. For suppression, the mapping of BGO hit pattern bits onto position letters has been altered. Finally, some more examples have been added to the manual. \section{Introduction} \label{intro} The prime function of the event builder is to build events containing the defined set of parameters in the defined format. There is also some consistency checking done on the quality of events processed on input. 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 is not intended as a complete technical manual.) The EUROGAM project defined a list of general actions for the event builder, together with suggestions of what it should not do. The event builder language provides support for Compton suppression, new word formation, event filtering and simple arithmetic. It does not support operations such as gain matching and ballistic deficit correction. Another criterion for event builder processing could 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. The efficiency of computation required to cope with the level of processing necessary means 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. However, the provision of the event builder compiler allows the user some flexibility over what processing is done to the data without having to understand and write code at a low level. \section{Data considerations} \label{datacons} The document ``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. \subsection{Groups and Items} \label{grpit} Each data word (or {\em item}) has a unique 14 bit EUROGAM {\em address} which is written into the data acquisition hardware during the set-up phase. The address is divided logically into two parts: an 8 bit {\em group number} and a 6 bit {\em item number}. The repeated structure of the array apparatus is such that most parameters expected by the EUROGAM acquisition system naturally fall into {\em groups}. In particular, the set of data from a single Ge and associated BGO detectors can be considered as a {\em group} of parameters to be treated together. For each Ge detector the associated group will has a maximum of 32 parameters or {\em items} with item numbers running from 0--31. Each group has a group number. Each event consists 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, \ldots) each provide a group of parameters with its own unique group number. Many of the groups described above are 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 {\em groupset} can be given a {\em group name} in the language via a {\bf group} format specification (\S \ref{ipdefs}). Each groupset covers a {\em range} of group numbers, thus allowing, say, 45 identical Ge groups to be specified in one statement. In the same statement, {\em item names} are associated with the item numbers in a particular groupset, so avoiding the need for the user to refer to addresses. \subsection{Trigger Group} \label{trig} The trigger group is the only fixed group to appear in every event. The group number is always 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). The items for the trigger group are numbered starting from 48 (@30 in hex), rather than from 0 as for other groups on input to the event builder. When the trigger group is written to output, then its items are numbered implicitly from 0, as for all the other groups. \subsection{Single Item Names vs Group Item Names} \label{singit} The item names introduced in \S \ref{grpit} may actually describe several items of data. These are termed {\em group item names}. It is possible to associate an item name with an address specified explicitly and uniquely (see \S \ref{ipdefs}). This is a {\em single item name}. 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 group and groups with only one item are permitted. \subsection{Local Variables and Constants} \label{locvar} A {\em 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 a EUROGAM address associated with it. There is the facility in the language to initialise the value of a variable at the start of each event (\S \ref{val}). 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. Note: it is not possible for the user to save or accumulate information from one event and access it in subsequent events. {\em 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. \section{Organisation} \label{org} In order to define the operation of the event builder the user has to create a text file using any favourite editor. The suffix of the filename must be {\tt .ebl}. The text file must be read by a programme (compiler) called ebc 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 in the document entitled ``EUROGAM EBC Reference Card'' (L.C. Pratt and J.R. Cresswell, EDOC082) version 2.01 and a supplementary card ``EUROGAM SS Reference Card'' (L.C. Pratt) version 2.01 are available. The language 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: \begin{tabbing} \hspace{1.0in}\=\hspace{0.5in}\=\kill \>\bf input formats \\ \>\> Describes what items are expected as input to the event builder. \\ \>\bf output formats \\ \>\> Describes how the items are to be output. \\ \>\bf values \\ \>\> To initialise the user's local variables and constants and \\ \>\> to define templates for copying from group to group. \\ \>\> This section is optional. \\ \>\bf commands \\ \>\> Any processing required. \end{tabbing} The file is terminated with the statement: \begin{tabbing} \hspace{1.0in}\=\kill \>\bf finish \end{tabbing} 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 describe 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 {\bf whenever} command should be used (\S \ref{whenever}). 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 {\bf if} statement (\S \ref{if}) 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 {\bf stream} command or by default on reaching the end of the event processing (see \S \ref{stream}). As processing is carried out, parts of the event may be discarded using the {\bf reject} command (\S \ref{rej}) 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 {\bf stream} command. The data rejected is no longer accessible via subsequent commands and has essentially been discarded. The {\bf suppress} command (\S \ref{suppr}) 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. \newpage \section{Command Syntax} \label{comsyn} Within the syntax definitions, the following conventions are followed: All substitutable components are specified as $<\cdots>$, for example {\bf $<$name$>$}, {\bf $<$address$>$}, etc\ldots 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 {\bf $<$name$>$r} . Syntax that is only optional is denoted using sloped font \boldmath $like\;this$ \unboldmath . In the examples, keywords from the event builder language appear in {\tt UPPER CASE} and names chosen by the user appear in {\tt lower case}. \begin{description} \item[Statements] \hspace{5.2in} \newline 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. \item[Names] \hspace{5.2in} \newline 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. \item[Case] \hspace{5.5in} \newline The compiler is not case-sensitive. For example, the forms {\tt MRAW}, {\tt Mraw} and {\tt mraw} are all treated as the same name. \item[Numbers] \hspace{5.2in} \newline Only integer arithmetic is handled by the event builder. Numeric values may take any of the following forms: \begin{tabbing} \hspace{1.0in}\=\hspace{2.0in}\=\+\kill Decimal integer \>{\tt 0 25 -33} \\ Binary integer \>{\tt \%00001110001} \\ Hexadecimal integer \>{\tt @ffff @00001234} \end{tabbing} 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. \item[Comments] \hspace{5.2in} \newline 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 compiler. Hence whole lines or part of lines after commands may be used for commenting the text. \end{description} \newpage \section{Input Definitions} \label{ipdefs} 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. If any expected parameters are missed out of the definition, the event builder will not know what to do with the data from the missing parameters and an error statistic will be incremented. If extra parameters are specified which will never be received, this results in wasted resources such as memory, executing unnecessary instructions and in extreme cases (e.g. if every numerically possible item 0--32 and group 1--255 were defined as expected), may result in the event builder accepting corrupt data as valid. \subsection*{Input Section Syntax} \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf input formats} \end{tabbing} 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. \subsection*{Format Specification Syntax} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf $<$item-name$>$ $<$address$>$} \\ or \\ \>\>{\bf 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 group numbers and \\ $<$item-list$>$ \>\>is a list of $<$item-name$>$s separated by commas. \end{tabbing} The set of group numbers may be specified as a single number, as an inclusive range of consecutive numbers $i:j$ (where $i$ should not clash with each other, item names specified in other groupsets, item names declared using the single item format (the first format statement type given above) or group names, i.e. item names and group names should be unique within the {\bf input formats} section. The {\bf 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 {\bf blank} may appear in $<$item-list$>$. It is used as a spacer instead of an \mbox{$<$item-name$>$.} The \mbox{$<$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 {\bf blank} is thus a reserved word and may not be used for any other purpose. It is not an \mbox{$<$item-name$>$:} for example, references to {\tt blank} in an expression \mbox{(see \S\ref{expr})} will cause a compiler error. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} tac @0103 GROUP trg[255](param1, BLANK, param3, param4) GROUP germ[1:70](e1, e2, t1, ebgo, tbgo, hit) \end{verbatim} \end{description} The first line declares a single item, {\tt tac}, is expected as input with the address shown. In effect it has group number 3 and item number 1. The second line defines a groupset, {\tt trg}, which contains one group, with group number {\tt 255} containing items {\tt param1, param3} and {\tt param4}. Their item numbers are implicitly defined as 0, 2 and 3 respectively. The {\tt BLANK} is present no item with item number 1 is expected from hardware. The last line declares data from a groupset of 70 groups with group numbers from {\tt 1} to {\tt 70} is expected as input. Each group contains items {\tt e1} to {\tt hit} with item numbers 0 to 5. \begin{description} \item[Valid line break points:] \item[$\bullet$] after the right square bracket (]) following $<$range$>$, \item[$\bullet$] after one of the commas (,) in $<$item-list$>$. \end{description} \newpage \section{Output Definitions} \label{opdefs} 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 group and have the same group number. 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 {\bf input formats} section. In the absence of any {\bf stream} commands later on in the language file (see \S \ref{stream}), 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). \subsection*{Output Section Syntax} \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf output formats} \end{tabbing} The {\bf output formats} section follows on from the {\bf input section} and consists of the above statement, followed by one or more format specification statements. \subsection*{Format Specification Syntax} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf $<$item-name$>$ $<$address$>$ } \\ or \\ \>\>{\bf 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 group numbers and \\ $<$item-list$>$ \>\>is a list of $<$item-name$>$s separated by commas. \end{tabbing} The set of group numbers may be specified as a single number, as an inclusive range of consecutive numbers $i:j$ (where $i$ should not clash with item names specified in other groupsets or item names declared using the single item format (the first format given above) or group names, i.e. item and group names should be unique within the output definitions section. \newpage \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} tac @0103 GROUP germ[1:70](e1,t1) \end{verbatim} \end{description} The example is similar to that for the input formats section. However, the definition here specifies how the data will be output. In the groupset {\tt germ} fewer items have been specified than in the input section, so the user has reduced the number of words to be output. \begin{description} \item[Valid line break points:] \item[$\bullet$] after the right square bracket (]) following $<$range$>$, \item[$\bullet$] after one of the commas (,) in $<$item-list$>$. \end{description} \newpage \section{Variable and Constant Initialisation} \label{val} 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 {\bf 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 {\bf output formats} section may also be initialised in this section. They are NOT initialised to zero by default, but are considered to be absent unless they get set during processing. This section is also used to define {\em template}s for the {\bf groupcopy} command. The source and destination groupsets and how to transfer the items belonging to the group are specified and the definition is associated with a template name, which can be referred to subsequently in {\bf groupcopy} commands in the {\bf commands} section. The detailed description of this is deferred until \S\ref{groupcopy} and \S\ref{template}. \subsection*{Values Section Syntax} \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf values} \end{tabbing} The {\bf values} section is optional. It follows on from the {\bf output formats} section and consists of the above statement, followed by one or more value specification statements. \subsection*{Value Specification Syntax} \label{values} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf set $<$variable-name$>$ = $<$integer$>$ } \\ or \\ \>\>{\bf set $<$item-name$>$ = $<$integer$>$ } \\ or \\ \>\>{\bf constant $<$constant-name$>$ = $<$integer$>$ } \\ or \\ \>\>{\bf groupcopy $<$template-name$>$ to $<$group-name$>$ } \\ \>\>\>{\bf from $<$group-name$>$ $<$template-body$>$ } \\ 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, \\ $<$constant-name$>$ \>\>\>is a user-provided name for a local constant, \\ $<$template-name$>$ \>\>\>is a user-provided name for the template, \\ $<$group-name$>$ \>\>\>is the name of a groupset defined in one of the formats sections and \\ $<$template-body$>$ \>\>\>is explained in \S \ref{template}. \\ \end{tabbing} The $<$variable-name$>$ or $<$constant-name$>$ should be unique within the {\bf values} section and must not be in use as an item name in the {\bf input formats} section or as a group name in either format section. The {\bf set} statement ensures that the local variable or item is reset to the given value at the start of every event. The {\bf 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. \begin{description} \item[Example:] \hspace{1.0in} \begin{verbatim} CONSTANT emin = 50 CONSTANT emax = 10000 SET ntest = 9 \end{verbatim} \end{description} This defines {\tt emin} and {\tt emax} to have fixed values as shown, and ensures that {\tt ntest} is set to 9 on starting to process each event. \section{Commands} \label{coms} The user's commands appearing in the {\bf commands} section only take effect once the input data has been scanned once and passed the checks for corruption. Actions that apply to groups of parameters of a similar type can only be applied in {\bf whenever} blocks (\S \ref{whenever}). The group range facility in the input format specification (\S \ref{ipdefs}) allows all the groups in an event satisfying the range criteria to be acted upon by the same commands. \subsection*{Commands Section Syntax} \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf commands} \end{tabbing} The {\bf commands} section comes after the {\bf values} section if present, or otherwise after the {\bf output formats} section. It consists of the above statement followed by any number of command statements. The {\bf 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. \subsection*{Qualification Bits} There are two of these, named {\bf q0} (most significant bit) and {\bf 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 {\bf commands} section by adding {\tt .q0} or {\tt .q1} to any valid reference to an item name in an expression or assignment. They are discarded on output. The qualification bits can be copied onto the top of the dataword with the {\bf moveqq} command (see \S \ref{moveqq}). \begin{description} \item [Example:] \hspace{5.2in} \begin{verbatim} IF e1.Q0 EQ 1 THEN REJECT GROUP \end{verbatim} \end{description} See \S \ref{if} for the explanation of the {\bf if} command and \S \ref{rej} for the {\bf reject} command. \newpage \subsection*{Special Names} \label{special} There are 2 special names which are used to access specific information in the commands section. The {\bf eventno} is the EUROGAM event number of the current event and {\bf groupno} is the EUROGAM group number of the group currently being processed inside a {\bf whenever} block (see \S \ref{whenever}). They are conceptually somewhere between a local variable and a constant. They are like a constant because they can never be set by the user, or appear in one of the formats sections. Other variables or items can be set to the value of one of these special names, or they can be used in expressions in comparisons. The {\bf eventno} is the same for the processing of one event, but the value is not truly constant because it is different from event to event. The value of {\bf groupno} is not constant at all, it is more like a loop counter. \subsection{Arithmetic Expressions} \label{expr} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf $<$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. \end{tabbing} The operands in $<$expression$>$ may be $<$item-name$>$s, integers or local variables and constants. If not listed in at least one of {\bf input formats}, {\bf output formats} or {\bf values} section then $<$variable$>$ is assumed to be a local variable, and similarly for any undeclared names in $<$expression$>$. An arithmetic operation on a group name is not allowed. Parameter variables which are only defined in the {\bf output formats} section were formerly automatically initialised to zero at the start of processing every event under the EUROGAM phase I compiler. This behaviour has been altered for phase II: they are not set and are considered not to be present in the event until explicitly set by an instruction from the user. Up to 6 levels of parentheses are allowed in $<$expression$>$ and the operators given in the following precedence table may be used: \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{1.5in}\=\hspace{0.5in} \=\hspace{2.0in}\=\+\kill \>\>\>\>associativity \\ {\bf not} \>bitwise NOT (complement)\> \> \> right\\ \boldmath $\ast$\>multiply \>\boldmath $/$\>divide \> left \\ \boldmath $+$ \>plus \>\boldmath $-$\>minus \> left \\ \boldmath $<$ \>shift bits left \>\boldmath $>$\>shift bits right \> left \\ \boldmath $\&$ \>bitwise AND \> \> \> left \\ {\bf xor} \>exclusive bitwise OR \> \> \> left \\ {\bf ior} \>inclusive bitwise OR \> \> \> left \end{tabbing} 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.) \newpage \begin{description} \item [Example:] \hspace{5.7in} \begin{verbatim} sumenergy = (sumenergy + ebg0)/2 + e2 \end{verbatim} \end{description} \begin{description} \item[Valid line break points:] \item[$\bullet$] after the equivalence sign (=), \item[$\bullet$] after one of the operators. \end{description} \newpage \subsection{Increment Command} \label{inc} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf increment $<$variable$>$} \\ where \\ \>$<$variable$>$ has the same definition as for arithmetic commands. \end{tabbing} 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 \verb, a = a + 1,. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} INCREMENT a \end{verbatim} \end{description} \subsection{Decrement Command} \label{dec} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf decrement $<$variable$>$} \\ where \\ \>$<$variable$>$ has the same definition as for arithmetic commands. \end{tabbing} 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 \verb, a = a - 1,. \begin{description} \item[{\bf Example:}] \hspace{5.2in} \begin{verbatim} DECREMENT a \end{verbatim} \end{description} \newpage \subsection{Moveqq Command} \label{moveqq} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf moveqq $<$item-name$>$} \\ where \\ \>$<$item-name$>$ is the name of an item defined in input or output section. \end{tabbing} 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: \newline (q0) bit 31 $\rightarrow$ bit 15 \newline (q1) bit 30 $\rightarrow$ bit 14 \newline 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 {\bf suppress} command, \S \ref{suppr}) also allows the top bit (15) of the data value to be set, which could be a source of confusion. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} MOVEQQ e1 \end{verbatim} \end{description} \newpage \subsection{If \ldots Else Construct} \label{if} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\kill \>\>{\bf if $<$condition$>$ then $<$statements$>$ } \\ where \\ \>$<$statements$>$ may be a single statement or \{$<$statement$>$r\} \\ \>$<$condition$>$ is one of \+\+\+ \\ \bf $<$variable$>$ $<$test$>$ $<$value$>$ \\ \bf $<$variable$>$ passes [$<$value$>$,$<$value$>$] \\ \bf $<$variable$>$ fails [$<$value$>$,$<$value$>$] \-\- \\ where \+ \\ $<$variable$>$ \>\> is an item name or local variable name, \\ $<$test$>$ \>\>is one of {\bf eq} (equality), {\bf ne} (not equal to), {\bf lt} (less than) \\ \>\>{\bf le} (less than/equal) {\bf gt} (greater than), {\bf ge} (greater than/equal) \\ $<$value$>$\>\>is an integer value, an item name a local variable name or a \\ \>\>constant name. \end{tabbing} This allows the execution of blocks of code conditional on the values of the data in the event. Up to 6 {\bf if} blocks may be nested inside one another. Note that the condition may not contain an expression. The limits on the gate are inclusive. Finally, an {\bf if} block may be followed by an {\bf else} block: \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf else $<$statements$>$ } \end{tabbing} The {\bf else} block is optional and is executed if the condition in the {\bf if} is not fulfilled. When using nested {\bf if} \ldots {\bf 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) {\bf else}less {\bf if} is used. This arises when the single statement form is used, and is eliminated by using braces round the statement. If an item that is not present in the event is referenced in an {\bf if} condition, it is treated as if it had value zero for the purpose of the test. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} 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 \end{verbatim} \end{description} If {\tt sumenergy} has value 50, then the second condition is fulfilled and the statements in braces are executed. If {\tt tac} has value 20, then the third condition is not fulfilled and the event is not rejected, but {\tt tcount} is incremented instead. \newpage \begin{description} \item[Valid line break points:] \item[$\bullet$] before the left brace (\{), \item[$\bullet$] after the left brace (\{), \item[$\bullet$] at a valid line break point in $<$statement$>$. \item[NB:] the right brace (\}) must be on a line on its own (apart from a trailing comment). \end{description} \newpage \subsection{Whenever Command} \label{whenever} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\hspace{1.0in}\=\kill \>\>{\bf whenever $<$condition$>$ then $<$statements$>$ } \\ where \\ \>$<$statements$>$ may be a single statement or \{$<$statement$>$r\}, \\ \>$<$condition$>$ is one of \\ \>\>\>\bf group = $<$group-number$>$, \\ \>\>\>\bf group = $<$group-name$>$ or \\ \>\>\>\bf item = $<$sitem-name$>$ \\ \>where \\ \>\>$<$group-number$>$ \>\>is an integer group number between 1 and 255, \\ \>\>$<$group-name$>$ \>\>is the name of a groupset defined in the input or \\ \>\> \>\>output section and \\ \>\>$<$sitem-name$>$ \>\>is an item name declared with the single item format \\ \>\> \>\>in the input or output section. \end{tabbing} The {\bf whenever} command executes a block of code ($<$statement-list$>$) for the \linebreak \mbox{$<$group-number$>$} 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 $<$group-name$>$ condition, i.e. this type of {\bf whenever} statement implies looping over the block of code. The group number of the group currently being processed can be obtained using the special symbol {\bf groupno} inside the block (see \S\ref{special}). {\bf Whenever} blocks may be nested within each other. Also, {\bf if}s inside {\bf whenever}s and vice versa are allowed. A {\bf whenever} command implies looking for the presence of word(s) in the event. The {\bf if} command tests the value of data. ($<$sitem-name$>$ may not have a qualification bit, that would not make sense.) \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} 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 } \end{verbatim} \end{description} The statement(s) shown are executed for all groups found in the event that belong to the groupset with group name {\tt germ}. Note the use of group item names like {\tt t1} and {\tt ebgo} is only valid in a {\bf whenever} statement or block, as shown in the example. If the {tt reject} command causes the condition in the {\tt whenever} statement no longer to be true, that block of code is exited immediately. (See \S \ref{rej} for the explanation of the {\bf reject} command.) \begin{description} \item[Valid line break points:] \item[$\bullet$] after the THEN, \item[$\bullet$] after the left brace (\{), \item[$\bullet$] at a valid line break point in $<$statement$>$. \item[NB:] the right brace (\}) must be on a line on its own (apart from a trailing comment). \end{description} \subsection{Reject Command} \label{rej} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.6in}\=\kill \>\>{\bf reject $<$group-name$>$} \\ or \\ \>\>{\bf reject $<$sitem-name$>$} \\ or \\ \>\>{\bf reject event} \\ where \\ \>$<$group-name$>$ \>\>is the name of a groupset \\ \>$<$sitem-name$>$ \>\>is the name of an item defined with a single item format statement. \\ \end{tabbing} The first form of the {\bf reject} command may be used with {\bf if} and {\bf 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 {\bf reject} command: \begin{tabbing} \hspace{1.0in}\=\kill \>{\bf reject group} \end{tabbing} is only valid within a {\bf whenever} block. It rejects the current group being processed. If there are nested {\bf whenever} statement blocks, any ambiguity is resolved by taking the current group of the innermost {bf whenever} block where the condition uses the {\tt whenever group = } syntax. It does not matter whether the item or groupset is defined in the {\bf input} or {\bf 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 {\tt whenever group = } $<$group-name$>$ 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 {\bf 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 {\bf suppress} command but subsequent {\bf whenever} access to other items of rejected data is not available. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} IF mraw LT 8 THEN REJECT EVENT WHENEVER ITEM = param THEN { IF param FAILS [1000,4000] THEN REJECT param } WHENEVER GROUP = germ THEN { IF t1 FAILS [100,250] THEN REJECT GROUP ELSE INCREMENT count } IF count LT 4 THEN REJECT germ \end{verbatim} \end{description} The first line of the example rejects the whole event if {\tt mraw} is less than {\tt 8}. The 1st {\tt whenever} block rejects single item {\tt param} if it fails a filter. The 2nd {\tt whenever} block checks item {\tt t1} for every group in groupset {\tt germ}, rejecting the group if {\tt t1} fails a filter and counting the number of groups for which the test is passed. In the last line, if {\tt count} is too low, the whole of groupset {\tt germ} is rejected. \newpage \subsection{Suppress Command} \label{suppr} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.75in}\=\kill \>\>{\bf suppress scheme $<$scheme-number$>$ file $<$data-file$>$} \boldmath $tag$ \unboldmath \\ 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.\\ \end{tabbing} This command performs the (shared) suppression on the event according to the \linebreak instructions in $<$data-file$>$. The filename should be a Unix filename and should have the extension {\tt .ss}. 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 {\bf tag} is optional. It specifies that the effect of the {\bf 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 {\bf 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 {\em tagging mode suppression}. Note also that the commands {\bf groupcopy} and {\bf moveqq} also add bits in to the top of item data values. In the absence of the {\bf tag} keyword, suppressed groups are marked as discarded as if they had been the subject of a {\bf reject} command. The data for the suppressed groups are not then written to the output streams. This is {\em rejection mode suppression}. Appendix \ref{app1} 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. \newpage \subsection{Stream Command} \label{stream} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.75in}\=\kill \>\>{\bf stream $<$stream-number$>$ $<$output-list$>$} \\ or \\ \>\>{\bf 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. \end{tabbing} This command allows streamed output from the event builder. (The sort package 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 {\bf event} keyword is specified, the data for the entire event is output as specified in the {\bf output formats} section (aside from groups that have been discarded with the {\bf reject} or {\bf suppress} commands). The same data may be written to different streams. There are 4 streams numbered 1--4 which can send data along the data path and ultimately to tape. (The mechanism for specifying which stream goes where is not part of the event builder language. The responsibility for supervising streaming lies with the tape server. The on-line sorter spies on the data path to obtain its input.) There is a default setting: if no {\bf 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 {\bf stream} commands used, even if none have been executed for the given event. If, because for example, the source file contains a single {\bf stream} command inside an {\bf if} block of statements for which the condition was not fulfilled by the event, then no output would result for that event. A single {\bf stream} statement in the source file means that all further output must be specified explicitly. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} STREAM 1 trigger, germ STREAM 2 recoil STREAM 3 EVENT \end{verbatim} \end{description} This will write the data for any groups present in groupsets {\tt trigger} and {\tt germ} to stream {\tt 1}, and that for {\tt recoil} to stream {\tt 2}. All the data specified in the {\bf output formats} section that is present will be written to stream {\tt 3}. \begin{description} \item[Valid line break points:] \item[$\bullet$] after $<$stream-number$>$, \item[$\bullet$] after one of the commas (,) in $<$output-list$>$. \end{description} \newpage \subsection{Groupcopy Command} \label{groupcopy} The {\bf groupcopy} command allows the user to copy data from a given group to another given group. The event builder language was designed to handle items in the same group together. This new command has been added to allow data from a group to be split up by copying some of its items to another group belonging to a different groupset. The way it works is that the user includes in the {\bf values} section the specification of a {\em template}, which defines how to do the copy from any group belonging to a given groupset to any group belonging to another given groupset. The template is given a name, by which it is invoked with a {\bf groupcopy} command in the {\bf commands} section, giving {\em group numbers} as arguments. The groups must belong to the groupsets defined in the template. The template syntax is given in \S\ref{template} and the command syntax is given below. \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\hspace{1.0in}\=\kill \>\>{\bf groupcopy $<$template-name$>$ to $<$group-number$>$ from $<$group-number$>$ } \\ where: \+ \\ $<$template-name$>$ \>\>\>is the name of a template defined with a {\bf groupcopy} \\ \>\>\>statement in the {\bf values} section and \\ $<$group-number$>$ \>\>\>is an integer number, a constant or a variable\\ \>\>\>giving the number of the group belonging appropriate \\ \>\>\>to the groupset defined in the template. \\ \end{tabbing} Any data already in the destination group is overwritten by the {\bf groupcopy} command. Any items in the destination group for which there is no original item defined or present in the event have their values set to zero. \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} GROUPCOPY templ1 TO 81 FROM 1 GROUPCOPY templ2 TO gn FROM GROUPNO \end{verbatim} \end{description} The first example copies the items from group {\tt 1} to group {\tt 81} according to the instructions in a template which has been given the name {\tt templ1}. Group {\tt 81} must belong to the destination groupset as defined in {\tt templ1} and similarly group {\tt 1} must belong to the originating groupset. The second example copies the items from the current group being treated by a {\bf whenever} block (by reference to the special symbol {\tt GROUPNO}, see \S\ref{special}) into a group whose number is given by the variable {\tt gn} according to template {\tt templ2}. Similar restrictions on groups belonging to defined groupsets apply as in the first example. The compiler attempts to check these, but in the second example it is not possible as the value of {\tt gn} is not known at compilation time. If the event builder detects such an error during processing, an error statistic is incremented. \newpage \subsection{Groupcopy Template Definition} \label{template} N.B. The template definition is done in the {\bf values} section of the language file. Here is the template definition syntax, some of which has already been presented in \S \ref{values}: \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.5in}\=\hspace{1.0in}\=\kill \>\>{\bf groupcopy $<$template-name$>$ to $<$group-name$>$ from $<$group-name$>$} \\ \>\>\>{\bf from $<$group-name$>$ $<$template-body$>$} \\ where: \+ \\ $<$template-name$>$ \>\>\>is a user-provided name for the template, \\ $<$group-name$>$ \>\>\>is the name of a groupset defined in one of the format \\ \>\>\>sections, \\ $<$template-body$>$ \>\>\>is \{$<$template-line$>$r\}, \\ $<$template-line$>$ \>\>\>is given by \\ \\ \>\>{\bf $<$item-list$>$ : $<$item-list$>$} {\em :} $<$\boldmath$tag$-$word$\unboldmath$>$ \\ \\ where: \\ $<$tag-word$>$ \>\>\>is {\bf tag} or {\bf notag} \\ \end{tabbing} The $<$item-list$>$s are lists of $<$item-names$>$ separated by commas as defined before in other commands. The first and second (or destination and originating) $<$item-list$>$s contain items belonging to the groupsets given by the first and second (or destination and originating) $<$group-name$>$s respectively. When the template is invoked, the event builder looks for the next item in the originating list and if it is present in the event copies the value across to the first item in the destination list not yet set. If the originating item is not present, the event builder carries on down the originating list and looks until it does find an item to copy. This carries on until the destination items have all been set or there are no more items to look for in the originating list. Any destination items that have not then been filled have their values set to zero. Note that it is possible for one or both $<$item-list$>$s to contain only one item. Also there is little point in a destination list being longer than the originating list, as the extra items will never be filled. When the items are copied across, information as to which item originally contained the value is lost. This may not matter: for example, if there is only one item in each list it is still obvious where the value came from. In some cases it could be important to know which item provided the value, in the context of leaves of a clover detector, for instance. The {\bf tag} keyword is used to instruct that the copied item value is tagged with its position in the originating list using the top 3 bits. Since only 3 bits are available for tagging, this unfortunately means this feature is not totally general as only values 1-7 can be used for tagging, and the number of items in the originating list is only limited by the number of items in the originating group, which could be upto 32. The {\bf notag} keyword indicates that tagging should not be done. The $<$tag-word$>$ and the preceding colon may be omitted, in which case the default is not to tag the value. \newpage \begin{description} \item[Example:] \hspace{5.2in} \begin{verbatim} GROUPCOPY templ TO opgs FROM ipgs { t : t1 : NOTAG e : e1,e2 : NOTAG ita,itb : i1,i2,i3,i4 : TAG } \end{verbatim} \end{description} The example shows the definition of a template called {\tt templ}. It defines how to copy groups belonging to the originating groupset, {\tt ipgs} into groups belonging to the destination groupset, {\tt opgs}. Items {\tt t1, e1, e2, i1, i2, i3} and {\tt i4} must all belong to groupset {\tt ipgs} and items {\tt t, e, ita} and {\tt itb} belong to groupset {\tt opgs}. The first $<$template-line$>$ will cause the value of item {\tt t1} to be copied to item {\tt t}, if {\tt t1} is present: otherwise {\tt t} is set to zero. The value will not be tagged, as it can only have come from one item. For the second \mbox{$<$template-line$>$}, {\tt e} will take the value of {\tt e1} if that is present, otherwise {\tt e2} if that is present, otherwise zero. No tagging is done, so the user will not know if {\tt e} contains the value of {\tt e1, e2} or neither of these, but presumably does not care. For the third $<$template-line$>$ there are several possible outcomes as to which items get copied where, depending which of the originating items are present in the event. The event builder first looks to fill {\tt ita} by checking for {\tt i1}, if {\tt i1} is absent, it looks for {\tt i2} and so on. When/if it fills {\tt ita} it then looks to fill {\tt itb} by carrying on with the {\tt i}{\em n} if there are any left. Any items it fails to fill are set to value zero. Tagging is used to say which items were copied. A tag value of zero means that no original item was copied into that destination item. Suppose items {\tt i2} and {\tt i4} are present in the event. Then {\tt ita} will have a data value copied from {\tt i2} and be tagged with the value 2 and {\tt itb} will have a data value copied from {\tt i4} and be tagged with the value 4. Notice that the tag values of 2 and 4 are not the same as the item numbers of the item in the groupset {\tt ipgs}. They could be items 16 and 7 respectively (the definition of the groupset is not shown). It is the position in the originating $<$item-list$>$ that is used for the tag value. The use of {\bf groupcopy} is further illustrated in \S\ref{exclover} and \S\ref{exshields}. \newpage \section{Reserved Words} The following is a list of reserved words which should not be used as user- defined names of items, variables, groups, etc. The list consists of key words that have special significance in the event builder language and the reserved words of ANSI C. \begin{verbatim} asm event int suppress auto eventno item switch blank extern le tag break fails long then case file lt to char finish main typedef commands float moveqq union const for ne unsigned constant formats notag values continue fortran output void debuga from passes volatile debugl ge register whenever debugp goto reject while decrement group return stream default groupcopy scheme struct do groupno set double gt short else if signed enum increment sizeof eq input static \end{verbatim} \newpage \section{Examples} \addtocounter{lcpexample}{1} \subsection{Example \thelcpexample: mind.ebl} \markboth{Example \thelcpexample \/ (\S\thesubsection) continued\ldots}{Example \thelcpexample \/ (\S\thesubsection) continued\ldots} \label{exmind} \begin{verbatim} ! File mind.ebl ! ! 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 ! Note: the case of the characters is not significant to the compiler. 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 ! Define some constants to be used in filtering. CONSTANT a = 2000 CONSTANT b = 15000 CONSTANT c = 300 CONSTANT d = 10000 CONSTANT e = 8000 CONSTANT f = 30000 COMMANDS ! Reject events with too few gamma rays. WHENEVER GROUP = trigger THEN { IF mraw LT 8 THEN REJECT EVENT } ! Check the germanium groups calculating sum energy and other parameters. WHENEVER GROUP = germ THEN { sumener=sumener+(e2+ebg0) SUPPRESS SCHEME 1 FILE config.ss IF e1 FAILS [a,b] THEN REJECT EVENT INCREMENT nge IF t1 PASSES [c,d] THEN INCREMENT ft1 } \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} ! Final event filtering. IF sumener FAILS [e,f] THEN REJECT EVENT IF ft1 LT 1 THEN REJECT EVENT STREAM 1 EVENT ! Send all the output data to one stream only. FINISH \end{verbatim} Named parameters (e.g. {\tt sumener, ft1}) which are not defined in the {\bf 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 {\bf commands} section. \newpage \addtocounter{lcpexample}{1} \subsection{Example \thelcpexample: clover.ebl} \label{exclover} \markboth{Example \thelcpexample \/ (\S\thesubsection) continued...}{Example \thelcpexample \/ (\S\thesubsection) continued...} \begin{verbatim} ! File clover.ebl ! ! To illustrate the GROUPCOPY facility. This file could be used to split ! the clover groups up into sets in which the same number of leaves fired. ! It also has the effect of reducing the volume of data for output by ! getting rid of many input items missing in the clovers groupset, which ! would be output with value zero. ! INPUT FORMATS GROUP trigger[255] (type, mraw, msup, mbgo, muser, mtac) GROUP germ[1:50] (ge1, ge2, get, gebd, bgoe, bgot, bgop) ! The keyword BLANK is used to fill in for items not activated in hardware. GROUP clovers[51:80](BLANK, BLANK, BLANK, BLANK, clbgoe, clbgot, clbgop, BLANK, geA1, geA2, geAt, geAbd, geB1, geB2, geBt, geBbd, geC1, geC2, geCt, geCbd, geD1, geD2, geDt, geDbd) OUTPUT FORMATS GROUP trigger[255] (type, mraw, msup, mbgo, muser, mtac) GROUP germ[1:50] (ge1, get, bgop) ! Define output groupsets to receive subsets of groupset clovers depending ! how many leaves fired. GROUP clovers1[81:110] (cl1bgop, ge1A1, ge1At) GROUP clovers2[111:140] (cl2bgop, ge2A1, ge2At, ge2B1, ge2Bt) GROUP clovers3[141:170] (cl3bgop, ge3A1, ge3At, ge3B1, ge3Bt, ge3C1, ge3Ct) GROUP clovers4[171:200] (cl4bgop, ge4A1, ge4At, ge4B1, ge4Bt, ge4C1, ge4Ct, ge4D1, ge4Dt) VALUES ! Define groupno offsets for clover groupsets with different no of leaves ! firing. CONSTANT cloff1 = 30 CONSTANT cloff2 = 60 CONSTANT cloff3 = 90 CONSTANT cloff4 = 120 ! The VALUES section continues on the next page. \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} ! The continuation of the VALUES section from the previous page. ! Define group copy templates to instruct how to copy a group into an ! appropriate place depending how many clover leaves have fired. A ! maximum of 4 items appear in the originating lists, so it is OK to use ! tagging. GROUPCOPY cp4 TO clovers4 FROM clovers { cl4bgop :clbgop :NOTAG ge4A1, ge4B1, ge4C1, ge4D1 :geA1, geB1, geC1, geD1 :TAG ge4At, ge4Bt, ge4Ct, ge4Dt :geAt, geBt, geCt, geDt :TAG } GROUPCOPY cp3 TO clovers3 FROM clovers { cl3bgop :clbgop :NOTAG ge3A1, ge3B1, ge3C1 :geA1, geB1, geC1, geD1 :TAG ge3At, ge3Bt, ge3Ct :geAt, geBt, geCt, geDt :TAG } GROUPCOPY cp2 TO clovers2 FROM clovers { cl2bgop :clbgop :NOTAG ge2A1, ge2B1 :geA1, geB1, geC1, geD1 :TAG ge2At, ge2Bt :geAt, geBt, geCt, geDt :TAG } GROUPCOPY cp1 TO clovers1 FROM clovers { cl1bgop :clbgop :NOTAG ge1A1 :geA1, geB1, geC1, geD1 :TAG ge1At :geAt, geBt, geCt, geDt :TAG } COMMANDS WHENEVER GROUP = clovers THEN { ! Work out how many leaves have fired. leaves = 0 IF geA1 GT 0 THEN INCREMENT leaves IF geB1 GT 0 THEN INCREMENT leaves IF geC1 GT 0 THEN INCREMENT leaves IF geD1 GT 0 THEN INCREMENT leaves ! The current WHENEVER block is continued on the next page. \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} ! The WHENEVER block continued from the previous page. ! Copy the group into the appropriate groupset depending how many leaves ! fired. IF leaves EQ 1 THEN { gn = cloff1 + GROUPNO GROUPCOPY cp1 TO gn FROM GROUPNO } IF leaves EQ 2 THEN { gn = cloff2 + GROUPNO GROUPCOPY cp2 TO gn FROM GROUPNO } IF leaves EQ 3 THEN { gn = cloff3 + GROUPNO GROUPCOPY cp3 TO gn FROM GROUPNO } IF leaves EQ 4 THEN { gn = cloff4 + GROUPNO GROUPCOPY cp4 TO gn FROM GROUPNO } } ! End of the WHENEVER block. STREAM 1 EVENT FINISH \end{verbatim} \newpage \addtocounter{lcpexample}{1} \subsection{Example \thelcpexample: shields.ebl} \label{exshields} \markboth{Example \thelcpexample \/ (\S\thesubsection) continued\ldots}{Example \thelcpexample \/ (\S\thesubsection) continued...} \begin{verbatim} ! File shields.ebl ! ! This demonstrates how GROUPCOPY could be used to split up groups into ! germanium and BGO words. ! INPUT FORMATS GROUP trigger[255] (type, mraw, msup, mbgo, muser, mtac) GROUP germ[1:64] (neut, ge2, get, gebd, bgoe, bgot, bgop) GROUP clovers[65:74] (e1, e2, e3, e4, n, t, b, be, bt, hit) OUTPUT FORMATS GROUP trigger[255] (type, mraw) GROUP germ [1:64] (neut, ge2, get, getbd) GROUP clovers[65:74] (e1, e2, e3, e4) GROUP shields[101:174](sbgoe, sbgot, sbgop) VALUES ! Define how to copy the bgo items from the germ groupset to the shields ! groupset. The tagging field is left out, so the default of NOTAG will ! be adopted. GROUPCOPY bgocp TO shields FROM germ { sbgoe :bgoe sbgot :bgot sbgop :bgop } ! Define how to copy the bgo items from the clover groupset to the shields ! groupset. Note that another template is needed to copy the clover groupset ! but the destination groupset, shields, is the same as for the previous ! template. GROUPCOPY bgocp2 TO shields FROM clovers { sbgoe :be sbgot :bt sbgop :hit } \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} COMMANDS ! Copy the bgo words from the germ groupset. WHENEVER GROUP = germ THEN { gn = GROUPNO + 100 GROUPCOPY bgocp gn FROM GROUPNO } ! Copy the bgo words from the clovers groupset. WHENEVER GROUP = clovers THEN { gn = GROUPNO + 100 GROUPCOPY bgocp2 gn FROM GROUPNO } STREAM 1 EVENT FINISH \end{verbatim} \newpage \addtocounter{lcpexample}{1} \subsection{Example \thelcpexample: streams.ebl} \label{exstreams} \markboth{Example \thelcpexample \/ (\S\thesubsection) continued\ldots}{Example \thelcpexample \/ (\S\thesubsection) continued...} \begin{verbatim} ! file streams.ebl ! ! To show writing data to different streams. ! INPUT FORMATS GROUP trigger[255] (type, mraw, msup, mbgo, muser, mtac) GROUP germ [1:64] (neut, ge2, get, gebd, bgoe, bgot, bgop) GROUP other [81:90] (e1, e2, e3, e4, t1, t2, t3, t4, mode) OUTPUT FORMATS GROUP trigger[255] (type, evn) GROUP germ [1:64] (neut, ge2, get, getbd) GROUP other [81:90] (mode, e3, t2) GROUP shields[101:164](sbgoe, sbgot, sbgop) VALUES ! Define template to split off the bgo items from the germ groupset. GROUPCOPY bgocp TO shields FROM germ { sbgoe :bgoe sbgot :bgot sbgop :bgop } COMMANDS ! Save the current event number as a trigger word. This would be needed ! should reassembly of all the data on different streams for the same event ! be required. evn = EVENTNO ! Copy the bgo words. WHENEVER GROUP = germ THEN { gn = GROUPNO + 100 GROUPCOPY USING bgocp TO gn FROM GROUPNO } \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} ! Write the germanium and bgo data to one stream and the data from the other ! detector to another. STREAM 1 trigger, germ, shields STREAM 2 trigger, other FINISH \end{verbatim} \newpage \appendix \section{Appendix on Suppression File Format} \label{app1} 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, which word should be tagged with a bit in the event of the {\bf tag} keyword being used with the {\bf suppress} command and which word(s) should be used to decide whether a Ge detector has fired. By way of an illustration, sample suppression files are shown on in \S\ref{sstable} on page \pageref{sstable} and \S\ref{ssisomer} on page \pageref{ssisomer}. 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. Optionally, it can also specify which item(s) in the i/p group denote(s) that the Ge detector has fired. This information is only needed if the {\bf butnot} facility is used in the file (see below). The values defined in the defaults line 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 (\boldmath$\backslash$\unboldmath) 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--80. Each BGO position around the Ge position has a unique letter in the range a--k. 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. Unfortunately, it has proved necessary to alter the meaning of the BGO letters slightly for phase II. The letter a now corresponds to the first bit in the hit pattern (bit 0). This was not the case under phase I: the letter a corresponded to BGO position a, which was bit 1 in the hit pattern (provided the channel had been cabled correctly). The old definition was altered from the specification to match the behaviour of the phase I germanium card as delivered. The phase II clover card BGO hit pattern starts in bit 0, hence the definition has been altered to match this. The phase I type cards still provide the same hit pattern starting at bit 1, so their first BGO detector now must be specified with the letter b. {\em All existing phase I suppression files must be altered to comply with the new definition.} A facility has been added (since version 1.1 of this manual) to allow a more complex type of shared suppression to be specified than that described above. This is used if a given BGO element is to be allowed to suppress the current group, but only if another Ge detector has not fired. This uses the keyword {\bf butnot}. Supposing on the row for group 11, we find a term specifying 27e butnot 28. If BGO element 27e fires but Ge 28 does not, then the data for group 11 is suppressed. However, if BGO 27e fires and Ge 28 also fires then group 11 is not suppressed by the example term. The issue of whether a given Ge has fired is resolved by examining the fire item(s) given in the defaults line or column 1 of the row for that detector. So for our example, if the row for group 28 has a fire item specified, that is the one that will be used, otherwise the default value will be used. The description of the specification below has been altered since version 1.1 of the manual, but {\bf butnot} is an additional facility, so the basic defined syntax has not been altered, since the new instructions are all optional. \newpage \subsection{Suppression Specification Syntax} \begin{tabbing} \hspace{0.5in}\=\hspace{0.5in}\=\hspace{0.7in}\=\hspace{1.3in}\= \hspace{0.9in}\=\kill \>\> \boldmath $defaults \;$ $hititem\;$\unboldmath {\bf =} $<$\boldmath$item$-$number$\unboldmath$>$ \boldmath$tagitem\;$\unboldmath {\bf =} $<$\boldmath$item$-$number$\unboldmath$>$\\ \>\>\>\>\> {\bf \lb} \boldmath$fireitem\;$\unboldmath {\bf =} $<$\boldmath$fire$-$term$\unboldmath$>$ \boldmath {\bf \rb} $\;\backslash$ \unboldmath \\ \>\>{\bf $<$row$>$} r \\ where \\ \>$<$row$>$ is given by: \\ \>\>{\bf $<$Ge-position$>$ $<$}\boldmath$item$-$number$\unboldmath$>$ $<$\boldmath$item$-$number$\unboldmath$>$ \\ \>\>\>\>{\bf \lb $<$}\boldmath$fire$-$term$\unboldmath$>$\rb \boldmath $\;\mid$ \unboldmath $<<$BGO-term$>$ r \boldmath $\mid$ \unboldmath$>$ r \boldmath $\backslash$ \unboldmath \\ and where \\ \>$<$item-number$>$ \>\>is an integer item number in the range 0--32, \\ \>$<$fire-term$>$ \>\>is either \\ \>\>\>{\bf $<$item-number$>$} \\ \>\>\>or \\ \>\>\>{\bf ( $<$item-number$>$ r ) } \\ \>$<$Ge-position$>$ \>\>is an integer value in the range 1--72, \\ \>$<$BGO-term$>$ \>\>is either \\ \>\>\>{\bf $<$BGO-range$>$} \\ \>\>\>or \\ \>\>\>{\bf ( $<$BGO-formula$>$ ) } \\ \>$<$BGO-range$>$ \>\>is either \\ \>\>\>{\bf $<$Ge-position$><$BGO-position$>$} \\ \>\>\>or \\ \>\>\>{\bf $<$Ge-position$><$BGO-position$>$ -- $<$BGO-position$>$} \\ \>$<$BGO-position$>$\>\>is a letter in the range a--j, \\ \>$<$BGO-formula$>$ \>\>is given by: \\ \>\>\>{\bf $<$BGO-list$>$ butnot $<$Ge-list$>$} \\ \>$<$BGO-list$>$ \>\>is a list of $<$BGO-range$>$s separated by spaces, \\ \>\>\>and \\ \>$<$Ge-list$>$ \>\>is a list of $<$Ge-position$>$s separated by spaces. \end{tabbing} Please note: the {\bf \lb} $\;$ {\bf \rb} round the $<$fire-term$>$ parts of command are not part of the definition: they indicate that the fire item information is an optional part of an optional piece of syntax. The {\bf defaults} line is optional. It establishes default values for the hit item, tag item and fire items described below for every row in the table. It saves them being specified repeatedly as in its absence, they must be specified on each row of the table. The default values can be overridden by specifying different values on a row. The suppression specification is a table of rows. With the exception of the {\bf 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, \boldmath $\mid$ , \unboldmath referred to as a {\em 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 {\em end row} character, \boldmath $\backslash$\unboldmath. 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 2 numbers and optionally another item number or list of item numbers in parentheses. If there is a {\bf defaults} line at the start of the file, then the item numbers are optional: otherwise the first 2 item numbers are compulsory. The first item number is that of the hit pattern word in the group as specified in the {\bf input formats} section. The second is that of the item as specified in the {\bf output formats} section that should be tagged with a suppression bit if the {\bf suppress} command is invoked with the optional {\bf tag} keyword. Note that if tagging mode suppression is desired, then the {\bf 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 third term gives item numbers that are used to decide if a Ge detector has fired as specified in the {\bf input formats} section. For a phase II clover detector, for example, the event builder might have to test 4 items to decide whether the clover has fired, whereas for an ordinary phase I detector, a single item might suffice. The fire term is only needed if the {\bf butnot} keyword is used in the suppression file. 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 {\em 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. \begin{description} \item[Example] \hspace{5.2in} \begin{verbatim} 69 6 0 | 69a-j | 64A-B 45i 45k 48f 48g | | 70d 68A |\ \end{verbatim} \end{description} 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. The {\bf butnot} keyword is intended to allow the specification of a list of BGO elements that should be included in the suppression only if a given list of Ge detectors has not fired. Nested {\bf butnot} operations are not allowed. An example of the syntax is shown in the following example. \begin{description} \item[Example] \hspace{5.2in} \begin{verbatim} 10 6 0 | 10b-k | 9b (11b BUTNOT 12) (11c 12d 12e 14b-e BUTNOT 12 13)|\ 11 6 0 | 11b-k | |\ 12 6 0 0 | 12b-k | |\ 13 6 0 (0 1 2 3) | 13a-g | |\ 14 6 0 | 14b-k | |\ \end{verbatim} \end{description} In scheme 2, Ge detector {\tt 10} is suppressed by the BGOs from its own shield and element {\tt b} from shield {\tt 9}. Element {\tt b} from shield {\tt 11} suppresses group {\tt 10} in the absence of a hit in Ge detector {\tt 12}. Element {\tt c} of shield {\tt 11}, elements {\tt d} and {\tt e} from shield {\tt 12} and elements {\tt b}, c, d and {\tt e} from shield {\tt 14} suppress group {\tt 10} only in the absence of a hit in Ges {\tt 12} and {\tt 13}. A single fire item has been specified in column 1 of the rows for detector {\tt 12} as it is needed by the {\tt butnot} formulas in scheme 2 for group {\tt 10}. A list of fire items has been specified for group {\tt 13} for the same reason. Note that the specification for group {\tt 13} has been split over 2 lines. A substantial example of suppression file format is given in \S\ref{sstable}. This file starts with a defaults line, so for most groups the hit pattern is received as item {\tt 6} and tagging will be on output item {\tt 0}. Detector {\tt 4} is different to the others for some reason: its suppression bit will be on item {\tt 1} instead. \newpage \setcounter{lcpexample}{1} \subsection{Suppression Example \thelcpexample: js.ss} \label{sstable} \begin{verbatim} ! File js.ss ! ! 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''. ! NOTE: This example uses phase I style detectors, so it has been ! altered to accomodate the new hit pattern bits to letters mapping: ! a-j has become b-k, etc. DEFAULTS HITITEM = 6 TAGITEM = 0 \ 1 | 1b-k | 2g 2h 2i 6b 6f 5d 5e 5f 35b 35c 7j 7k |\ 2 | 2b-k | 3g 3h 3i 6b 6c 1d 1e 1f 11b 11c 13j 13k |\ 3 | 3b-k | 4g 4h 4i 6c 6d 2d 2e 2f 17b 17c 19j 19k |\ 4 6 1 | 4b-k | 5g 5h 5i 6d 6e 3d 3e 3f 23b 23c 25j 25k |\ 5 | 5b-k | 1g 1h 1i 6e 6f 4d 4e 4f 29b 29c 31j 31k |\ 7 | 7b-k | 8g 8h 8i 12f 12b 11d 11e 11f 1b 1c 35j 35k |\ 8 | 8b-k | 9g 9h 9i 12b 12c 7d 7e 7f 34b 34c 37j 37k |\ 9 | 9b-k | 10g 10h 10i 12c 12d 8d 8e 8f 39b 39c 42j 42k |\ 10 | 10b-k | 11g 11h 11i 12d 12e 9d 9e 9f 41b 41c 14j 14k |\ 11 | 11b-k | 7g 7h 7i 12e 12f 10d 10e 10f 13b 13c 2j 2k |\ 12 | 12b-f 7f 7g 8f 8g 9f 9g 10f 10g 11f 11g | |\ 13 | 13b-k | 14g 14h 14i 18f 18b 17d 17e 17f 2b 2c 11j 11k |\ 14 | 14b-k | 15g 15h 15i 18b 18c 13d 13e 13f 10b 10c 41j 41k |\ 15 | 15b-k | 16g 16h 16i 18c 18d 14d 14e 14f 43b 43c 46j 46k |\ 16 | 16b-k | 17g 17h 17i 18d 18e 15d 15e 15f 45b 45c 20j 20k |\ 17 | 17b-k | 13g 13h 13i 18e 18f 16d 16e 16f 19b 19c 3j 3k |\ 18 | 18b-f 13f 13g 14f 14g 15f 15g 16f 16g 17f 17g | |\ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | 37b-k | 38g 38h 38i 41d 41e 41f 8b 8c 34j 34k |\ 38 | 38b-k | 37d 37e 37f 33b 33c 65j 65k |\ 41 | 41b-k | 37g 37h 37i 44b 44c 6j 6k |\ 43 | 43b-k | 44g 44h 44i 47d 47e 47f 14b 14c 10j 10k |\ 44 | 44b-k | 43d 43e 43f 9b 9c 41j 41k |\ 47 | 47b-k | 43g 43h 43i 50b 50c 15j 15k |\ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . etc ! Note: the BUTNOT keyword is not used so no fire items have ! been defined in the DEFAULTS line or the data rows. \end{verbatim} \newpage \addtocounter{lcpexample}{1} \subsection{Suppression Example \thelcpexample: isomer.ss} \markboth{Suppression Example \thelcpexample \/ (\S\thesubsection) continued\ldots}{Suppression Example \thelcpexample \/ (\S\thesubsection) continued\ldots} \label{ssisomer} \begin{verbatim} ! File isomer.ss ! ! This is a real phase II suppression file as used in C. Beausang's isomer ! run during commissioning. ! defaults hititem = 6 tagitem = 0 \ ! The phase I detectors, 1-30 are suppressed by their own shields. They ! have elements b-k, as the first bit used in the hit pattern is bit 1. 1 | 1b-k |\ 2 | 2b-k |\ 3 | 3b-k |\ 4 | 4b-k |\ 5 | 5b-k |\ 6 | 6b-k |\ 7 | 7b-k |\ 8 | 8b-k |\ 9 | 9b-k |\ 10 | 10b-k |\ 11 | 11b-k |\ 12 | 12b-k |\ 13 | 13b-k |\ 14 | 14b-k |\ 15 | 15b-k |\ 16 | 16b-k |\ 17 | 17b-k |\ 18 | 18b-k |\ 19 | 19b-k |\ 20 | 20b-k |\ 21 | 21b-k |\ 22 | 22b-k |\ 23 | 23b-k |\ 24 | 24b-k |\ 25 | 25b-k |\ 26 | 26b-k |\ 27 | 27b-k |\ 28 | 28b-k |\ 29 | 29b-k |\ 30 | 30b-k |\ ! Groups 31 to 35 are the forward detectors and the unsuppressed data is ! required from them, so there is no row of data for these groups. \end{verbatim} \newpage \thispagestyle{myheadings} \begin{verbatim} ! The phase II clover detectors are also suppressed by their own shields. ! They have elements a-g, as the first bit used in the hit pattern is bit 0. 51 | 51a-g |\ 52 | 52a-g |\ 53 | 53a-g |\ 54 | 54a-g |\ 55 | 55a-g |\ 56 | 56a-g |\ 57 | 57a-g |\ 58 | 58a-g |\ 59 | 59a-g |\ 60 | 60a-g |\ 61 | 61a-g |\ 62 | 62a-g |\ 63 | 63a-g |\ 64 | 64a-g |\ 65 | 65a-g |\ 66 | 66a-g |\ 67 | 67a-g |\ 68 | 68a-g |\ 69 | 69a-g |\ 70 | 70a-g |\ 71 | 71a-g |\ 72 | 72a-g |\ 73 | 73a-g |\ 74 | 74a-g |\ \end{verbatim} \end{document}