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.