Currently support is implemented for all HBOOK file handling. It is
possible to have A_C open more than one histogram file. Each file has an
associated histogram stream number, analogous to an output file stream.
For the purposes of this note I will restrict the discussion to using only
one file. Since HBOOK is the default package in BUILD_JOB the only thing
you must consider at this stage is how big you should dimension the PAWC
common block. N-tuple users will want to make it at least 500,000 long
words this is done with the command:
SET SIZE/HBK4=500000
BUILD_JOB will then generate code needed for the HBOOK interface.
Special care must be taken when booking the older row-wise Ntuples. First you
need to know the top level directory of the HBOOK file. You
get this information from A_C with the following function:
STATUS = ANGTH4(STREAM,TOPDIR,FILNAM,OPNOPT)
Where STREAM is the stream id for which the information should
be returned. Most users should use the default steam (ie. set STREAM = 1).
The following are RETURNED arguments: TOPDIR is
the Top directory string, FILNAM is the Filename string that
the user typed in with the "HIST OPEN..." command and OPNOPT is
a character*2 variable indicating the open option as described
as CHOPT in the documentation for HROPEN. An example set of
calls to book Ntuples is:
NBUFF = 10000
STATUS = ANGTH4(1,TOPDIR,FILNAM,OPNOPT)
CALL HBOOKN(NID,TITLE,NVAR,TOPDIR,NBUFF,CHAR)
Note that stream 1 is specified. This will always work if the user uses the defaults at the ANA>> prompt. The other thing to be careful with is the relative size of NVAR and NBUFF. NBUFF is the size of the buffer in memory that must be used up before the buffer is written to the HBOOK disk file. If it is too large the Ntuple will take up too much of the PAWC common block. If it is too small writes to disk will happen too frequently. Since HBOOK/ZEBRA allows these buffers to be read back in there is some overhead in writing to disk. Pointers are stored in the PAWC common for each write. This is why it is possilbe to write too frequently. Some users have managed to run out of space in the PAWC common by filling it up with pointers. When this occurs, the error is fatal and not very informative. For users of the newer column-wise Ntuples no special A_C calls are necessary and the calls to HBNT and HBNAM[E/C] are much simpler. For more information on the pros. and cons. of using the different types of Ntpules see the cern hbook document.
A_C uses the HBOOK directory structure in order to avoid histogram id collisions between two different user modules. Each A_C module's histograms get booked and filled into it's own subdirectory. The name of the subdirectory is the module name. What this means to the user is that someone else's module can not accidently fill entries into your histograms however when you want to read the HBOOK output you will have to change directory to the correct directory to see your histograms. In PAW you can use the command "cd <module-name>". In a fortran program that reads the output histogram file you can call HCDIR('<module-name>',' ').
In the analysis control program you must give the following commands at the
ANA>> prompt (or in your uic file). This is a minimal set:
HISTOGRAM OPEN
HISTOGRAM ON
BEGIN...
HISTOGRAM WRITE
Row-wise Ntuple users should be warned that there is an upper limit to the
allowed size of HBOOK files. The way RZ files are implemented in HBOOK a maximum
number of direct access file records are allocated when the file is opened.
The default value is 4000 and can be up to 65000. The record length is the
number of longwords/record so the total number of longwords in the file
would be the product of these two parameters. The VAX has a maximum record
length of 8191 longwords so there will be an absolute limit
no matter what you do. One word of caution.
If you max out both of these parameters you will probably need a bigger
size PAWC so I would suggest only doing this if you are now having
problems. In order to change these values from the default values you can
use these two qualifiers on the "HISTOGRAM OPEN" command.
They are:
/MAX_NREC=<max._number_of_records>
and
/RECLENGTH=<record_length> (in longwords)
For a full discription of how these parameters affect the allowed size of your row-wise N-tuple see the note written by John Marrafino PM0082-S. It's called "Writing Large Ntuple Files via HBOOK" and it is also available in the FNAL computing division library. For more information about the "HISTOGRAM OPEN" command see Appendix A. Note that the above comments are also true for column-wise Ntuples but because column-wise Ntuples are more space efficent many users do not encounter the same space problems.