*B..BKID Short description of bank with hollerith Id BKID *B.AU Author1, Author2 *B.VE 5.12 { version number} *B.ST ISTOR { mnemonic of the store} *B.DV IRODIV { mnemonic of the division} *B.NI NUMID { numerical identifier} *B.ND NDATA { number of data words} *B.IO IOCHAR { IO characteristics} *B.NZ NZERO { number of data words preset to zero} *B.NL NLINKS { total number of links} *B.NS NSLINKS { number of structural links} *B.NX NXID { NXID: Id of a possible next bank} *B.UP UPID -JB { UPID: Id of Up-bank, JB is the link offset of bank BKID} *B.OR ORID { ORID: Id of Origin-bank}
*B.LINK { indicate start of link description} *B.1 D1ID Short description of D1ID { D1ID: Id of first down bank} *B.2 D2ID .... *B/LINK { indicate end of link description}
If a link is not (yet) defined the mnemonic NOTU
should be used
to avoid that DZDOC produces a diagnostic message.
*B.RLINK { indicate start of Rlink description} *B.1 D1ID Short description of D1ID { D1ID: Id of referenced bank} *B.2 D2ID .... *B/RLINK { indicate end of Rlink description}
*B.BI { indicates start of status word bits description} *B.1 NOAUTH no authorisation to modify directory *B.2 MODIFIED directory has been modified *B.3 LOCKED file locked by 'RZFILE' *B.4 ORGREL ORGANIZATION='RELATIVE' on VAX *B.5 CACCESS C file access routine used *B.11-17 LOGLEVEL 11-17 LOG level (default taken from MZ) *B/BI { indicates end of status word bits description}
*B.DATA { indicates start of data word description} *B.1 DATAWOR1 Description of data word 1 *B.REP 5 *B.1 DATAWOR2 Description of data words 2 - 6 *B/REP *B/DATA { indicates end of data word description}
DATAWOR1
.. DATAWOR7
are (upto) 8 characters mnemonics
which can be selected by the user.
The data type and range may optionally be given in the description. The format is as given in the following examples:
*B.DATA *B.1 EVENTTYP IO:I [1,200] Event type, Integer, range: 1-200 *B.2 ENERGY IO:F [0.,100.] Energy *B/DATAAllowed IO specifiers are
B, I, F, D, H, R ,U
corresponding to the
ZEBRA IO characteristics, R
is the same as F
,
U
the same as B
.
The following special mnemonics are used to specify the content of
a data word in more detail.
They are interesting not only for documentation
purposes but even more when using the documentation within the
interactive bank display: They allow to selectively print lines of
the documentation depending on values of data words or byte portions
of them. They must appear on cards following one with a general
description whereby the dataword number has to be be repeated
(i.e. the 3 in *B.3
). This is to clearly distinuish them from
normal continuation cards, for which the sequence number and the
mnemonic field is left blank. The different types may be mixed for
one data word.
The mnemonic WILDCHAR
or MASK
allows to describe a choice
depending on the printed value of the dataword allowing
wildcard characters. The mask is taken from the first characters of
the comment field separated by a blank from the description.
An asterix is used to represent one wild character.
In the following example it assumed that ATTRIBUT describes the
attributes of a graphic object. They may be decimal coded in the
following manner: ATTRIBUT = 10000*TYPE + 100*SIZE + COLOR
Example of a choice with wildcard characters
*B.3 ATTRIBUT Graphics attributes: *B.3 MASK 1**** line, *B.3 MASK 2**** box, *B.3 MASK 11**** circle, *B.3 MASK ****01 black *B.3 MASK ****02 red *B.3 MASK ****03 greenIf the value of ATTRIBUT happens to be 20503 the documented printout is:
3 ATTRIBUT 20503 Graphics attributes: box, green
If hexadecimal coding is appropriate one can force hexadecimal
formatting of the printout by preceeding the mnemonic be B:
like in this example (Note: Only 6 characters are left for the name):
Example with hexadecimal formatting
*B.4 B:TRTYPE Trigger type: *B.4 MASK *******1 energy, *B.4 MASK *******F multiplicity, *B.4 MASK ******1* tracks, *B.4 MASK ******2* clusters,
The mnemonic C1234567
, where 1234567
can be any 7-digits integer
number, describes a variable with a choice value.
If a data word is described like this,
then in an interactive session, where values of
datawords together with their documentation can be shown,
only the line for which the choice applies will be displayed.
Leading zeros may be left out or replaced by underscores.
Negative values are possible.
Example of an integer choice value
*B.8 MYCHOICE The following applies *B.8 C0000010 Meaning of 8. word, if it has value the 10 *B.8 C____111 Meaning of 8. word, if it has value the 111 *B.8 C-10 Meaning of 8. word, if it has value the -10 *B.8 C12 Meaning of 8. word, if it has value the 12
The memonic BITVAL12
, where 12
stands for any 2-digits integer
between 0 and 31, describes a data word where single bits are significant.
In an interactive session only those lines are shown
for which the corresponding bit is set in the dataword.
Example of a bit mask
*B.9 YOURBITS Single bits are significant *B.9 BITVAL01 Significance of bit 1 *B.9 BITVAL15 Significance of bit 15
The memonic BITS0309
, where 03
and 09
stand for any 2-digits integers between 0
and 31
,
describes the bit portion of a data word.
When datawords are dumped with documentation the value
of the bit portion will be printed.
Example of a bit description
*B.9 IZCODE Coded hit value *B.9 BITS0007 Wire number *B.9 BITS0815 Charge *B.9 BITS1623 Theta value
ZEBRA provides and uses a Hollerith format, which is transportable.
These words should be documented with a mnemonic starting with
Z:
. In this case DZDOC will call ZITOH and UHTOC to print
it as a character. A mnemonic starting with B:
forces DZDOC
to print the value in hexadecimal. D:
assumes that the upper
bits of the word contain a packed date and time which is decoded
by the RZ routine RZDATE.
The mnemonic P:ABCDEF
, where ABCDEF
can be any name,
describes a variable used as a pointer within the current bank.
If during the display of
the contents of a bank the word number to which the variable points,
is reached, the documentation for this section of data is expected
at L:ABCDEF
and is tagged in the output with the string --Label:
.
The string N:ABCDEF
may be used to flag a variable when
used later as a repetition count (see below).
The description of the RZ top bank in Section
contains extended applications of pointers, labels etc.
Example of the use of a pointer
*B.4 P:LDIR Pointer to subdirectories *B.5 N:NSDIR Number of subdirectories ... *B.1 L:LSDIR Subdirectory structure *B.REP N:NSDIR Loop through subdirectories *B.1 Z:NAME Name *B.2 IRECSD Record number *B.3 D:DATE creation date and time *B/REPPointers and repetition counts can also be bitportions of a variable. Assume that the lower 16 bits of a word contain a pointer, the upper 16 are the repetition count. In this case the syntax is as given in the following example: Note that the name of the pointer is taken from the first 6 characters of the comment field or until a blank is encountered.
Pointer, count which is a bitportion
*B.4 SUBDIR pointer to, and number of subdirs *B.4 P:BI0015 LDIR Pointer to subdirectories *B.4 N:BI1631 NSDIR Number of subdirectories
Note: When generating FORTRAN code the prefixes N: etc. will be removed.
If the same kind of data words or links are repeated several times
they may be described within a *B.REP
.. *B/REP
clause.
Repetitions may include groups of data words or links.
The repetition count may be fixed, variable
(indefinite) or calculated from a data word or taken from a previous
data word as shown above.
*B.LINK *B.REP 25 *B.1 DXID Short description of DXID *B/REP *B.26 DYID .... *B.27 DZID .... *B/LINK
*B.LINK *B.REP NREPS Comment *B.1 DXID Short description of DXID *B/REP *B/LINK
Repetition counts given as a simple expression of the current data word are decoded by routine DZDDWD.
Example of repetition counts for documenting data words
*B.DATA *B.REP NUMH *B.1 IHEAD Header word for a hit *B.1 BITS0007 IWNUM wire number *B.1 BITS0819 IT0 start of scanner pulse *B.1 BITS2031 LENH number of samples for this scanner pulse *B.REP BITS2031+1 / 2 ! =(LENH+1)/2 *B.1 IHIT Coded FADCs Samples *B.1 BITS2429 1st sample HV side *B.1 BITS1621 1st sample signal side *B.1 BITS0813 2nd sample HV side *B.1 BITS0005 2nd sample signal side *B/REP (LENH+1)/2 *B/REP NUMH *B/DATA
In this case the outer loop runs over a indefinite number NUMH
of
hits each of which is preceeded by a header word IHEAD
.
The 12 most significant bits of IHEAD
are used to calculate the repetition count of the inner loop describing
the individual samples of one hit.
Note that in the present example 2 samples fit into one 32-bit word).
For specifying a repetition count the allowed operators are:
BITSnnmm
indicating the bit portion, +
, -
, /
and
*
with constant parameters.
The evaluation is strictly left to right, no brackets are allowed.
Blanks are not significant, comments are separated by `!'.
The decoding is triggered by the keyword BITSnnmm
.
In the simplest case the current word could be directly the repetition
count:
Example of how to specify a repetition count
*B.1 NSAMPLES *B.REP BITS0031 ! current word = repetition count *B.1 IPULSE1 Pulseheight of Channel 1 *B.2 IPULSE2 Pulseheight of Channel 2 *B/REP
It may happen (especially for detectors which are split into two
sides) that the description of data words and links of two banks are
identical only differing in the linkage
(I.e. only the Up-bank is different).
In this case the tag *B.IDEM
may be used to avoid
duplication of the documentation.
Example of the use of the IDEM
keyword
*B..DEHR Header bank of right side ... *B.LINK *B.1 DEDA Bank containing actual data .. *B/ -------------------------------------------------------- *B..DEHL Header bank of left side ... *B.LINK *B.1 DEDA Bank containing actual data .. *B/ -------------------------------------------------------- *B..DEDA Bank containing actual data .. *B.UP DEHR .... full description of bank DEDA (possibly including links) .... *B/ -------------------------------------------------------- *B..DEDA *B.UP DEHL *B.IDEM DEHR *B/
The bank which is fully described (in this example DEDA
with
Up-bank DEHR
) must preceed the description containing the
IDEM
tag.
The documentation for a bank must be terminated by:
*B/
Card image File describing the bank EV
*B..EV Event header bank. *B.AU S.Holmes *B.VE 402 *B.ND 10 *B.NL 2 *B.NS 2 *B.NX None *B.UP None *B.OR None *B.IO '3H 3I -F' *B.LINK *B.1 VX Vertex bank *B/LINK *B.DATA *B.1 LABNA Name of laboratory *B.2 EXPTNA Name of experiment *B.3 DAQNA Initials of shift crew *B.4 IHDAT Data type *B.4 C1 Experiment data *B.4 C3 Test beam data *B.4 C4 Cosmic ray data *B.4 C5 Monte-carlo data *B.5 IIEVT Trigger number *B.6 IIFITY Filter type (Bit string) *B.6 BITVAL00 Sum E(clus) > 2 GeV *B.6 BITVAL01 E(EB cls/blk) > 200MeV *B.6 BITVAL04 Lumi Event *B.7 IITHRU Thrust * 10000 *B.8 IICTHR Cosine of the thrust axis * 10000 *B.9 IIECAL Total Electromagnetic Energy *B. (in units of MeV) *B.10 IIHCAL Total Hadronic Energy *B/DATA *B/