Next: About this document
Up: DASH: A Data Analysis
Previous: Disk-based ntuples: example code
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
'dst_common.inc' ***. 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
statement.
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)
DASH> INPUT RUNxxxxxx.DST
DASH> PATH DST2ZEB
DASH> SET/WRITE ZWRITE
DASH> OUTPUT ON RUNxxxxxx.ZDST
DASH> ANA
(Convert ZEBRA to DST)
DASH> SET/READ ZREAD
DASH> INPUT RUNxxxxxx.ZEB
DASH> PATH DST2ZEB
DASH> OUTPUT ON RUNxxxxxx.DST
DASH> ANA
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
by ZEBRA.
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)
TALK ZREAD LREC 5400
TALK ZWRITE LREC 5400
INP FILENAME (for a file on disk)
or INP /dev/nrtape tplx (for a file on tape)
OUTPUT ON OUTFILE
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
sgitovax.com. 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.
ETK