next up previous contents
Next: About this document Up: DASH: A Data Analysis Previous: Disk-based ntuples: example code

MADLIB: A library of example modules


AAA_README_ABOUT_MAD                          E. Kearns, G. Ludlam, C. Okada

This documents the files in the Muon Analysis DST (MAD) library. It
includes the standard MUA (also Muon Analysis) code for reading the DST
files made on VAXGS. The library contains several DASH modules as well
as utility subroutines called by those modules. You may link to this
library and use the utility subroutines outside of the DASH environment-
you might find the print routines especially useful.

To use these routines on VAXGS, simply link to [MACROUSA.MAD]MADLIB/L.
You should also point your include statements to the include files in
this directory. This directory will always be the current official
release, the source code and development versions will be kept in
subdirectories such as [.V21]. To install on a remote computer, see the
instructions in [.V21]AAA_HOW_TO_INSTALL.TXT.

In this area I have included a copy of the DST common block that you can
point to. The latest version of the DST common block now holds all of
the variables used in the past (e.g. IMBU data) as well as the current
version (whatever that might be). So regardless of which read
subroutines you use, all of your analysis code should now *** include
'' ***. Hint: use lower case filenames to make migrating
to unix easier.

MADREAD  is a DASH read-module that reads the unformatted DST events into
         the DST common block. It calls the MUAREAD subroutine which
         contains the big read statement that describes the DST
         structure. You will see several versions of MUAREAD in this
         area as well as hooks in the MADREAD module to select which one
         to call. This was put in when there were multiple file versions;
         the current MUAREAD is advertised to read all versions past and
         present (.TDST and .DSTE for example); this is the routine called
         by default, so do not worry about the extra routines and hooks.

MADWRITE is a DASH write-module that writes the DST information back out
         in the same compressed form that MUADST does. It calls MUAWRITE
         which contains the big read statement changed into a write

MADDUMP  is a DASH module that dumps printed information from the DST
         common block to the screen. It contains a TALK entrypoint which
         you can use to turn off information you are not interested in.

MUAPICT  is a DASH module which uses HIGZ to make a graphics display
         of the information in the MUADST common block. If you include
         this module, be sure to perform the HIGZ initialization as
         described in the DASH manual. You will find that initialization
         also in EXAMPLE.FOR (but commented out).

DST2ZEB  is a DASH module that converts the DST information into a ZEBRA
         structure. The ZEBRA structure mostly contains the compressed
         information, but due to overhead, is about twice as big as the
         binary DST files. The primary purpose is to write exchange format
         files for transfer to Unix. This directory contains INCLUDE files
         you should use that define the offsets into the bank for each
         variable. The file ZEB_COMMON.INC sets up the ZEBRA store and
         declares the arrays IQ and Q that contain the banks.

ZEB2DST  is a DASH module that converts the ZEBRA structure back into
         the DST common block.

ZREAD    is a DASH read-module that reads in ZEBRA structures. It will
         actually read in any ZEBRA structure, but special hooks have
         been put in to recognize ZEB2DST banks and RAWR banks (MACRO
         raw data). It will do byte-swapping on MACRO RAWR if necessary
         (the DREAM routine BYTSWP is included in this library). The
         TALK entrypoint can call of the DZ diagnostic subroutines. Try
         TALK ZREAD DZSURV after reading in an event.  The record length
         is 900 bytes by default, but can be specified such as TALK
         ZREAD LREC 5400 (LREC appropriate for MACRO raw data). The
         CHOPT for the FZFILE call is 'LXP' by default, but can be
         specified as the optional third argument to the INPUT command;
         for example: to read events from tape under unix, we use: INPUT
         /dev/nrtape TPLX.

ZWRITE   is a DASH write-module that writes out ZEBRA structures. It has
         the same interface as ZREAD for specifying LREC and CHOPT, but
         it does not share these variables- they must be set separately.

MUAPRINT is a set of utility subroutines that print the variables in
         the DST common. It is aclled by MADDUMP, however you may use
         this outside of DASH by calling MUAPRINT_ERP(LUN) and so on.

Since these modules are useful to convert the DST common block into
ZEBRA banks for exchange with UNIX computers, let me provide an example
and remind you how DASH handles multiple READ/WRITE-modules. This is an
instance where you would use the rare DASH command SET/READ and
SET/WRITE. Let us assume that you built an executable linking in
MADREAD, MADWRITE (declared primary read/write modules in subroutine
DASH_DECL with DASH_DEC_REA and DASH_DEC_WRI) as well as ZREAD and
ZWRITE. Here are example sessions:

(Convert DST to ZEBRA)

(Convert ZEBRA to DST)

Note: this is also an unusual instance where the order of the
commands matters somewhat. You must SET/READ before INPUT
and SET/WRITE before OUTPUT so that the files are opened correctly
Here are some notes about working with MACRO-style ZEBRA raw data (GJL):
ZWRITE writes the data out with bytes in the VMS order. That is, the
data is the same as if it had come directly off of a data tape.  So when
reading in UNIX, it will generally be necessary to swap the bytes.  We
check using the data whether or not this is necessary by comparing the
header with the bank.  (The header is always in the correct order.)
ZREAD does this automatically.

When opening a file to write out in DASH, there is generally no need to
specify the CFOPEN options.  The correct (default) options are LXO.  If
for some reason one wishes to write out the data in 'SWAPPED' format
(the format that UNIX understands), then do the following in DASH: TALK
ZWRITE SWAP 0.  This will turn off the 'unswapping'.

For MACRO data, the record length must be specified (5400 bytes,
currently) because the default behavior for ZREAD and ZWRITE is set for
the DST ZEBRA files (900 bytes). Use TALK ZREAD LREC 5400 and TALK
ZWRITE LREC 5400 to make this correct.

Here is a synopsis of how to correctly read in and out macro data:
	(start dash program)
	INP FILENAME  (for a file on disk)
     or INP /dev/nrtape tplx (for a file on tape)

Very simple. Now, this output file should be readable by DREAM on the
same machine. To read in the file on a VMS machine, do the following:

First, FTP the file to the VMS machine in BINARY mode. This will
transfer the file in 512 byte blocks. That is, the BLOCKSIZE will now be
512. However, we need the blocksize to be 21600 (which is 4 times the
record-length (5400)). So we have to run a command file to change that.
The command file is printed on p. 56 of the ZEBRA FZ reference manual.
It exists on buphyc::buphyf$dub0:[macro.ludlam.anal.wfd] and is called It uses the vms utility EXCHANGE. One can specify the
BLOCKSIZE here, and it needs to be 21600. (The example in the manual
gives 3600.)  When that is done, the file is DREAM readable.