Describing the columns of a CWN

CALL HBNAME (ID, CHBLOK, VARIABLE, CHFORM)

CALL HBNAMC (ID, CHBLOK, VARIABLE, CHFORM)

Action: Describe the variables to be stored in a CWN (non-character and character variables, respectively).

Input parameters:

ID

Identifier of the Ntuple as in the call to HBNT.

CHBLOK

Character variable of maximum length 8 characters specifying the name by which the block of variables described by CHFORM is identified.

VARIABLE

The first variable that is described in CHFORM. Variables must be in common blocks but may not be in a ZEBRA bank. For example, given the common block CEXAM described below, one would call HBNAME with the argument IEVENT. In the case of character variables, the routine HBNAMC must be used. In all other cases one should use HBNAME.

CHFORM

Can be either a character string describing the variables to be stored in block CHBLOK or:

'$CLEAR'

To clear the addresses of all variables in the Ntuple.

'$SET'

To set the addresses in which to write the values of all variables in block CHBLOK.

The last two forms are used before reading back the Ntuple data using HGNT, HGNTB, HGNTV or HGNTF. See also HUWFUN.

With CHFORM the variables, their type, size and, possibly, range (or packing bits) can all be specified at the same time. Note however that variable names should be unique, even when they are in different blocks.. In the simplest case CHFORM corresponds to the COMMON declaration. For example:

       COMMON /CEXAM/ IEVENT, ISWIT(10), IFINIT(20), NEVENT, NRNDM(2)

       CHFORM = 'IEVENT, ISWIT(10), IFINIT(20), NEVENT, NRNDM(2)'

The default type and size of a variable can be overridden by extending the variable name with :<t>*<s>:

When the range of a type U, I or R variable is known, its storage size (number of packing bits) may be added behind the :<t>*<s> specification using :<b> for types U and I and :<b>:[<min>,<max>] for type R. Floating-points are packed into an integer using:

IPACK = ((R - <min>)/(<max> - <min>)*(2**<b> - 1) + 0.5

When :<b>... is not specified a variable is stored using the number of bytes given by <s> or the default. In case the default type and size of a variable should be used, the packing bits can be specified as ::<b>.... <b> must be in the range 1$\le$ b$\le$ 8*<s>. Automatic bit packing will happen, for type U and I, when a range is specified like: ICNT[-100,100]. In this case ICNT will be packed in 8 bits (7 bits for the integer part and 1 bit for the sign). In case CNT is an integer ranging from -100 to 100 it could be specified either like CNT[-100,100]:I or like CNT:I::[-100,100]. Logical variables will always be stored in 1 bit. All variables must be aligned on a word boundary and character variables must have a length modulo 4. The maximum length of the variable name is 32 characters.

Variable-length Ntuple rows and looping over array components are also supported to optimize Ntuple storage and Ntuple plotting. Variable row length can occur when arrays in the Ntuple depend on an index variable.

Example of a variable row length CWN definition

      PARAMETER (MAXTRK = 100, MAXHIT = 300)
      COMMON /CMTRK/ NTRACK, NHITS(MAXTRK), PX(MAXTRK), PY(MAXTRK),
     +               PZ(MAXTRK), XHITS(MAXHIT,MAXTRK), YHITS(MAXHIT,MAXTRK),
     +               ZHITS(MAXHIT,MAXTRK)
      CALL HBNAME(ID,'VARBLOK2',NTRACK, 
     +            'NTRACK[0,100], NHITS(NTRACK)[0,300],'//
     +            'PX(NTRACK), PY(NTRACK), PZ(NTRACK), XHITS(300,NTRACK),'//
     +            'YHITS(300,NTRACK), ZHITS(300,NTRACK)')

In this example the number of elements to store in one Ntuple row depends on the number of tracks, NTRACK. The call to HBNAME declares NTRACK to be an index variable and that the size of the Ntuple row depends on the value of this index variable. The range of an index variable is specified using [<l>,<u>], where <l> is the lower and <u> the upper limit of the arrays using this index variable. In the above example the lower limit of NTRACK is 0 and the upper limit is 100 (= MAXTRK). While filling a CWN HBOOK can also easily test for array out-of-bound errors since it knows the range of NTRACK. Only the last dimension of a multi-dimensional array may be variable and the index variable must be specified in the block where it is used. Array lower bounds must, just like the lower range of the index variable, be 0.

HBNAME may be called more than once per block as long as no data has been stored in the block. New blocks can be added to an Ntuple at any time, even after filling has started, whereas existing blocks may only be extended before filling has started.