What you should know before you start

The basic data elements of HBOOK are the histogram (one- and two-dimensional) and the Ntuple. The user identifies his data elements using a single integer. Each of the elements has a number of attributes associated with it.

The package is organised as part of a library, from which at load time unsatisfied externals are searched and loaded. In this way only those subroutines actually used will be loaded, therefore minimising the space occupied in memory by the code. Unfortunately, given the way Fortran works and although the package is structured as much as possible in the sense of selective loading, some unused subroutines will usually be present.

HBOOK uses the ZEBRA [bib-ZEBRA] data structure management package to manage its memory (see chapter [more info]). The working space of HBOOK is an array, allocated to the labelled common /PAWC/. In ZEBRA terms this is a ZEBRA store. It is thus necessary to reserve as many locations as required with a declarative statement in the main program. The actual length of the common is defined most safely via a PARAMETER statement, as shown below: 

                    ##-------------------------------+
                    ## PARAMETER (NWPAWC = 50000)    |
                    ##-COMMON-/PAWC/-HMEMOR(NWPAWC)--+

Furthermore HBOOK must be informed of the storage limit via a call to HLIMIT. This is discussed in detail in section [more info]. In the case above this would correspond to 

                          +--------------------+
                          |CALL HLIMIT(NWPAWC) |
                          +--------------------+
At execution time, when histograms are booked, they are accomodated in common /PAWC/ in booking order, up to the maximum size available. Note that a call to HLIMIT will automatically initialise the ZEBRA system via a call to the routine MZEBRA. If ZEBRA has already been initialised, ( HLIMIT should be called with a negative number indicating the number of words required, e.g. 

                         +----------------------+
                         | CALL HLIMIT(-NWPAWC) |
                         +----------------------+

HBOOK parameter conventions

Histogram or Ntuple Identiers

Histograms and Ntuples in HBOOK are identified by a positive or negative integer. Thus the histogram identifier ID = 0 is illegal at booking time. However it is a convenient way to specify that the option or operation applies to all known histograms in the current working directory (e.g. output, input, printing). All routines for which a zero identifier is meaningful are mentioned explicitly.

Parameter types

In agreement with the Fortran standard, when calling an HBOOK routine the type of each parameter must correspond to the one described in the routine's calling sequence in this manual. Unless explicitly stated otherwise, parameters whose names start with I, J, K, L, M or N are integer, the rest real, with the exception of those beginning with the string CH, which correspond to character constants.

Data packing

All booking commands that reserve space for histograms or plots require the ``packing'' parameter VMX. It corresponds to the estimated maximum population of a single bin, on the basis of which a suitable number of bits per channel will be allocated. This allows several channels to be packed in one machine word, and thus to require less storage space (at the expense of packing and unpacking processing time). A value VMX=0.0 signals that no packing is to be performed and that each histogram channel will occupy one machine word.