@EDAS

.im @@e .* .im @defind .#duplex .im @rfres .* .im @memhg .im @offanal .* .im @index :egdoc.

@GOOBUF

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. Buffer Header :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 9.95cm center 11.7cm cente m center .el .tp 6 right 22 center 38 center 46 center 54 center 62 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ºººunused .bx º4 ºtype ºººsubtype .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm 11.7cm &colmax .el .bx set &col0 38 54 &colmax º8 ºused data lengthººfragment beginººfragment end .bx off .bx cancel º12 ººbuffer number for this type - subtype .bx º16 ººnumber of buffer elements .bx º20 ººcurrent index (=-1: IBM format) .bx º24 ººtime stamp VMS 64 bit format .bx º32 ºº4 long words reserved ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º48 ºfirst data word ºººsecond data word .bx off ººº. . . .bx off .kp off

@GOOELE

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. Buffer Element Header :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 11.7cm center .el .tp 6 right 22 center 38 center 54 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ººunused .bx º4 ºtype ººsubtype .hr &col0 to &colmax º8 ºfirst data word ººsecond data word .bx off ººº. . . .bx off .kp off

@GOOEV41

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. Event Type 4, Subtype 1 :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 11.7cm center .el .tp 6 right 22 center 38 center 54 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ººunused .bx º4 ºtype = 4 ººsubtype = 1 .hr &col0 to &colmax º8 ºfirst data word ººsecond data word .bx off ººº. . . .bx off .kp off

@GOOEV42

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. Event Type 4, Subtype 2 :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 11.7cm center .el .tp 6 right 22 center 38 center 54 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ººunused .bx º4 ºtype = 4 ººsubtype = 2 .bx º8 ºfirst data word id ººfirst data word .bx º12 ºsecond data word id ººsecond data word .bx off ººº. . . .bx off .kp off

@GOOEV61

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. Event Type 6 :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 9.95cm center 11.7cm cente m center .el .tp 6 right 22 center 38 center 46 center 54 center 62 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ºººunused .bx º4 ºtype = 6 ºººsubtype = 1 .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm 11.7cm &colmax .el .bx set &col0 38 54 &colmax º8 ºdata length subevent 1ººevent countººCAMAC crate 1 .bx off º12 ºfirst data word ºººsecond data word .bx off ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm 11.7cm &colmax .el .bx set &col0 38 54 &colmax º ºdata length subevent 2ººevent countººCAMAC crate 2 .bx off .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º ºfirst data word ºººsecond data word .bx off ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm 11.7cm &colmax .el .bx set &col0 38 54 &colmax º ºdata length subevent nººevent countººCAMAC crate n .bx off .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º ºfirst data word ºººsecond data word .bx off ººº. . . .bx off .kp off

@GOO2000

.if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 .kp on :medium. File Header Buffer :emedium. .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º27 º23 º19 º15 º11 º7 º3 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 9.95cm center 11.7cm cente m center .el .tp 6 right 22 center 38 center 46 center 54 center 62 center .* .bx &col0 &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º0 ºdata length ºººunused .bx º4 ºtype = 2000 ºººsubtype = 1 .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm 11.7cm &colmax .el .bx set &col0 38 54 &colmax º8 ºused data lengthººfrag. begin = 0ººfrag. end = 0 .bx off .bx cancel º12 ººbuffer number for this type - subtype = 1 .bx º16 ººnumber of buffer elements = 1 .bx º20 ººfor internal use (=-1: IBM format) .bx º24 ººtime stamp VMS 64 bit format .bx º32 ºº4 long words reserved ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º48 ºused length of tape labelºººtape label (30 characters) .bx cancel ºººtape label (continuation) ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º80 ºused length of file nameºººfile name (86 characters) .bx cancel ºººfile name (continuation) ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º168 ºused length of user nameºººuser name (30 characters) .bx cancel ºººuser name (continuation) ººº. . . .hr &col0 to &colmax º200 ººdate 'dd-mm-yyyy hh:mm:ss.mm' (24 characters) ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º224 ºused length of run id.ºººrun id. (66 characters) .bx cancel ºººrun id. (continuation) ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º292 ºused length of exp. spec.ºººexp. spec. (66 characters) .bx cancel ºººexperiment specification (continuation) ººº. . . .hr &col0 to &colmax º360 ººnumber of comment lines following .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º364 ºused length of line 1ºººline 1 (78 characters) .bx cancel ºººline 1 (continuation) ººº. . . .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º444 ºused length of line 2ºººline 2 (78 characters) .bx cancel ºººline 2 (continuation) ººº. . . .hr &col0 to &colmax ººº ººº. . . ººº .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax ººused length of line nºººline n (78 characters) .bx cancel ºººline n (continuation) ººº. . . .bx off .kp off

@TOC

:medium :toc. .pn off

C

.im c2

COFFALL

.tr _ 41 .pn pref .se pre = 'Offline Data-Reduction' :prefix. .dh 1 NTC .dh 2 PA .dh 2 TCIN 2 .dh 2 TFONT hi2 .dh 4 TC .dh 2 NUM .dh 3 NUM .dh 4 NUM :medium. .pt .im cof1intr :toc .pt .im cof2raw .pt .im cof3sat .pt .im cof4goo

COF1INTR

.se pre = 'Offline Data-Reduction' :prefix.

Offline Data-Reduction

With the experiments performed at the UNILAC and SIS/ESR at GSI, large amounts of data are collected. In general they consist of events with many parameters obtained from multiple coincidences between multi-parameter detectors. SATAN, the System to Analyze Tremendous Amounts of Nuclear Data, is a system of programs and tools designed to analyze data from such experiments. SATAN runs on the IBM host in the computing center and offers all functions needed for the evaluation of experiments, from storage and reduction of list mode data up to the graphics support for the final publication. The functionality provided by the SATAN environment at GSI covers the following areas:

  • Storage of large amounts of raw data in a Automatic Tape Library (ATL).
  • Permanent availability of the required raw data on IBM disk, utilizing the powerfull functions of the IBM Hierarchical Storage Manager (HSM).
  • Analysis and reduction of large amounts of experiment data.
  • Evaluation of spectra with powerful tools for arithmectics, fitting, unfolding, linearizing, ...
  • Graphical representation of results on terminals and plotters.
SATAN accepts input of data gathered with the GSI data acquisition system GOOSY, and also with the old GOLDA system. Additionally, suitable interfaces are defined to enter external data with any format into SATAN.

SATAN provides a very extensive documentation available in a folder, which may be updated, and an interactive HELP facility. Please refer to this documentation :fn. H. G&o.ringer et al.,
Experiment Data Acquisition and Analysis System,
GSI Report 88-16 (ISSN 0171-4546) :efn. for more details, as the current chapter provides only a brief overview. The table of contents can be found on the next page.

COF2RAW

.se mem = 'The GSI Raw Data Handling' :head.

The GSI Raw Data Handling

Experiment raw data from tape or 3480 cartridge, with or without label, created on a VAX or IBM, can be copied to IBM disk using the .ce TSO-Command ONLTADI. With the option 'FILE(*)', complete tapes may be transfered within one job. The number of files on a single tape must not exceed 999. On IBM disk, the files are under control of the IBM Hierarchical Storage Manager (HSM), which is also responsible for storage administration of all other user data sets. Of course, the whole raw data volume of GSI experiments is by far too big for permanent storage on disk. So data currently not used are moved to a cheaper storage medium, the 3480 cartridges. A 3480 cartridge has a capacity of about 200 Mbytes, roughly 10% more than a magnetic tape, but it is much smaller, having a write density of 38,000 bpi, compared with 6250 bpi. The 3480 cartridges are as reliable as tapes and also a standard, and they are easier to handle. Especially library systems with robots for mounting and demounting and with capacities of several thousand cartridges are offered by many companies. So files not used for some days are copied by the HSM to 3480 cartridges and erased on disk ('migration'). If migrated files are needed again, the HSM copies them back to disk automatically and erases them on 3480 cartridge ('recall'). The input volumes with the original raw data (mainly VAX tapes) may be kept as backup, preferably in the computing center, where suitable conditions (climate, hanging) exist. For migration to 3480 cartridge, the HSM utilizes an Automatic Tape Library (ATL), which is based on a robot for mounting and demounting the 3480 cartridges without operator intervention. The HSM recall of a raw data file with a size of 150 Mbytes takes only 5-6 minutes of elapsed time. This concept has several advantages:

  • Only one single copy process from the original VAX tape to an IBM disk is necessary.
  • The raw data are at any time available on disk -_either immediately or within a few minutes, if an HSM recall is necessary. This is independent from the presence of operators, because the cartridge mounts are done by a robot.
  • The HSM performs data compression before migration to cartridge and decompression before recall to disk. Tests indicated a data compression of up to 30% to 40% for GOOSY raw data with fixed event length (type 4.1), thus saving a substantial portion of space on cartridges.
  • The HSM offers some flexibility in tuning the free space of the raw data disk pool. So unused files normally are more than three days available on disk before migration.
  • With ISPF panel 3.4, a list of all raw data files is available on-line indicating the current status (migrated or not) and the allocated space.
In the first column of ISPF panel 3.4, ISPF functions (e.g. BROWSE, display of data set information, ...) or data set specific TSO-Commands (e.g HRECALL or HMIGF for an explicite HSM recall or migrate, respectively) can be invoked. To select specific subsets of data files, complete name parts at the right may be omitted in this panel ('data set level' specification). Additionally some wildcard character handling is supported. The asterisk ('*') specifies a complete name part, if enclosed by dots, or the beginning or end of an uncompletely specified name part (e.g. 'MAY*' or '*MAY'). In September 90, the ATL contains &eqv.3200 cartridges, each with a capacity of 200_Mbytes. Roughly 1500 cartridges are not available for storage of raw data, but will be needed for migration and backup of other data. If necessary, the number of cartridges can be increased to &eqv.5000. Then, even if neglecting the data compression of the HSM, the ATL will have a capacity of at least &eqv.700_Gbytes for raw data. Any dataset out of this pool will be available on disk within a few minutes, independent of the presence of operators. In the future, a further migration level may be introduced for currently not used data. They will be kept outside of the ATL and must be made available by submitting a request to the operators.

Naming Conventions

Normally the raw data from tape are copied to disk without any changes. Optionally, GOOSY raw data with standard buffer headers (currently the event types 4.1, 4.2, and 6.1) can be converted to IBM representation (key word CONVERT of the TSO-Command ONLTADI) performing the necessary byte swaps and ASCII-EBCDIC conversions. This saves CPU time when analyzing the raw data on the IBM with the SATAN system. To distinguish between both types of data representations, and as a result of urgent user requests, the following naming conventions for raw data files on IBM disk have been defined. There are three main aspects:
  1. Raw data in IBM representation have a name part ('qualifier') LMDI, raw data in VAX representation have a name part LMDV.
  2. Another name part is created from the input volume name (6 characters) and the file number.
  3. The VAX tapes written by GOOSY have an ANSI label (AL). To identify the VAX origin of the raw data also on the IBM, the VAX file name is appended as the last part of the corresponding IBM data set name.
In order to meet some differences between VAX file names and IBM data set names, the VAX file names must follow some restrictions and are slightly modified according to rules described below. The disk data set names created by the TSO-Command ONLTADI look as follows: .tp 10mm 70mm ºuid.LMDV.vvvvvvff.vaxfile º(VAX representation, default)
ºuid.LMDI.vvvvvvff.vaxfile º(IBM representation, with option CONVERT) .if &$PDEV = 3820 .th .se tsize = 25mm .el .se tsize = 12
tsize=&tsize termhi=1
uid
User identification on IBM.
vvvvvv
Input volume name (six characters).
ff
File number (two digits). If files with numbers >_99 are adressed, an additional name part will be created (see below).
vaxfile
The (slightly modified) VAX file name in the case of AL volumes.
If the input volume is an IBM standard label (SL) tape or 3480 cartridge, the IBM file name on the input volume is taken instead of the VAX file name, of course. For file numbers in the range 100 to 999, the first digit 'h' (hundreds) appears in an additional name extent. The second and third digit ('ff') are appended to the volume name in the same way as for file numbers <_100: ºuid.LMDI.vvvvvvff.#h.vaxfile º(IBM representation) The resulting IBM data set name may be rather long, but it is not necessary to enter the complete name in the most important applications. Especially when analyzing such data sets in SATAN (using the INPUT command), the data set names may be abbreviated as long as they are unique. As already mentioned, VAX and IBM file names are not compatible. To enable a unique conversion, the following GSI naming conventions for names of VAX files containing experiment data have been defined:
  1. The total length of the name should not exceed 25 characters.
  2. .ti _ 6d The length of name parts separated by underscores ('_') should be smaller than 9, or smaller than 8 if beginning with a number.
  3. VAX file names end with '.LMD'.
The conversion to IBM name parts ('vaxfile') is done according to the following rules:
  1. Underscores are replaced by dots.
  2. Underscores immediately following underscores are ignored.
  3. If a name part (separated by underscores) begins with a number, it will be preceeded by a $-sign.
  4. The last extent '.LMD' will be removed.
Example: The VAX file name of file number 3 on the tape volume X123YZ is .ce MAY_87_RUN_WITH_BEAM.LMD .ti _ 41 It will be converted to IBM name parts ('vaxfile'): .ce MAY.$87.RUN.WITH.BEAM On IBM disk, the data set will have the name (e.g. in IBM representation) .ce 'uid.LMDI.X123YZ03.MAY.$87.RUN.WITH.BEAM' Evaluating this data set in SATAN using the INPUT command, the specification of .ce LMDI.X123YZ03 is sufficient (unless there are more than 99 files on volume X123YZ).

Reduced Raw Data

If raw data reduced or modified by SATAN analysis on the IBM are written to disk, they are also put under control of the HSM and therefore also permanently available. .* .go end

Raw Data Transfer between IBM and VAX

To copy raw data between the IBM 3090 and the VAX computers, there are the first releases of two DCL-Commands available on the VAX computers. With SIRAW and RIRAW, raw data files in VAX representation (IBM data set qualifier LMDV) can be sent to IBM disk or received from IBM disk, respectively. On the VAX side, any available device (disk, tape, EXAbyte, ...) may be addressed. The full functionality will be available in 1991. Then by means of these commands the raw data disk pool of the IBM, the storage manager HSM, and the ATL with a capacity of roughly 700 Gigabytes and a robot for automatic cartridge mount may be used also from the VAX computers and any workstation connected via Decnet. ...end

COF3SAT

.se mem = 'SATAN Overview' :head.

SATAN Overview

The functionality of SATAN extends from raw data processing, spectrum accumulation, and spectrum evaluation up to the preparation of graphics output for scientific publications. Due to the variety of the experiments at GSI, however, SATAN is not a closed system containing every conceivable analysis logic as a subset. Instead, the system is also able to call subroutines written by the user according to well-defined rules (see :hdref refid=cosuser.). The results of raw data analysis are

  1. reduced or modified raw data, and
  2. data structures called 'data elements'. Examples for data elements are analyzers (containing spectrum and error data), calibrations, and linearizations.
Data elements may also be created interactively using SATAN commands. In a SATAN session, for data elements about 70 Mbytes of space is available. For storage and retrieval of data elements, a data element library is provided. .******************************************************************** .se mem = 'The SATAN Environment' :head.

The SATAN Environment

The SATAN environment consists of the following main components:

  • a comfortable system for the handling of large amounts of raw data,
  • a rich set of support libraries with problem-oriented macros and procedures to write complex raw data analysis programs in high level languages (PL/I and FORTRAN),
  • a powerful command language,
  • data libraries for data elements, global parameters, and pictures,
  • program development support via specific TSO commands for compile, link, and load steps,
  • interactive help and tutorial facilities, and
  • documentation support to keep your personal SATAN manual up-to-date.
SATAN sessions may be executed in foreground under TSO/E enabling interactive data evaluation. If a dataset is specified containing a command list to be executed, data analysis will be done in a batch job. .********************************************************************

User Interfaces

To provide more flexibility, SATAN is designed as an open system. The user may add own code in order to perform nonstandard functions specific to his own data processing. Since the user code and part of the 'system' code are loaded together as one executable load module, the user section must be written carefully. An error in it might lead to overwriting the system code and produce unpredictable results. .im f1#2#1 .* user exits

There are three types of interfaces to add user written code to SATAN:

  1. The already mentioned analysis procedure. The rules are explained in detail in the next chapters. In principle, an analysis procedure has raw data as input and modified raw data or data elements as output.
  2. The user commands. With a single keyword, the command name, optionally with additional parameters, the execution of complex user-specific programs is triggered. The parameter list of these programs is arbitrary and defined by the user according to his specific needs.
    Like all SATAN commands, also user commands may be invoked interactively
    • via terminal input,
    • in a batch job from a command list on a dataset, or
    • within an analysis procedure using the macro '@EXCMD'.
    :sp The definition of user commands may be done with the library procedure $CMDDEF, either in the initialisation part of analysis programs, or in initialisation programs with the special header $INITPROC (see :hdref refid=cosinit.).
  3. The user exits. Exits are special user procedures with a definite name and parameter list. The existing user exits are summarized in :figref refid=uexits..
.********************************************************************

The Programming Language

To allow easy implementation of system control functions, the system part of SATAN is written in PL/I, with only a few exceptions written in assembler language. The programming language used to write analysis programs is also PL/I, but with powerful enhancements developed specifically for raw data processing. The most important standard functions are supplied as special language elements called 'macros', which can be expanded by a preprocessor to PL/I code. Therefore the special TSO commands PLO (foreground) and PLOB (batch) are available to compile user programs containing macros. Additionally a rich set of PL/I library routines is available. The most important standard functions offered with macros and library functions are:

  • input and output of raw data,
  • spectrum accumulation,
  • condition checking,
  • linearization of data, and
  • interactive graphics.
In addition the full functionality of SATAN commands (see :hdref refid=coscmd.) is available in analysis procedures. Any SATAN command can be invoked here with the help of a special macro ('@EXCMD').

The macro concept has many other advantages:

  • The implemented system functions form extensive blocks of code with advanced PL/I language constructs. They are all hidden from the user, who only needs to use some basic PL/I statements.
  • It is very easy for the user to add new functions into existing programs.
  • Existing macros can be enhanced without need to change existing analysis programs.
  • The execution speed for analysis programs can be optimized without program change by generating better code with the preprocessor.
There are two groups of macros available distinguished by the first character of their name. All macros beginning with a '$'-sign can be used only in analysis programs starting with a standard program header. All macros beginning with a '@'-sign are also available in user defined commands or user exits.

FORTRAN is certainly more familiar to scientists than PL/I. Therefore FORTRAN subroutines may also be invoked in a user's interface. The structure of analysis programs is described below in more detail. .********************************************************************

Analysis Programs

As a convention, all macro names begin with a '$' or a '@' (at-sign), and all system variable names contain a '$' and/or a '@'. Therefore the user should avoid these characters in choosing his own variable names. Several analysis program headers are available in SATAN for different tasks and raw data formats:

  • $GOOPROC for the analysis of any GOOSY events,
  • $LISTPROC for the analysis of fixed length events in SATAN format,
  • $LISTVAR for the analysis of variable length events in SATAN format, and
  • $ANLPROC for analysis subroutines evaluating events of fixed length in SATAN format.
The evaluation of the different GOOSY raw data types is described in detail in :hdref refid=goosyda.. The following picture shows the sceleton of an analysis routine for the evaluation of raw data in SATAN format and with fixed event length. However, in principle the structure of analysis programs processing GOOSY data is the same. .im f3#3#1

Beginning and end of an analysis routine have to be marked by SATAN macros, in this example $LISTPROC and $ENDANL, respectively. The first part of the procedure ('definition part') contains definitions, initializations, and storage allocations of all data structures to be used in the following analysis part. Here all analyzers have to be created, all global parameters must be declared, and any user commands must be defined. The definition part is executed only once during the initialisation phase of the SATAN system.

The analysis part, which starts at $ANTRY, is executed each time a block of raw data is ready for processing. Each block consists of several events, which are handled event by event. This event loop is delimited by the macros $EVENT and $ENDEVT and may contain the macro and library calls for spectrum accumulation, condition checking, output of modified or reduced raw data, and so on. In this example, each event consists of the same number of (two-byte) parameter values (fixed event length). .********************************************************************

Initialisation Programs

Within initialisation programs, no raw data analysis can be performed. Especially the macros $ANTRY, $EVENT, and $ENDEVT are not available here. Initialisation programs may be used to define user commands for SATAN sessions without raw data analysis. An example is shown in :figref refid=ansceli.. .im f3#3#1i The command procedure 'myentry' must be provided by the user, either included as PL/I entry in the initialisation program, or as external subroutine. Like the definition part of analysis programs, initialisation programs are executed only once during the initialisation phase of the SATAN system. It is not allowed to load initialisation programs and analysis programs together for one single SATAN session! .********************************************************************

The Command Language

The interactive SATAN command language allows execution of standard functions. It gives the possibility
  • to change
    • the flow of control in analysis procedures, and
    • the flow of data by defining input and output data streams,
    utilizing the powerful global parameter tool of SATAN,
  • to scan, dump, and copy binary data on magnetic tape or 3480 cartridge volumes,
  • to store and retrieve data from libraries,
  • to manipulate data,
  • to visualize data with a variety of display commands,
  • to fit model functions (system- or user-defined),
  • to deconvolute data distributions,
  • to linearize spectra, or
  • to execute lists of such commands.

The user communicates with the system via graphic and/or alphanumeric screen by means of which he issues commands and receives the results of the processing, mainly in a graphical form. Generally the name of a command is chosen such that its purpose is more or less obvious. With few exceptions, the first letter of a command name denotes the functional class the command is belonging to:

compact tsize=8 termhi=0.
___A
Analyzer commands
___D
Display commands
___F
Fit commands
___I
Input/output and global parameter commands
___L
Linearization commands
___M
Magnetic tape or 3480 cartridge commands
___$
System control commands
.kp off A few frequently used commands do not obey these naming rules (e.g. 'HALT', 'HELP', 'REPEAT', 'TUTORIAL', 'EXIT').

Three different types of command parameters are possible.

  • Required positional parameters.
    These parameters are always required by the system and cannot be defaulted. They are entered as values (numbers or character strings) immediately following the command name and are identified by the order in which they appear.
  • Optional positional parameters.
    They are also identified by the order in which they appear but may be omitted causing default values to take effect. Individual parameters may be defaulted by the use of adjacent commas. The list as a whole may be truncated from the end (right to left).
  • Optional parameters.
    Optional parameters are identified by a name (keyword) which may be followed by a value (number(s) or character string) enclosed in parantheses. Separated by the special character '/' from the list of positional parameters, they may be entered in any order. If omitted, default values take effect.
    Optional parameters without an argument act as a switch having the two possible values '0' and '1'.
Each optional parameter is provided with a default value. Two kinds of default values are possible:
  • Static defaults.
    Their values are unchanged and take effect each time the corresponding parameters are not explicitely specified.
  • Replaceable defaults.
    They act like static defaults, but their values are overwritten by the corresponding parameter values used last.
Most command and parameter names may be abbreviated as long as the remainder is unique
Example:
Display analyzer A of event type LIST within the limits of channel numbers 100 and 260. DISP A LIST / WINDOW(100,260) is equivalent to D A LIST / W(100,260) If a parameter value includes delimiters (blank, comma or slash), it must be enclosed in single quotes. A single quote itself is included by immediately repeating it.
Example:
Write the character string "SATAN'S_ANALYZER" (positional parameter) as comment on the current picture. DWRITE 'SATAN''S ANALYZER' A list of optional positional parameters can only be truncated from the end (right to left). However, an individual item may be omitted if a comma is typed instead.
Example:
Assume the command EXAMPLE to be defined with three positional parameters.
compact tsize=20 termhi=0.
EXAMPLE__,B_C
the 1st parameter is defaulted
EXAMPLE__A,,C
the 2nd parameter is defaulted
EXAMPLE__,,C
the 1st and 2nd parameters are defaulted
EXAMPLE__A
the 2nd and 3rd parameters are defaulted
.********************************************************************

The SATAN Versions

SATAN exists in three different versions ('old', 'normal' and 'new') in order to satisfy some controversial requirements of the user. On the one hand, permanently new functions or extensions of existing functions are required. On the other hand, many scientists are interested in a static system they can use for a certain period of time without the necessity to change existing analysis programs and to learn new commands.

The old and normal versions are static and remain unchanged, whereas the new version is developed further, extending continuously the function spectrum. However, once a year the old version is replaced by the normal version, the normal one by the new one and the previous old version is deleted. .********************************************************************

Calling SATAN

SATAN runs on the IBM host in the computing center with the operating system MVS/ESA. Sessions may be executed

  • in foreground under TSO/E enabling interactive data evaluation by command input via terminal, or
  • in a batch job, if a dataset containing a command list is specified.
Interactive SATAN sessions should be started outside of the ISPF environment. Then at any time a switch to the ISPF panels (and back to SATAN) is possible.

.tp &colmax right In principle, there are several possible ways to start a SATAN session. Typical sequences of TSO commands are: SATAN NEW ST º(1) The new version of SATAN ist started for an interactive session without any user's program ('ST' stands for 'standard'). Any system command may be specified, but no raw data can be processed. PLO MYANAL(GAMMA) NEW
SATAN NEW OBJ( MYANAL(GAMMA) ) º(2) At first a user's procedure available in the dataset .ce 'userid.MYANAL.PLI(GAMMA)' is compiled in foreground for the new version of SATAN. The program may contain SATAN macros and library calls and may be either an analysis procedure, an initialisation procedure, or a user exit (see :hdref refid=cosuser.). The object code is written to .ce 'userid.MYANAL.OBJ(GAMMA)' Then the new version of SATAN ist loaded together with this object module. Besides the standard functionality, also the corresponding user's functions are available. For background compilation, the TSO command PLOB (with an ISPF panel for parameter input) is available. To start the same SATAN session as a batch job, additionally a dataset must be specified containing the list of commands to be executed, such as: SATAN NEW OBJ( MYANAL(GAMMA) ) COM( SATAN.EXEC(GAMMA) ) º(3) In examples (2) and (3), SATAN was loaded with user modules. Because loading takes the order of one minute of elapsed time, this is only reasonable in the program development phase, when user modules are permanently changed. The exact load time, of course, depends on the program size and the current computer load. In the production phase with stable user modules, executable SATAN modules should be created only once by link-editing with the TSO command SATLINK: SATLINK NEW OBJ( MYANAL(GAMMA) ) LINK(SGAMMA)
SATAN NEW CALL(SGAMMA) º(4) SATLINK submits a batch job, and the time to built the executable SATAN module is spent here. This module is stored into the member 'SGAMMA' of the (default) load library 'userid.$SATAN.LOAD'. It can be called then as often as needed without a significant time delay. The standard SATAN invoked in example (1) is also such a 'ready' load module. The examples shown here are very simple. Many objects can be included for a session, of course, and external references can be resolved from user-created load libraries. Each of the mentioned TSO commands has much more options than presented here. For more details please refer to the SATAN manual. .*****************************************************************

The special SATANGD System

A special SATAN version to be invoked with the TSO-Command SATANGD was developed by a GSI user. :fn. K. H. Schmidt
SATANGD Graf Manual
GSI Nov. 89 :efn. A number of procedures is linked together with the SATAN system allowing the creation of high quality representation graphics for scientific publications using a powerful set of additional graphics commands. .******************************************************************** .se mem = 'Data Elements' :head. .pt

Data Elements

SATAN offers experimentalists a rich set of tools for data element handling, such as
  • storage in libraries,
  • manipulation and arithmetic,
  • display of spectra, optionally with error bars and calibrated axes,
  • plotting of such displays,
  • fitting of spectra,
  • unfolding of spectra, or
  • linearizing of spectra.
.********************************************************************

The Data Element: Analyzer

An analyzer may consists of
  • a spectrum of one to four dimensions,
  • the corresponding error spectra,
  • conditions for accumulation of data and
  • display windows and points.
All these components are optional.
The Spectrum

The analyzer spectrum contains the accumulated raw data. It consists of a one- to four-dimensional data space with up to 32k bins for each dimension. The spectrum contents may be long or short integers or (short) floating point numbers.

The Error Spectra

For each analyzer spectrum, up to four spectra of the same size containing error data may exist: the upper and lower vertical errors, and the left and right horizontal errors.

The Conditions

A condition defines a spectrum segment for usage in analysis programs. If existing and if not suppressed, it is checked automatically for each event and may be used to branch depending on the contents of incoming parameters.

The Display Windows and Points

They serve to store and display spectrum segments and channel numbers. They have no meaning for the raw data analysis, but for interactive evaluation based on graphical representation of spectra.

Most analyzer attributes including name, spectrum limits and bin sizes, and condition limits may be changed interactively. The display, fit, unfolding, and linearization utilities operate with analyzers. User interfaces are defined to add e.g. own fit routines to SATAN. .********************************************************************

The Data Element: Calibration

Calibrations are data structures providing one-dimensional arrays with x-coordinates ('calibrated coordinates') and an axis description. Calibrations may be used, for example, for the display of analyzer spectra, or for the usage of calibrated limits. To calibrate all coordinate axes of a n-dimensional spectrum, n_calibrations are needed.
The calibrated coordinate values may be defined by a polynomial ('polynom calibration'), or they can be explicitly specified by the user. .********************************************************************

The Data Element: Linearization

The data structure 'linearization' may be used for the evaluation of two-dimensional spectra, which are a function of two correlated parameters. The functional dependance of one of the two parameters will be removed. For example, assume the following functional dependance: .ce on charge = f(total energy, energy loss), .ce off as in the case of charge separation in ionization chambers. The functional dependance will be reduced with respect to a given linearization prescription, which will be stored in the corresponding linearization data structure. The result is the charge as a function of only one of the parameters, for instance .ce on charge = f(energy loss). .ce off

The data element linearisation consists of

  1. a gate (free form window) specifying the area to be linearized, and
  2. several polygon lines to remove the functional dependance of one parameter (the so called linearization description).
.********************************************************************

The Data Element Library

In many cases, the results of data analysis are spectra (analyzers) or other data elements. For referencing purposes and for complicated analysis procedures to be performed in several steps, it is desirable to be able to store data elements in some mass storage device and to retrieve them easily lateron.

This library resides on real disk data sets and can be accessed very quickly via VSAM ('Virtual Storage Access Method'). Each SATAN_user can define his or her own data element libraries with the ISPF panel 3.V. It is recommended to create at least one library per user and experiment. .******************************************************************** .se mem = 'Documentation of SATAN' :head. .pt

Documentation of SATAN

The SATAN documentation is available online from the computer, and on printed paper, enabling access also without computer support. It is created from one common text source. Informations about SATAN may be obtained by:

  • an interactive HELP facility in SATAN,
  • an interactive HELP facility in TSO,
  • printed manuals, and
  • interactive SATAN tutorials.

Independent of the physical medium, the SATAN documentation consists of five parts:

  1. Introduction and Concepts
  2. SATAN-Commands
  3. TSO-Commands
  4. Macros
  5. Procedures
.**********************************************************************

The Interactive HELP Facilities and Tutorials

.******************* :iref refid=edahelp. .******************* All parts of the documentation are supplied online when using the command HELP in the SATAN or TSO environment. However, for access in TSO, the SATAN documentation must be made available by invoking the TSO-Command .ce EDASHELP ON outside of the ISPF. This can be done by the system, if this command is written into a data set named LOGON.CLIST. Both, the SATAN and the TSO HELP commands, allow access to selected parts or to the complete description of a command, macro, or procedure. .im f1#4#1

The libraries accessed by the SATAN help facility are version dependent (see :hdref refid=cosver.) and can be accessed directly with the BROWSE option of ISPF. Their names are put together in :figref refid=docall.. Each library has the members $$TOC and $$NEWS providing a table of contents and the latest updates, repectively.

In the TSO and SATAN environment, the latest news and developments are available issuing the HELP commands with the option NEWS.

Within a SATAN session, several command lists are provided to demonstrate the usage and functionality of some important SATAN commands. They may be executed with the SATAN-Command TUTORIAL.

.******************* :iref refid=edasver. .******************* The SATAN-Commands HELP and TUTORIAL document the status of the SATAN version currently used, whereas the TSO-Command HELP always describes the new version of SATAN. .**********************************************************************

How to keep your SATAN Manual up-to-date

The printed SATAN manual is available in a folder. As the functionality of SATAN is continuously increased, the documentation must be updated correspondingly. Tools are available, which enable each user to keep his SATAN manual up-to-date:

  • The TSO-Command SATDOC provides an overview on all updates available for the SATAN manual, including the date and the subject of update.
  • Using the information obtained by SATDOC, the TSO-Command DOCUPD allows to print all updates for the SATAN manual on a laser printer.
To insert the new pages into the folder, a suitable paper punch is available in the printer room. With all existing updates included, the manual describes the 'new' version of SATAN. .**********************************************************************

The Documentation of User Commands

In SATAN a user may define own commands to invoke self written procedures interactively. All features of the SATAN documentation system are offered to the user for the documentation of his own commands, including the interactive HELP facility. A sceleton for the documentation of user commands with the TSO-Command DOC is available in the dataset .ce 'RZ66.$EDASC.TEXT(@MASK)' For more details see the description of the TSO-Command DOC.

COF4GOO

.ti 6d 6d .se mem='Processing GOOSY data with SATAN' :head

Processing GOOSY data with SATAN

Introduction

The GOOSY raw data format ist different compared to SATAN. The buffers can have any size and the data contained therein are structured. Buffers and events have standard headers describing the data by type and subtype numbers. SATAN recognizes these numbers, interprets them, and then passes the data to the user's analysis program via the $EVENT macro. To accomplish these tasks SATAN has to be switched to the GOOSY data mode with a new analysis program header named $GOOPROC. The data format provided in the analysis program can be controlled by the user with the macro $OPTION.

Data Analysis providing unpacked Event Parameters

The general structure of analysis programs evaluating GOOSY raw data is practically the same as for the analysis of data in EDAS format (see figure 1). Only the analysis program header must be changed. It must be $GOOPROC instead of $LISTPROC or $LISTVAR and switches SATAN to the GOOSY data input mode. .im fgoo#1 The data must be valid GOOSY data, i.e. every buffer must begin with a valid GOOSY buffer header. The type and subtype information contained therein is interpreted and an appropriate action routine is called performing the following functions:

  • If necessary, the data are converted from VAX to IBM format (ASCII to EBCDIC conversion and byte swap).
  • The events are extracted ('unpacked') from the data buffer, if not inhibited with the macro $OPTION.
  • The event parameters are passed to the analysis program via the macro $EVENT.

An example of a simple analysis program for GOOSY raw data with basic macros can be seen in figure 2. .im fgoo#2

The example shows an analysis program for buffers and events of type 4. Subtypes 1 and 2 can be mixed . The program starts with the macro $GOOPROC which switches SATAN to the GOOSY data input mode. By default, the comressed events of subtype 2 are unpacked into events of fixed length. The length is given by the number of parameters specified in the parameter list of macro $EVENT. The correct number of parameters is checked.

Data Analysis without unpacking of Event Parameters

If the user wants to unpack the events within his analysis program, he must specify the macro $OPTION with keyword NO_UNPACK immediately before the program header $GOOPROC. Then the complete event including the event header is passed to the analysis routine with $EVENT. Conversion from VAX to IBM format is also done by SATAN. The number of parameters requested by the parameter list in the macro $EVENT must be equal to or bigger than the number of parameters found in the data buffer including four parameters for the event header.

The option NO_UNPACK may be useful, for example, if in a first rough analysis only parts of an event are of interest. The user can overlay a suitable structure to the event parameters filtering out only the required parameters thus improving the performance of his analysis program. .im fgoo#3

The sample program in Fig. 3 shows an analysis program for buffers and events of type 4 the option NO_UNPACK specified in the option statement at the begining of the program prevents default unpacking. The packed events and the unpacked ones if there is a mixture in the input data are extended by the GOOSY buffer element header in which the data length, type and subtype is specified. The four header words can be found in the first 4 parameters given in the parameterlist of macro $EVENT.

The user is responsible for correct recognition of event types (time stamps!), unpacking, and processing. The number of parameters given in the macro $EVENT must be at least the maximum number of data words in the event plus 4 words for the header data. The conversions between VAX and IBM data format is done automatically. .pa

Data Analysis without unpacking of Buffers

.im fgoo#4

If the user specifies the macro $OPTION with keyword USER_MODE immediately before the program header $GOOPROC, the processing of event data by SATAN is supressed. Only the buffer header is checked for a correct GOOSY buffer type and, if necessary, converted to IBM format. The buffer format (IBM/VAX) is indicated by a switch in the buffer header.

Using this option, which supersedes the option NO_UNPACK, the complete buffer including the buffer header is passed to the analysis routine via the $EVENT interface. The number of parameters is not checked in this case. A PL/I structure can be overlayed to extract the data. This analysis must be handled completely by user written routines. The option USER_MODE was implemented to support buffer types for which there is no default processing routine available. Especially any unknown buffer type is handled in this mode by default.

Fig. 4 shows an analysis program for buffer and event types 4 with option USER_MODE selected. In this mode the complete buffer is passed to the analysis program. SATAN checks for a correct GOOSY buffer header and translates it to IBM format if necessary. The data contained in the buffer are not touched. The complete buffer manipulation including byte swaps for VAX /IBM format conversion and the event recognition and extraction has to be done by the user.

Standard MBD Data (Event Type 6)

Fig. 5 shows an example analysis program for type 6 events . The events are unpacked by default into a structure of 7 crates maximum and a maximum lenght of 1000 words per crate. The unpacking can be prevented by use of the option NO_UNPACK. With this option specified, the event data together with the event header is passed to the analysis program.

The user is responsible for correct recognition of event types, unpacking and processing. The conversions between VAX and IBM data format is done automaticaly. Depending on the individual event structure for type 6 buffers the modes NO_UNPACK or USER_MODE and a user written unpack procedure can result in a much faster program than using the defaults ! .im fgoo#5 .* .go rawend .pa .pt

Appendix

Supported GOOSY Buffer and Event Types

  • buffer type 1

    This is a nonstandard buffer type with a nonstandard buffer header. The complete data block is sent to the analysis program and the processing is completely up to the user.

  • buffer type 4

    These buffers contain events of subtype 1 and subtype 2. By default the comressed events are unpacked. The event length is taken from the length of the parameterlist specified in the macro $EVENT(....).

  • buffer type 6

    This buffer contains standard MBD events (subtype 1). By default these events are unpacked into a prdefined structure with 7 crates maximum and up to 1000 parameters per crate. Bigger events have to be unpacked by a user written routine.

  • buffer type 2000

    This buffer contains a GOOSY file header. The information contained therein is displayed at the terminal during the input of the data. The user is asked for acception or rejection of the data. The file header data is never passed to the analysis program.

  • buffer type any other

    For these buffer types there is no default processing routine implemented at the moment. Buffers are recognized as valid GOOSY buffers and the complete buffer, including the buffer header, is passed to the analysis program and must be handled by a user written routine.

  • event type 9000

    Time stamps are recognized by SATAN but not passed to the analysis program. .*----------- buffer header ----------------------------------------

GOOSY Buffer Structures

In the following a short overview of the structures of the supported GOOSY buffer and event types is given. A detailed description can be found in the manual 'GOOSY Buffer Structures' by H.G.Essel, H.Grein and M.Richter.

.*--------------------------------------------------------------------- .im @goobuf .*----- buffer header description ------------------------------------

  • data length

    Length of buffer without this buffer header in 16-bit words

  • Type

    A number specifying the buffer type

  • Subtype

    A number specifying the buffer subtype

  • Used length of data field

    The number of 16-bit words actualy used in this buffer

  • Fragment begin

    If this byte is 1 the buffer contains a fragment at the end of the buffer. The fragment is missing its trailing part which has to be found in the following buffer of the same type ans subtype.

  • Fragment end

    If this byte is 1 the buffer contains a fragment at the beginning of the buffer. The fragment is missing its first part which had to be found in the preceding buffer of the same type ans subtype.

  • Number of buffer elements

    Total number of fragments and data elements in this buffer.

  • Buffer number

    A current number of buffers of the same kind

  • Current index

    A longword to store the index of the last processed event. This field can be used by routines processing the buffer to store the index of the last processed buffer element. If the buffer is stored to disk or tape this field must be 0 or 1 if the data are in VAX format and -1 if the format is IBM. This word is used by SATAN to control the byte swapping of the data. If it is corrupted a default processing by SATAN is impossible.

  • Time stamp

    VAX binary time stamps (64 bit)

  • 4 reserved longwords

  • Data words

    The data field of the buffer. The structure of data is specified by the buffer type and subtype.

Structure declaration

                                                                 
1                                                                            
 /*----- $MACRO(SA$BUFHE)    ------------------------*/                         
 /*----- GOOSY BUFFER HEADER ------------------------*/                         
 ;                                                                              
 DCL  P_SA$BUFHE   POINTER INIT(NULL);                                          
 ;                                                                              
 DCL 1 S_SA$BUFHE  BASED(P_SA$BUFHE),                                           
       2 I_DLEN      BIN FIXED(15),    /* DATA LENGTH                 */        
       2 I_TLEN      BIN FIXED(15),    /* TOTAL LENGTH                */        
       2 I_TYPE      BIN FIXED(15),    /* TYPE                        */        
       2 I_SUBTYPE   BIN FIXED(15),    /* SUBTYPE                     */        
       2 I_USED      BIN FIXED(15),    /* USED LENGTH                 */        
       2 C_END       CHAR(1),          /* FRAGMENT END (AT BUF. BEGIN)*/        
       2 C_BEGIN     CHAR(1),          /* FRAGMENT BEGIN (AT BUF. END)*/        
       2 L_BUF       BIN FIXED(31),    /* CURRENT BUFFER NUMBER       */        
       2 L_EVT       BIN FIXED(31),    /* NUMBER OF FRAGMENTS         */        
       2 L_CURRENT   BIN FIXED(31),    /* VAX/IBM FORMAT              */        
       2 L_TIME(2)   BIN FIXED(31),    /* TIME STAMP                  */        
       2 L_FREE(4)   BIN FIXED(31),    /* RESERVED                    */        
       2 I_DATA(1)   BIN FIXED(15);    /* DATA                        */        
1                                                                            
.*------------- buffer element header -------------------------------

.im @gooele

  • data length

    Length of buffer element without this header in 16-bit words.

  • Type

    A number specifying the element type

  • Subtype

    A number specifying the element subtype

  • Data

    Any structure of data depending on type and subtype.

Structure declaration

                                                                 
1                                                                            
 /*----- $MACRO(SA$EVHE)           ------------------*/                         
 /*----- GOOSY DATA ELEMENT HEADER ------------------*/                         
 ;                                                                              
 DCL  P_SA$EVENT   POINTER INIT(NULL);                                          
 ;                                                                              
 DCL 1 S_SA$EVENT  BASED(P_SA$EVENT),                                           
       2 I_DLEN      BIN FIXED(15),    /* DATA LENGTH                 */        
       2 I_TLEN      BIN FIXED(15),    /* NOT USED                    */        
       2 I_TYPE      BIN FIXED(15),    /* TYPE                        */        
       2 I_SUBTYPE   BIN FIXED(15),    /* SUBTYPE                     */        
       2 I_DATA(1)   BIN FIXED(15);    /* EVENT DATA                  */        
1                                                                            
2 .*----- file header buffer ------------------------------------------- .im @goo2000
  • Data length

    Length of buffer in 16-bit words excluding this header.

  • Type

    For file header buffer always = 2000.

  • subtype

    For file header buffer always = 1.

  • Used length of data field

    Depends on length of comment.

  • Fragment begin

    This field is always = 0.

  • Fragment end

    This field is always = 0.

  • Number of buffer elements

    for this file header always = 1.

  • Buffer number

    A current number of buffers of the same type.

  • Current index

    Indicates VAX /IBM format of this buffer header and data. A value of -1 indicates IBM data any other >= 0 indicates VAX data format.

  • Time stamp

    A quadword for the system time in VAX/VMS binary format.

  • 4 reserved longwords

  • File header specific information

  • Used length of tape label

    Number of characters used in the next field

  • Tape label

    Contains the tape label of the ANSI tape if the file was created on a tape.

  • Used length of file name

    Number of characters used in the next field

  • File name

    Name of file at the time of creation.

  • Used length of user name

    Number of characters used in the next field

  • User name

    User name of the creating VAX/VMS process.

  • Date

    Character string of the file creation date in the format "dd-mmm-yyyy hh:mm:ss.mm " where dd is the day of the month mmm is the 3 character abbreviation of the english spelled month and yyyy is the year, hh are hours, mm minutes, ss.mm are seconds. this date string is always padded by a space character.

  • Used length of run identification

    Number of characters used in the next field

  • Run identification

    Character string to identify the experiment run corresponding to this file.The contents is user defined. The string can have a maximum of 66 characters.

  • Used length of experiment name

    Number of characters used in the next field

  • Experiment name

    Character string to identify the experiment run corresponding to this file.The contents is user defined. The string can have a maximum of 66 characters.

  • Number of lines

    Number of 78 character comment lines following

  • Used length of line

    Number of characters used in the next field

  • Comment lines

    Character string array to characterize the contents of this file. The lines are user defined. The header can have a maximum of 46 lines.

.kp on Structure declaration

                                                                 
1                                                                            
 /*----- $MACRO(SA$FILHE)          ------------------*/                         
 /*----- GOOSY FILE HEADER   ------------------------*/                         
 /*      BUFFER TYPE 2000,1                          */                         
 /*--------------------------------------------------*/                         
 ;                                                                              
 DCL  P_SA$FILHE   POINTER INIT(NULL);                                          
 ;                                                                              
 DCL 1 S_SA$FILHE  BASED(P_SA$FILHE),                                           
       2 I_DLEN      BIN FIXED(15),    /* DATA LENGTH                 */        
       2 I_TLEN      BIN FIXED(15),    /* TOTAL LENGTH                */        
       2 I_TYPE      BIN FIXED(15),    /* TYPE                        */        
       2 I_SUBTYPE   BIN FIXED(15),    /* SUBTYPE                     */        
       2 I_USED      BIN FIXED(15),    /* USED LENGTH                 */        
       2 C_END       CHAR(1),          /* FRAGMENT END (AT BUF. BEGIN)*/        
       2 C_BEGIN     CHAR(1),          /* FRAGMENT BEGIN (AT BUF. END)*/        
       2 L_BUF       BIN FIXED(31),    /* CURRENT BUFFER NUMBER       */        
       2 L_EVT       BIN FIXED(31),    /* NUMBER OF FRAGMENTS         */        
       2 L_CURRENT   BIN FIXED(31),    /* FOR UNPACK                  */        
       2 L_TIME(2)   BIN FIXED(31),    /* TIME STAMP                  */        
       2 L_FREE(4)   BIN FIXED(31),    /* RESERVED                    */        
                                       /*-----------------------------*/        
       2 C_LABEL     CHAR(30) VAR,     /* TAPE LABEL                  */        
       2 C_FILE      CHAR(86) VAR,     /* FILE NAME                   */        
       2 C_USER      CHAR(30) VAR,     /* USER NAME                   */        
       2 C_TIME      CHAR(24),         /* TIME AND DATE               */        
       2 C_RUN       CHAR(66) VAR,     /* RUN IDENTIFICATION          */        
       2 C_EXP       CHAR(66) VAR,     /* EXPERIMENT                  */        
       2 L_LINES     BIN FIXED(31),    /* NUMBER OF LINES             */        
       2 C_LINE(L_LINES REFER(L_LINES))                                         
                     CHAR(78) VAR;     /* COMMENT LINES               */        
.kp off                                                                         
1                                                                            
2 .*----- buffer type 1 ------------------------------------------------

Buffer Type 1, Subtype 1

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .if &$PDEV = 3820 .th .se col0 = 1.2cm .el .se col0 = 7 Buffer Type 1, Subtype 1 .* .if &$PDEV = 3820 .th .tp 1.1cm right 1.2cm 2.95cm 4.7cm 6.45cm 8.2cm 9.95cm 11.7cm 13.45c right .el .tp 7 right 10 right 14 22 30 38 46 54 62 69 right ºOffset º31 º28 º24 º20 º16 º12 º8 º4 º0 .* .if &$PDEV = 3820 .th .tp 1.1cm right 4.7cm center 8.2cm center 11.7cm center .el .tp 6 right 22 center 38 center 54 center .* .bx &col0 &colmax º0 ººheader length º .hr &col0 to &colmax .if &$PDEV = 3820 .th .bx set &col0 8.2cm &colmax .el .bx set &col0 38 &colmax º4 ºType = 1 ººSubtype = 1 .hr &col0 to &colmax º8 ºfirst data word ººsecond data word .bx off ººº. . . .bx off

2 MBD buffer. This buffer has a non standard GOOSY buffer header and must be processed by user written routines. The buffer is recognized by SATAN and sent to the analysis routine without any processing . The buffer is assumed to be in VAX format and the first 4 words are swaped. 2 .*-------- buffer type 4 ----------------------------------------------

Buffer Type 4, Subtype 1

Buffer type 4 , subtype 1 can contain events of type 4, subtype 1 or subtype 2 and time stamps (events of type 9000, subtype 1). .im @gooev41 .*-------------------------------------------------------------------- 1 .im @gooev42

Structure declaration

                                                                 
1                                                                            
 /*----- $MACRO(SA$EVHE)     ----------------------------------------*/         
 ;                                                                              
 DCL  P_SA$EVENT   POINTER INIT(NULL);                                          
 ;                                                                              
 DCL 1 S_SA$EVENT  BASED(P_SA$EVENT),                                           
       2 I_DLEN      BIN FIXED(15),    /* DATA LENGTH IN WORDS        */        
       2 I_TLEN      BIN FIXED(15),    /* NOT USED    = 0             */        
       2 I_TYPE      BIN FIXED(15),    /* TYPE        = 4             */        
       2 I_SUBTYPE   BIN FIXED(15),    /* SUBTYPE     = 1/2           */        
       2 I_DATA(1)   BIN FIXED(15);    /* EVENT DATA                  */        
1 .*-------- buffer type 6 ----------------------------------------------

Buffer Type 6, Subtype 1

Buffer type 6 contains standard MBD events of type 6 subtype 1 with structure defined by J11 programs. .*---------------------------------------------------------------------

.im @gooev61 1

  • data length

    Length of buffer element without this header in 16-bit words.

  • Type

    A number specifying the element type = 6

  • Subtype

    A number specifying the element subtype

  • Data length subevent

    Length of subevent in words excluding header longword .

  • Event count

    A counter to check the correct order of events and subevents. In IBM format the counter and CRATE bytes are swaped !

  • CAMAC crate

    The number of the CAMAC crate where the subsequent subevent data come from. In IBM format the counter and CRATE bytes are swaped !

  • Data words

    Data

.kp on Structure declaration

                                                                 
 /*---- $MACRO(SA$ME61)     -------------------------------------*/             
 /*--------------------------------------------------------------*/             
 /* Declaration of MBD event structure 6,1                       */             
 /* gooinc(sa$me6_1) copied at 26.2.88                           */             
 /*--------------------------------------------------------------*/             
   DCL P_SA$ME6_1    POINTER INIT(NULL);                                        
   DCL IP_SA$ME6_1   BIN FIXED(31) BASED(ADDR(P_SA$ME6_1));                     
   DCL 1 SA$ME6_1    BASED(P_SA$ME6_1),                                         
      2 IA$ME6_1_slen     BIN FIXED(15),   /* subevent length    */             
      2 HA$ME6_1_event    CHAR(1),         /* event count        */             
      2 HA$ME6_1_crate    CHAR(1),         /* crate              */             
      2 IA$ME6_1_data(1)  BIN FIXED(15);   /* data words         */             
                 ...                                                            
      2 SA$ME6_1_next,                                                          
        3 IA$ME6_1_nslen     BIN FIXED(15), /* subevent length   */             
        3 HA$ME6_1_nevent    CHAR(1),       /* event count       */             
        3 HA$ME6_1_ncrate    CHAR(1),       /* crate             */             
        3 IA$ME6_1_ndata(1)  BIN FIXED(15); /* data words        */             
                                                                                
.kp off 1 By default events of type 6 are unpacked into the following structure. The maximum number of crates is 7 and the maximum number of data words per crate is 1000.

.kp on

                                                                 
 /*---- $MACRO(SA$MBD)       --------------------------------*/                 
 /*----------------------------------------------------------*/                 
 /* Declaration of MBD event structure 6,1                   */                 
 /*  unpacked Version                                        */                 
 /* gootyp(sa$mbd) copied at 26.2.88                         */                 
 /*----------------------------------------------------------*/                 
   DCL P_SA$MBD     POINTER;                                                    
   DCL 1 SA$MBD     BASED(P_SA$MBD),                                            
      2 IA$MBD_dlen      BIN FIXED(15),                                         
      2 IA$MBD_tlen      BIN FIXED(15),                                         
      2 IA$MBD_type      BIN FIXED(15),                                         
      2 IA$MBD_subtype   BIN FIXED(15),                                         
                                                                                
         2 SA$MBD_C1,                                                           
      3 IA$MBD_C1_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C1(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C2,                                                           
      3 IA$MBD_C2_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C2(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C3,                                                           
      3 IA$MBD_C3_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C3(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C4,                                                           
      3 IA$MBD_C4_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C4(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C5,                                                           
      3 IA$MBD_C5_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C5(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C6,                                                           
      3 IA$MBD_C6_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C6(1000)    BIN FIXED(15), /* data words */                      
         2 SA$MBD_C7,                                                           
      3 IA$MBD_C7_slen     BIN FIXED(15), /* subevent length  */                
      3 IA$MBD_C7(1000)    BIN FIXED(15); /* data words */                      
 ;                                                                              
.kp off ...rawend

CT

.********************************************************************

The Data Element: Calibration

Calibrations are data structures providing one-dimensional arrays with real numbers which may be used as 'calibrated coordinates'. By command references can be created between analyzer spectra and calibrations. This enables, for example, the display of analyzer spectra with calibrated axes, or the usage of calibrated limits. To calibrate all coordinate axes of a n-dimensional spectrum, a reference to a calibrations is needed for each dimension of the spectrum. For the same calibration, references may exist to several different (one-dimensional) analyzer spectra, or even to different dimensions of the same (multi-dimensional) analyzer spectrum. References between analyzers and calibrations can be created and deleted dynamically by SATAN commands. However, they are not stored in the data element libraries. Ending a SATAN session, all references are lost and must be recreated when starting a new SATAN session. The calibration values may be defined by a polynomial ('polynom calibration'), or they can be specified explicitly by the user. The calibration data element consists of:
  • a one-dimensional array containing the calibrated coordinates or -_in case of a polynom calibration_- the polynom parameters,
  • limits, expressed in terms of (fictive) analyzer channel numbers, which specify the validity range, and
  • an axis description for display.
.********************************************************************

The Data Element: Linearization

The data structure 'linearization' may be used for the evaluation of two-dimensional spectra, which are a function of two correlated parameters. The functional dependance of one of the two parameters will be removed. For example, assume the following functional dependance: .ce on charge = f(total energy, energy loss), .ce off as in the case of charge separation in ionization chambers. The functional dependance will be reduced with respect to a given linearization prescription, which will be stored in the corresponding linearization data structure. The result is the charge as a function of only one of the parameters, for instance .ce on charge = f(energy loss). .ce off

The data element linearisation consists of

  • a gate (free form window) specifying the area to be linearized, and
  • several polygon lines containing the information for the removal of the functional dependance of one parameter ('linearization prescription').
Gate and linearization prescription can be created, modified, or deleted interactively with SATAN commands specifying graphics or alphanumeric input. The linearization prescription may be executed by command or in analysis programs. A description of the linearization in more detail will be found in :hdref refid=utline..

C0

.im @rfsup :medium.

Introduction

.se mem = 'Introduction' :head.

Experiments performed with the GSI facilities UNILAC and SIS/ESR cover the fields of Nuclear and Atomic Physics, Nuclear Chemistry and Biology. The types of data measurement range from the simple accumulation of spectra up to the acquisition of events with thousands of parameters obtained from multiple coincidences between multi-parameter detectors.

SATAN, the System to Analyse Tremendous Amounts of Nuclear data, is designed to analyze the data arising from such experiments. The objectives of SATAN are the support of all functions needed for the evaluation of experiments, from the raw data input up to the final publication. This includes

  • easy access to large volumes of experiment data during data analysis,
  • the availability of all tools required for the analysis of experiment data,
  • the evaluation of spectra, and
  • graphical representation of results on terminals and plotters.

SATAN runs on the central mainframe in the GSI computer center, and was historically developed as part of EDAS, the Experiment Data Acquisition and Analysis System of GSI. EDAS consisted of two parts, SATAN, and GOLDA, the data acquisition part, which ran on PDP-11 computers. For more complex experiments, the capacity of the GOLDA system was not sufficient to allow 'online' analysis for technical and physical control of the experiment parameters. In this case, the experiment computer was linked to SATAN, offering its powerful services also in 'online' mode.

However, the requirements of newer experiments, especially at SIS/ESR, could not be satisfied with GOLDA, and a new data acquisition system named GOOSY (GSI Online Offline SYstem) was developed. GOOSY runs on the VAX computers of GSI and offers also powerful online analysis capabilities eliminating the need of a SATAN online mode.

The rich set of standard tools, available in SATAN for input and analysis of raw data in EDAS format, is also available for raw data in GOOSY formats. The strongly experiment dependent analysis programs can be constructed easily from standardized program elements such as macros and subroutines.

The IBM mainframe in the GSI computer center and the VAX experiment computers are connected via HYPERchannel, a high speed connection allowing fast transfer of raw data and spectra. .tp 15mm

The complete SATAN documentation consists of five parts:

  • I ºIntroduction and Concepts
  • II ºSATAN-Commands
  • III ºTSO-Commands
  • IV ºMacros
  • V ºProcedures

This first volume is intended to be an introduction into SATAN, as well as a reference handbook. All stages of an experiment analysis are outlined. The contents is organized in four chapters, which are kept independent of each other as far as possible:

  1. General Concepts,
  2. Data Analysis with SATAN,
  3. The Usage of SATAN-Commands, and
  4. The TSO-Environment of SATAN.
.**************** :iref refid=guide .**************** .**********************************************************************

How to Use this Documentation

In principle, information is available at three levels, differing from each other by the depth of information and the number of details.

  1. The highest level can be found in the first chapter of this volume. In an overview the general concepts and the principles underlying the design of SATAN are explained, and the functionality of SATAN is described in a general way.
  2. The chapters 2 to 4 describe in more detail how to write analysis programs, how to use the commands, and which functions are available. This part is illustrated with many examples demonstrating both, simple principles, and advanced applications.
  3. The lowest level containing any available information is supplied by the appendix of this volume and by the volumes II to V, containing some program structure informations and the complete descriptions of all commands, macros, and library procedures.
Beginners should start reading the highest level to get first insights into SATAN. However, SATAN is designed in a way that each user only has to learn what he really needs. It is absolutely not necessary to have a knowledge of all parts of SATAN, when beginning to write first, simple analysis programs, or when creating the first analyzer and try to display it on a graphic screen. So, in parallel to reading the concepts, a newcomer should try to solve simple problems from the beginning, referencing also the specific parts of levels two and three of the SATAN documentation.

The lowest level is not suitable to get an overview. It is intended for usage as technical handbook, to be referenced when looking for certain functions, or when having a specific problem. :emedium.

C1

.im @@hd .dh 2 npa .im c1#1 .dh 2 pa .im c1#2 .im c1#3 .im c1#4

C1.1

.se pre = 'General Concepts' :prefix. :medium. .se title = 'General Concepts'

General Concepts

.se mem = 'SATAN Summary' :head. .* running heading erst auf der naechsten Seite :iref refid=concept.

SATAN is a system of programs and tools designed to analyze experiment data from experiments performed at the UNILAC or SIS/ESR at GSI. SATAN accepts input of data gathered with the GSI experiment data acquisition system GOOSY, and, of course, also input of data in EDAS format, collected with the older data acquisition system GOLDA. In addition, data written by user programs may be entered, and suitable interfaces are defined to perform the conversion of external data formats into GSI formats.

The functionality of SATAN extends from raw data processing, spectrum accumulation, and spectrum evaluation up to the preparation of graphics output for scientific publications. Along this way, in many cases huge amounts of raw data in the order of Gigabytes have to be reduced to a few numbers (for example cross sections, distribution functions) representing the physical results of experiments.

SATAN offers experimentalists a rich set of tools to solve standard problems, such as display, plotting, fitting, unfolding, or linearizing of spectra. Most tools are available in form of a high level command language, which enables easy manipulation of complex data structures. SATAN is an open system, and so each user may define his own, non standard data processing functions in a high level language. .******************************************************************

SATAN Summary

SATAN, the System to Analyse Tremendous Amounts of Nuclear data, runs on a central computer &ibmcomp. and can perform complex data analysis using all resources of a big installation shared among many users. The SATAN system is started with the TSO-Command SATAN, and may be used in the interactive mode as well as in the batch mode. The SATAN environment consists of the following:

  • a comfortable system for the handling of large volumes of raw data,
  • a high level, experiment oriented programming language to write complex raw data analysis and reduction programs,
  • a set of support libraries with macros and procedures,
  • a command language,
  • libraries for data elements (e.g. spectra or calibrations), global parameters and pictures,
  • program development support including compilers and a powerful debugging environment,
  • extended TSO support via specific TSO commands,
  • interactive help and tutorial facilities, and
  • documentation support.
.*********************************************************************

The Raw Data

In the raw data input stream, SATAN recognizes two distinct data types:

    .kp on
  • list mode data (event by event), and
  • spectra (accumulated events) .kp off
.***************** :iref refid=listmo .*****************

The list mode data consist of sequences of events. An event represents the set of numerical values associated with a 'physical event'. It is a collection of all parameters measured in connection with the physical event. An event consists of several parameters correlated in time. Each parameter is a numerical value resulting after conversion of the analog signal captured by a detector. The parameters may represent physical coincidences (e.g. several detectors at different locations looking at coincident particles) or just different attributes of a single physical event (energy loss and residual energy of particles in a telescope experiment, for example). To keep track of the correlations between the different parameters for later analysis, they are normally written event-by-event onto a storage device by a data acquisistion system such as GOOSY. .****************** :iref refid= cogrou .****************** The size of events is very different depending on the experiment. The number of event parameters may vary between a few and several thousands for high energy physics experiments with SIS/ESR. GOOSY events are structured consisting of event header and event data, and they may be divided into subevents corresponding to different CAMAC crates, for example. Supported by standard tools in SATAN are the EDAS and GOOSY list mode formats.

Spectra may be accumulated in the hardware of the experiment computer as DMI (Direct Memory Increment) or CMI (CAMAC Memory Increment) spectra. :iref refid=symode seeid=datype :iref refid=alomo

A detailed description of EDAS and GOOSY raw data formats can be found in :hdref refid=strumag.. .*********************************************************************

Data Flow and Analysis in SATAN

I/O and data analysis are decoupled from each other. The I/O section is standardized and provided by the 'system', whereas the analysis section, which is strongly dependent on the particular experiment and the physical aspects of an individual evaluation, must be provided by the user. The principal structure of data flow and analysis in SATAN is as follows:

  • Dispatching (sorting) of the input raw data and forwarding them to the corresponding user-supplied analysis subroutine(s),
  • Output of modified raw data, for example after calibration or reduction,
  • Processing of raw data resulting in the accumulation of spectra with up to four dimensions, which are stored into data element libraries,
  • User interaction with the system to control the analysis by means of commands for global parameter modifications and display of the results.
The principal structure of data flow is shown in :figref refid=datflw.. .im f1#1#1 The analysis program contains the experiment dependent logic of event processing. The results of accumulation, the spectra, are stored in data structures called 'analyzers'. Analyzers and the other SATAN data elements (calibrations, linearizations) can be stored into and retrieved from data element libraries by means of commands.

The graphic representation of analyzer spectra, optionally with calibrated axes and error bars, plays a key role in SATAN. By means of a graphic display one- and two-dimensional spectra can be viewed either statically or 'live'. The 'live display' provides a way of following data accumulation event by event. In static displays, several different representation modes are available, and any projections or cuts of analyzer spectra with more than two dimensions can be displayed. .*********************************************************************

Analysis Procedures

Due to the variety of GSI experiments, SATAN is not a closed system containing every conceivable analysis logic as a subset. Instead, the system calls analysis subroutines written by the user in a high-level language, following well-defined rules. In these subroutines the user specifies the configuration and analysis logic of the experiment. In a modular way, an extensive and rich set of standard functions is available in analysis programs. They are supplied by the system as

  1. macros (see :hdref refid=progdev),
  2. library routines (see :hdref refid=libfunc), or
  3. commands (see :hdref refid=ecomlan).
Any SATAN-Command can be invoked in analysis procedures using the SATAN-Macro @EXCMD. Examples of standard functions offered are:
  • input and output of raw data,
  • condition checking and access to condition counters,
  • spectrum accumulation, and
  • access to and handling of the contents of data elements (spectra, error and calibration data, ...).
This modular construction makes the system very flexible, allowing the user to integrate new routines easily. .*********************************************************************

Program Development

Development of SATAN analysis programs is done in PL/I on the central computing facilities (&ibmcomp.). PL/I was selected as programming language of SATAN for both, the system part and the user's part, because PL/I offers a rich functionality not available with other programming languages. However, there was no language available providing specific and powerful software tools for experiment data analysis. .****************** :iref refid=simple. .****************** So a problem-oriented macro language was developed for this purpose called SIMPLE (System Independent Macro Programming LanguagE). In this language, the user writes his programs using a powerful set of macros, which will be expanded by a preprocessor to PL/I. Together with the macros, all PL/I constructs are allowed in analysis programs, and FORTRAN or C subroutines may be invoked (see :hdref refid=satlan).

For more details see :hdref refid=maclan.. An extensive introduction on how to write SATAN analysis programs, illustrated with many examples, is provided in :hdref refid=datanal.. A detailed description of each SATAN-Macro is available in Volume_IV of this manual. .*********************************************************************

The Library Functions

A set of PL/I subroutines is supplied offering

  • access and handling of the contents of analyzers,
  • drawing of graphic primitives and definition of their attributes,
  • writing of text to terminal and protocol files and getting input from terminal, and
  • utility functions, such as
                                                                             
    -  handling of random number distributions,                                     
    -  peak search algorithms,                                                      
    -  smooth and spline algorithms, and                                            
    -  linearizing of spectra.                                                      
    
Additionally interfaces are available, which allow access to the data element libraries from FORTRAN main programs running independent of the SATAN environment.

The names of all SATAN library procedures start with a '$'_sign to mark them as 'system' procedures. The '$'_sign should not be used for user subroutines to avoid naming conflicts. The SATAN library procedures are described in detail in Volume_V of this manual. .*********************************************************************

The Command Language

The interactive SATAN command language allows the execution of standard functions. Commands enable

  • to control the flow of data by defining input and output data streams,
  • to change the flow of control in analysis procedures,
  • to manipulate data,
  • to display data,
  • to fit model functions,
  • to deconvolute (unfold) distributions,
  • to linearize distributions,
  • to access external data,
  • to get help information,
  • to execute lists of commands.
.******************* :iref refid=commcon. .******************* Generally the name of a command is chosen such that its purpose is more or less obvious. With some exceptions, the first letter of a command name denotes the functional class the command is belonging to:
compact tsize=8 termhi=0.
___A
Analyzer commands
___D
Display commands
___F
Fit commands
___I
Input/Output commands
___L
Linearization commands
___M
Magnetic tape commands
___$
System control commands
Additionally the user may define own commands invoking self written routines interactively.

In (interactive) foreground sessions, the user may communicate with the system via graphic and alphanumeric screens, entering commands and graphics cursor input, and receiving the results of the processing, mainly in a graphical form.
In background sessions, files containing command lists can be executed. Graphic output can be created on metafiles (e.g. GDF vector file) or plotter devices.

The principal structure of SATAN commands and their usage, illustrated with many examples, is described in :hdref refid=command.. A detailed description of each SATAN command is available in Volume_II of this manual. .********************************************************************

SATAN Versions

.****************** :iref refid=satansm :iref refid=satancm :iref refid=satanrm :iref refid=versat .****************** SATAN exists in three different versions called 'old', 'normal', and 'new' in order to satisfy some controversial requirements of the user. On the one hand, permanent new functions or extensions of existing functions are required. On the other hand, the scientists are interested in a static system they can use for a certain period of time without the necessity to change existing analysis programs and to learn new commands. The old and normal versions are static and remain unchanged for a longer period of time, whereas the new version is developed further continuously to fulfil the steadily increasing requirements of the users. However, once a year the old version is replaced by the normal version, and the normal version is replaced by the current new version, thus making new developments also available to the static versions. .********************************************************************

Interfaces to GOOSY

.***************** :iref refid=gooint .***************** GOOSY raw data and spectra can be transferred to the central processor of the computer center in several ways:

  1. Magnetic tapes or cartridges containing raw data can be copied to disks in the computer center via TSO-Command (see :hdref refid=rawcon).
  2. Raw data files can be transferred between VAX and IBM disks via HYPERchannel, a high speed connection between the central processor in the computer center and the VAX computers at GSI. This can be done interactively or via batch job, invoking suitable DCL- or TSO-Commands on VAX or IBM, respectively.
  3. GOOSY spectra can also be transferred via HYPERchannel to the SATAN data element libraries (see :hdref refid=sanalib). Suitable analyzers containing these spectra are automatically created.
:emedium.

C1.2

.pa :medium. .se mem = 'Basic Concepts' :head.

Basic Concepts

The Raw Data Concept

Currently raw data from experiments at GSI or elsewhere are expected to be stored on magnetic tapes or 3480 cartridges. With a TSO-Command (ONLTADI) they are copied once to temporary disk units of the central processor in the computer center and put under control of the HSM, the Hierarchical Storage Manager. The files on the original tape or cartridge are backup files normally no longer needed. In spite of that, these volumes should also be kept in the computer center, where suitable conditions (climate, hanging) are provided.

Files not used for a certain time are 'migrated' automatically by the HSM to 3480 cartridges, and the original copy on disk is deleted. If migrated files are needed again, the HSM copies them automatically back to disk ('recall'). During the process of migration, the data are compressed by the HSM, reducing the size of migrated files for up to a factor of two.

Using the ISPF panel 3.4, each user may access online the list of all of his raw data files, including some information, such as the migration status, for example. In the command column of this list, many useful commands to handle data sets may be issued, especially the migration status can be changed here.

Currently there is a limitation concerning the availability of migrated raw data files. The HSM can perform a recall only if an operator in the computer center is available to put the required cartridge on a cartridge drive. However, operators are not available in the night (11.00pm to 6.00am), at weekends, and at holidays. So currently the user himself must take care, that all raw data files needed in a SATAN batch job are available at run time. In the near future, an automatic library system ('cartridge roboter') will overcome this problem providing complete independency of time when running SATAN batch jobs for data evaluation.

Raw data acquired with GOOSY on VAX computers must be transformed to IBM format when analyzed in SATAN. For integer event data, byte swaps must be performed, and text must be converted from ASCII to EBCDIC format. This can be done

  1. when copying from tape or cartridge to disk (ONLTADI),
  2. when reading into SATAN for analysis, or
  3. with the SATAN-Command IFORMAT.
Due to the GSI naming conventions, the names of raw data files on disks of the computer center begin with 'uid.LMDI', if they are available in IBM format. Here 'uid' means the user identification, and 'LMDI' is a fixed part of the data set name, qualifying the data as List Mode Data in IBM format.

Correspondingly, the names of raw data files in VAX format begin with 'uid.LMDV'. So both types of files can be distinguished by name and handled separately by ISPF panel 3.4. For more details on the raw data naming conventions, see .x.x.x.

To minimize the consumption of CPU time, raw data mainly to be analyzed with SATAN should be kept in IBM format. Raw data, which should also be analyzed with GOOSY, for example with the online analysis program from data acqusistion, may be kept in VAX format. For analysis with GOOSY, these files may be transferred to VAX disk via HYPERchannel, a high speed connection between the central processor in the computer center and the VAX computers at GSI (see .x.x.x.).

Raw data are read into SATAN by the command INPUT. Of course, input of raw data is not only accepted from IBM disk file, but also from no label (NL) magnetic tape (EDAS data) or ANSI label (AL) magnetic tape or cartridge (GOOSY data). However, direct input from tape or cartridge in time consuming SATAN analysis jobs should be an exception, because the number of tape and cartridge drives is limited. .********************************************************************

Data Elements in SATAN

The data elements are complex data structures. They can be created interactively with commands, or in analysis programs using macros or commands. Currently the space occupied by the sum of all data elements in a SATAN session may amount up to nearly 70_Mbytes. Three types of data elements are available:

  • analyzers,
  • calibrations, and
  • linearizations.
All data element attributes including names and definition ranges may be changed interactively. Most commands operate with data elements. A set of macros and procedures is provided to access or modify data elements within analysis procedures.

For storage and retrieval of data elements, a data element library is available (see :hdref refid=sanalib.). .********************************************************************

Analyzers

:iref refid=anconc An analyzer consists of
  • a spectrum of one to four dimensions,
  • the corresponding error spectra,
  • conditions for accumulation of data, and
  • display windows and points. .*
  • general information and comments.
.*
The Spectrum
consists of a one- to four-dimensional data space with up to 32k bins for each dimension. However, the overall space of an analyzer must not exceed 1_Mbyte currently. The spectrum contents may be two- or four-byte integers, or floating point numbers. .*
The Error Spectra:
For each analyzer spectrum, up to four spectra of the same size and dimensionality containing error data may exist: the upper and lower vertical and the left and right horizontal errors.
If only upper vertical (lower vertical) error data are stored, the lower vertical (upper vertical) error data are assumed to be identical. The same holds correspondingly for left and right horizontal error data. .*
The Conditions
define a spectrum segment for usage in analysis programs and with SATAN commands. They can be associated with an interval for each dimension, or, in the two-dimensional case, with a closed polygon of any shape (free form condition).
If not inhibited by the user, each event parameter to be accumulated is checked if lying within the condition limits of the analyzer, and the corresponding flags are set. The results may be used to change the data flow in the analysis program. .*
The Display Windows and Points
serve to store and display spectrum segments and channel numbers for (interactive) usage with commands, but they are not accessed in analysis programs. .********************************************************************

Calibrations

The calibration data structures provide one-dimensional arrays of real numbers, which may be used as 'calibrated coordinates'. By command references can be created between analyzer spectra and calibrations. This enables, for example, the display of analyzer spectra with calibrated axes, or the usage of calibrated limits. To calibrate all coordinate axes of a n-dimensional spectrum, a reference to a calibrations is needed for each dimension of the spectrum. For the same calibration, references may exist to several different analyzer spectra, or even to different dimensions of the same (multi-dimensional) analyzer spectrum. References between analyzers and calibrations can be created and deleted dynamically by SATAN commands. However, they are not stored in the data element libraries. Ending a SATAN session, all references are lost and must be recreated when starting a new SATAN session. The calibration values may be defined by a polynomial ('polynom calibration'), or they can be specified explicitly by the user. The calibration data element consists of:
  • a one-dimensional array containing the calibrated coordinates or -_in case of a polynom calibration_- the polynom parameters,
  • limits, expressed in terms of (fictive) analyzer channel numbers, which specify the validity range, and
  • an axis description for display.
.********************************************************************

Linearizations

The linearization data element may be used for the evaluation of two-dimensional spectra, which are a function of two correlated parameters. Performing the linearization process, the functional dependance of one of the two parameters will be removed by processing a given linearization prescription, which is stored in the corresponding linearization data structure. For example, assume the following functional dependance: .ce on charge = f(total energy, energy loss), .ce off as in the case of charge separation in ionization chambers. The result of a linearization process is the charge as a function of only one of the parameters, for instance .ce on charge = f(energy loss). .ce off

The data element linearisation consists of

  • a gate (free form window) specifying the working area, and
  • several polygon lines containing the information for the removal of the functional dependance of one parameter ('linearization prescription').
Gate and linearization prescription can be created, modified, or deleted interactively with SATAN commands specifying graphics or alphanumeric input. The linearization prescription may be applied to an analyzer spectrum by command or in analysis programs. A more detailed description of the linearization process will be found in :hdref refid=utline.. .********************************************************************

Data Element Libraries

Besides reduced or modified list mode data, in most cases the results of data analysis are spectra. For referencing purposes and for complicated analysis procedures to be performed in several steps, it is necessary to be able to store data elements in some mass storage device and to retrieve them easily and quickly later. This holds also for the other data elements, the calibrations and linearizations.

Therefore, the concept of an data element library was developed in SATAN. .****************** :iref refid=analib. .****************** This library resides on real disk data sets and is accessed via VSAM ('Virtual Storage Access Method'). Each SATAN user can define own data element libraries with a capacity of up to 1000 different dumps per library. The number of data elements per dump command (ADUMP) is unlimited. Once a data element is stored onto the library, it can be retrieved at any time during a SATAN session (command AFETCH).

However, we recommend to create several small libraries not exceeding a size of the order of 100_Mbytes instead of a single but large one. Also the VSAM data sets are under control of the HSM (Hierarchical Storage Manager) and will be migrated to 'secondary' mass storage devices, if they are not accessed for a certain time. If needed, a migrated data set is automatically 'recalled' by the HSM back to 'primary' storage. For very large data set of several 100_Mbytes, for however, there is a chance that not enough storage at a single volume is available, and the recall will fail. A data element on a library is identified by .****************** :iref refid=anlistr. .******************

  • the user identifier (uid) of the library-owner,
  • the library name (lib)
  • the run identification
  • the dump command number for a specific run identification
  • two names: the data element identifier, and the data element qualifier,
  • the data element type (analyzer, calibration, or linearization).
All VSAM data sets in the computer center have a common user identification 'RS0V', and so the data set name assigned to a data element library is .ce &vsamlib.. The run identification can be used to classify data elements within a library according to certain evaluation aspects. Library name (lib) and run identification must be specified when data elements are dumped by the command 'ADUMP'. If several dump commands are issued for the same run identifier, the dump number is automatically incremented by the system. For analyzers, from historical reasons the qualifier name often is also called 'event type' identifier.

Data elements from a library may be accessed not only by SATAN-Commands (AFETCH) or within analysis procedures invoking the macro '@EXCMD(AFETCH ... );'. Additionally interfaces are available, allowing access from FORTRAN main programs running outside of the SATAN environment.

GOOSY spectra may be copied for further evaluation from VAX computers directly into a SATAN data element library, residing on a disk in the computer center:

  1. The GOOSY spectrum must be dumped on the VAX by the MDBM command 'DUMP SPECTRUM'.
  2. Using the DCL-Command 'SIBMSPEC', the dump can be transferred via HYPERchannel to the specified SATAN analyzer library, where a suitable analyzer is created automatically.
Data element libraries as whole can be handled with the ISPF 3.V panel. They can be created, deleted, copied, or renamed, and some HSM functions such as migrate, recall, compress, or create backup, may be issued. .********************************************************************

The Global Parameter Concept

In most analysis programs calibrations or other numerical calculations are to be performed with the raw data. This implies the use of numerical constants, the exact values of which are mostly unknown when the program is written. Tools are desirable to modify their values dynamically during the analysis process by entering an appropriate command. Such parameters are called 'global parameters'. They may be simple variables or arrays of up to 15_dimensions, implemented as external structures. The global parameters may be used to control data flow and execution logic in analysis programs.

A specific global parameter is unique in a SATAN session and known in all user programs (analysis (sub)routines, user command procedures), in which he is declared with the macro @PARDCL. On command level a global parameter may be declared with the command IPARDCL.

With the command IPAR, global parameters can be accessed, modified and listed. Most contents of all data elements can be stored into global parameters using the command ASTORE, and several other commands provide output into global parameter arrays. As they can be read from and stored into members of a partitioned data set (PDS), they are an important interface between SATAN and other programs running independent of the SATAN environment.

For more details refer to the description of the SATAN-Command IPAR in Volume II. .********************************************************************

The User Section of SATAN

SATAN consists of the 'system code', which performs standard functions, and an optional 'user section'. When only standard functions are necessary, a standard subsystem of SATAN should be invoked using the option 'STANDARD' (abbreviated ST) of the SATAN command. To provide more flexibility, SATAN was designed as an open ended system. This means that several interfaces are available for the user to add own program code in order to perform nonstandard functions specific to his own data processing. Since the user section and the system section are linked together into an executable module, the user section must be written carefully. An error in it might lead to overwriting the system code, resulting in unpredictable results.

There are a number of ways to add user written code to SATAN:

  1. Analysis procedures: basically have the aim to convert raw data input into modified raw data or into data elements. They have a defined structure, especially a standard program header. The rules are explained in detail in :hdref refid=anproco..
  2. User commands: . The specification of a single keyword, the command name, may trigger the execution of a complex program. Like 'system' commands, also user commands optionally may have parameters.
    The user commands may be defined in the initialization part of an analysis procedure, or in special initialization procedures. Detailed explanations about writing user commands can be found in :hdref refid=usercom.
  3. User exits in SATAN commands: User exits are subroutines with a defined argument list. They are invoked, when the corresponding command is called, and executed before the system part of the specified command. The existing user exits and the commands invoking them are summarized in :figref refid=uexits..
.im f1#2#1 In any type of user code, 'normal' subroutines written in PL/I, FORTRAN, or C, may be invoked via the PL/I CALL statement. The system functions may be requested via
  1. SATAN-Procedures,
  2. SATAN-Commands (issued with the macro @EXCMD), or
  3. SATAN-Macros (having names starting with an '@'-sign).
Other SATAN-Macros have names starting with an '$'-sign. They can be used only in analysis 'main' programs with a standard program header (see :hdref refid=datanal).

There are two possibilities to run SATAN sessions with user sections included.

  1. An executable, temporary SATAN load module can be created with the loader. It will be executed immediately. The startup time requires a few CPU seconds, and the load module is no longer available, when the execution is finished. This mode of running SATAN is reasonable in the development and test phase, when the user programs will be changed permanently.
  2. An executable, permanent SATAN load module can be created with the linkage editor in a batch job (TSO-Command SATLINK). It can be invoked afterwards repeatedly using the CALL option of the SATAN command. In this case the invocation of SATAN is very fast. This mode of running SATAN is recommended in the production phase, when the analysis is stable and requires normally no more changes.
To add user sections to SATAN, the TSO-Commands SATAN and SATLINK have two key words 'OBJ' and 'LIB'. With the option OBJ, any user object modules can be added, especially analysis programs or initialization routines containing user's command definitions. The key word LIB enables the specification of user's load libraries. Resolving external (program) references, they are searched by the loader or linkage editor before the system load libraries. .**********************************************************

The principal Procedure of Experiment Data Processing

.***************** :iref refid=repmod .***************** Generally, data analysis is done in a number of successive steps. Thus, it is important to be able to preserve intermediate results from one step to the next. In general it is not possible to give a step by step recommendation of how to proceed with the data analysis. However, the principal procedure may look as follows:

  1. Normally the experiment data are stored on magnetic tapes or cartridges and should be copied once to an IBM disk with the TSO-Command ONLTADI (see :hdref refid=rawcon.).
    • Data in GOOSY format, available on magnetic tapes or cartridges with ANSI label (AL), can be copied directly to disk.
    • Magnetic no-label (NL) tapes with older EDAS data may be available in SATAN or GOLDA format. If measured with the GOLDA system on PDP-11 computers in stand-alone mode, they must be converted at first into SATAN format performing byte swaps and conversion from ASCII to EBCDIC. This can be done with the SATAN-Command MFO28 (see :hdref refid=exampt2.). The output is written to another NL tape and has the same format as data measured with GOLDA and SATAN in coupled mode. Also these data can be copied to disk with the TSO-Command ONLTADI.
  2. The next step is to pass the raw data through analysis procedures. There are different aspects possible.
    • In an iteration process, the same data may have to be processed repeatedly until the most suitable conditions and calibration parameters are found.
    • Often it is useful to calculate some physically relevant parameters from the measured quantities and to create modified or reduced list mode data, which can be analyzed much faster than the original raw data.
    • In most cases data analysis results in the accumulation of analyzer spectra. Together with the spectrum, some other relevant information is preserved in analyzers, e.g. the conditions and error spectra associated. All relevant data elements, including calibrations and linearizations, created interactively or in analysis procedures, can be stored in data element libraries for further evaluation.
    Raw data are read into SATAN by the command 'INPUT'. Reduced or modified list mode data can be saved on magnetic tape or cartridge files or on disk data sets, using the command 'IOUTPUT'. In a following analysis step, they can be read again by the command 'INPUT'. The chapters :hdref refid=datanal., and :hdref refid=gooanal., provide detailed information concerning the analysis of data in GOOSY and EDAS format, respectively.
  3. In following, mostly interactive SATAN sessions, the data elements created in 'production' batch sessions are checked and further evaluated using the powerful functionality of SATAN commands and interactive graphics. Retrieving data elements from libraries is performed by the SATAN-Command AFETCH. Then the analyzer spectra can be displayed in various graphics representations, optionally with calibrated axes and error bars. They can be modified, and arithmetic operations can be performed, for example to sum up the contents of several equivalent spectra into a sum spectrum, or to subtract background counts. Standard and user specific functions can be adapted to the measured spectra using the SATAN fit package. Spectra can be deconvoluted or linearized. In this evaluation step, also the final graphics output for scientific publication may be created. The results of such session(s), new or modified data elements, can also be stored into the data element libraries using the command ADUMP.
Obviously data analysis is an iterative process. Each of these steps may be executed several times under different aspects, until the final results of an experiment, mainly cross sections and distribution functions, are available with the required accuracy. .**********************************************************

Interactive and Batch Processing

.***************** :iref refid=intbat .***************** Since the same functions are available interactively and in batch, the user may separate the work into two parts:

  1. An interactive part with dynamic control upon the flow of analysis, with interactive graphics, and with checks for correctness, and
  2. a batch part with execution of a fixed command list.

Batch sessions are recommended for production runs processing large amounts of data and consuming large portions of CPU time. This may be true for the evaluation step 2. (running analysis programs) and for step 3. (running SATAN command lists), both described in section :hdref refid=intemod..

Interactive sessions seem to be useful

  • in the test and development phase of analysis programs, when only small portions of data are processed,
  • for checks of the results of production batch sessions,
  • for the development of schemes and procedures to evaluate data elements,
  • for the development of command lists ('EXEC' lists) and user commands,
  • for the creation of final graphics plots.
.**********************************************************

Data Transfer with External Installations

Both, raw data and the contents of data elements (spectra, error and calibration data, free form conditions, linearization prescriptions, ...) can be transfered between GSI and external installations.

The GSI raw data formats are described in detail in :hdref refid=strumag. and :hdref refid=strugoo..
For the conversion of external raw data formats into EDAS data format, a suitable interface (procedure $MYFORM, see :hdref refid=exdafo.) is offered. Such a conversion procedure is already available for the HOOPSY data format of HMI in Berlin (see option HOOPSY of SATAN-Command MFO28).

The contents of SATAN data elements can be stored into global parameters using the SATAN-Command ASTORE, and the global parameters can be stored into members of partitioned data sets ('PDS') with the SATAN-Command IPAR. External data corresponding to the contents of SATAN data elements can be read from PDS members

  • directly into the SATAN data element structures in the case of analyzer spectra (SATAN-Command AREAD), or
  • into global SATAN parameters with the command IPAR. Then the global parameter contents can be copied into the corresponding data element structures in the case of
    • error data (command AERROR),
    • calibration data (command ACALIB),
    • free form conditions (command ACDEF), or
    • linearization prescriptions (command ACDEF).
Smaller data volumes, for example members of partitioned data sets, may be exchanged with external installations online, using the connections of EARN and other networks via the ISPF panel C.E. Especially when communicating with installations running operating systems other than MVS, a standard record format, namely fixed blocked (FB_80), should be used.

To transfer large data volumes between installations, magnetic tapes or cartridges are possibly still the most suitable transport medium. The following informations are important:

  • The physical characteristics of the medium (density, type of label, number of files, record format, and block size), and
  • the data format. A binary dump and the data interpretation of this dump are useful in the case that problems should subsequently occur.
Data can be dumped from IBM disk to a magnetic tape or cartridge with the TSO-Command ONLDITA (list mode data) or with the ISPF panel G.T (any data format). .**********************************************************

Graphics Concepts

The SATAN graphic software is integrated in the general graphic concept of the GSI computer center, which is based on

  • the plotfile, a structured standard file format containing all the graphical information about the picture in a device independent format,
  • the plotfile interpreter, a program to interprete the plotfile and to reproduce the picture contained in it on every available graphic device,
  • interface programs for line and text drawing, enabling user supplied interactive graphics in SATAN, and
  • the standard graphics data file GDF (Graphics Data Format) of IBM.
The essential advantage of using the plotfile or the GDF file is the easy transfer of pictures between graphics devices and systems.

Pictures (including live displays) can be stored in plotfile format, either

  • temporarily for the current SATAN session (DCOPY ON), or
  • permanently on disk (DCOPY AGFP), thus available also for future SATAN sessions.
If retrieved again, the pictures can be redrawn on any device in SATAN (command DCOPY) and in any other graphics system based on the same plotfile format (GNOM, CALCOMP).

Pictures stored in the GDF vector file format may be further processed in two ways.

  1. The GDF file interpreter (TSO-Command GDFIP) allows slight manipulations of the picture and sends them to other graphics output devices.
  2. The TSO-Command LASPRAS enables interactive modifications such as rotate or zoom and rasterization of the picture in any size. The raster output can be included as 'page segment' into text files processed by the text processing systems DCF and TEX, and printed on a laser printer. In this way text and graphics can be integrated without usage of scissors and glue.

Some more details can be found in section :hdref refid=gradev.. .*****************************************************************

The special SATANGD System

A special SATAN version to be invoked with the TSO-Command SATANGD was developed by a GSI user /SGD88/. A number of procedures is linked together with the SATAN system allowing the creation of high quality representation graphics for scientific publications using a powerful set of additional graphics commands. :emedium.

C1.3

.pa :medium .se mem = 'SATAN Implementation' :head. .*********************************************************************

SATAN Implementation

:iref refid=satimp

SATAN runs on a central processor &ibmcomp. in the computer center as a user job under &ibmts., the Time Sharing Option of the Operating System &ibmos..

SATAN can be executed within ISPF, started from panel 6, or outside of ISPF. Switching between SATAN and ISPF is possible, if SATAN was started outside of ISPF. With a suitable interface (SATAN-Command EXTSO), TSO-Commands may be executed in SATAN also when started inside ISPF.

The system part of SATAN is implemented in PL/I. Additionally some assembler modules are included performing functions not available in PL/I.

Satan fully utilizes the XA feature of the operating system (see :hdref refid=osxa.) and the multitasking facility of PL/I (see :hdref refid=satask.). SATAN sessions may execute interactively in foreground, or in background as a batch job. .*********************************************************************

Some Aspects of the Operating System

The Extended Architecture (XA) Feature

The extended architecture (XA) feature of the operating system allows to address .ce on 2&s3.&s1.-1 bytes = 2 Gbytes .ce off of virtual storage (31_bit address mode), compared with 2&s2.&s4.-1_bytes = 16_Mbytes previously available without XA feature (24_bit address mode). The operating system allows programs to execute in any of both address modes. The address mode may even be switched within a program. Tools are available to a programmer to specify the address mode and to control the residence of program code and program data, either above or below the 16_Mbyte line.

For the control of load modules at run time, the Linkage Editor and the Loader have two options:

  • The AMODE option specifies the address mode of an entry point in a load module, when invoked at run time.
    Possible values are: 24, 31, or ANY. If ANY is selected, the operating system decides on the address mode at run time, depending on the actual environment.
  • The RMODE option specifies, where a module will be loaded for execution, above or below the 16_Mbyte line in virtual storage ('residence mode').
    Possible values are 24, or ANY. If the residence mode 24 is specified, the module will be loaded below the 16_Mbyte line for execution, independent of the current address mode. With RMODE ANY, the operating system will load the module above the 16_Mbyte line, if possible. Then, for example, the address mode 31 is necessary.
In principle, program data can be positioned in virtual storage independent of the program code. The tools available depend on the programming language used. In FORTRAN, for example, all data reside below the 16_Mbyte line, execept those contained in a dynamic common area. PL/I, the implementation language of SATAN (see :hdref refid=satlan), offers much more flexibility:
  • All variables declared with the AUTOMATIC option (default) are allocated by the system in the Initial Storage Area (ISA), which resides below the 16_Mbyte line.
  • Variables declared with the options BASED or CONTROLLED must be allocated explicitly using the ALLOCATE statement. They are put in another storage area called HEAP. This storage area may reside above or below the 16_Mbyte line, controlled by the PL/I run time options HEAP and TASKHEAP.
.*********************************************************************

The Adress Space of a SATAN User

SATAN fully utilizes the XA features of the operating system and the corresponding tools of PL/I. The address mode of the complete SATAN system is 31. The load modules of SATAN can be divided into two classes:

  1. a resident nucleus, and
  2. dynamically loadable ('fetchable') modules (see :hdref refid=dynloa.).
The resident nucleus of SATAN has a size of about 1_Mbyte and must reside below the 16_Mbyte line, mainly due to I/O services of the operating system running only with RMODE_24. The resident user program code (analysis and command procedures) is loaded together with the SATAN nucleus resulting in an executable load module below the 16_Mbyte line.

The dynamically loadable part of SATAN consists of about 100 load modules with an overall size of about 4.5_Mbyte. These fetchable modules are only loaded when needed, and nearly all of them reside above the 16_Mbyte line. Also user defined commands may be fetchable. The corresponding rules are presented in :hdref refid=fetchmo.

Only a small portion of the program data of SATAN resides below the 16_Mbyte line. All data structures of the SATAN data elements are declared with the option BASED and allocated above the 16_Mbyte line.

Below the 16_Mbyte line, about 8_Mbyte of address space is available for each user. Above the 16_Mbyte line, currently up to &addrspa can be allocated for program code and data. Whereas the first number is practically fixed, the second number is an installation parameter and must match with the current system configuration. So the current (virtual) address space of a user may have a size of up to &addrspt. in total. Its structure for a SATAN user is summarized in :figref refid=addrspu.. .im f1#3#1 .*********************************************************************

The Programming Language

.****************** :iref refid=complp1 .****************** The system components are all written in PL/I, with only a few exceptions, written in assembler. FORTRAN is certainly more familiar to scientists, but the following considerations led to the choice of PL/I:

  • Asynchronous, priority-controlled separation of different tasks (multitasking) is not possible in FORTRAN. .****************** :iref refid=multisa .******************
  • PL/I contains most FORTRAN elements as a subset with a similar syntax. SATAN is structured so that the experimenter need become familiar only with this subset. All complicated functions which require higher-level PL/I have been absorbed into the system.
  • PL/I supports dynamic storage management.
  • PL/I allows access to addresses of variables or arrays.
In any part of the user section, subroutines written in FORTRAN or C may be invoked. However, some modules should be written in PL/I:
  1. the analysis programs with standard header (see :hdref refid=datanal),
  2. the initialisation programs (also with standard header), and
  3. the command procedures, triggered by user programs.
.****************** :iref refid=compibm :iref refid=comlp1 :iref refid=comlfo .****************** Concerning the invocation of FORTRAN subroutines, there is a limitation resulting from the fact that the FORTRAN environment is not reentrant. At one time, the FORTRAN environment may be active only within one (PL/I) task, and it may be opened only once during the life time of a task. Therefore the SATAN user must decide before loading SATAN (calling SATAN with option OBJ(obj)) or linking SATAN (with SATLINK), in which task the FORTRAN environment shall be available. By default the FORTRAN environment is opened in the main task for system and user commands, but not in the analysis task. If FORTRAN subroutines are required in analysis programs, the option 'FORTANAL' must be specified in the SATAN or SATLINK command when creating an executable SATAN load module. Then the FORTRAN environment will be opened in the analysis task.
Caution: Commands are always executed in the main task, even if invoked in the analysis task via the macro @EXCMD! FORTRAN subroutine calls also in such commands are only possible in SATAN sessions created without the option 'FORTANAL'. .*********************************************************************

The Macro Language

.****************** :iref refid=simple PG=MAJOR .****************** The implementation of user written programs within the experiment data analysis system SATAN demands the use of a high-level, problem oriented programming language. Such a language was not available, and so SIMPLE, the System Independent Macro Programming LanguagE) was developed offering special language elements for experiment data processing purposes.

New language elements for special functions are most easily implemented by means of macros, identified by keywords, and possibly accompanied by an argument list. Since macro names are no legal program statements, they must be expanded by a macro preprocessor into legal code (PL/I), which then can be fed into the respective compiler.

Macros automatically make the generation of extensive blocks of code possible via simple statements and form the basis of SIMPLE. To expand the macros into PL/I code, a SPITBOL program /DEW71/ is used as preprocessor. .****************** :iref refid=comlsp. .******************

The advantages are:

  • Complicated functions which require higher level PL/I are hidden from the user, who only needs to use basic PL/I statements and the macros.
  • Standard functions needed for many evaluations, such as accumulation or condition checking, are coded only one time by a professional programmer.
  • The execution speed for analysis programs can be optimized without program modification by generating better code with the preprocessor.

As PL/I statements, macro lines should be delimited by a semicolon. The preprocessor for the expansion into executable PL/I code is invoked by the TSO-Commands PLO or PLOB, executing in foreground or in background, respectively.

Macros were developed for many standard analysis functions, using the analyzer concept as the basis. An extensive introduction into writing SATAN analysis programs for GOOSY and EDAS raw data, enriched with many examples, is provided in :hdref refid=datanal.. A detailed description of each SATAN macro may be referenced in Volume IV of this manual. .*********************************************************************

The Debugging Environment

.*********************************************************************

SATAN Internals

Entering the TSO command 'SATAN', the following functions are performed initially:

    .
  • The user address space receives better performance conditions within the system, valid for the duration of the SATAN session.
  • The allocation of all SATAN related data sets and files is done.
  • Entries in a log data set are created allowing statistical evaluation of SATAN usage afterwards.
  • General information and news concerning the SATAN system are written.
  • The SATAN system is loaded and started, or submitted as a batch job.
.*********************************************************************

The SATAN Multitasking

Utilizing the PL/I multitasking facility, the task structure of SATAN allows for asynchronous execution of different functions:

    .
  1. The 'command task' controls input and execution of commands.
  2. The 'Input/Output task' controls the data flow from and to external media.
  3. The 'dispatcher task' dispatches the input data to the data type dependent processor. The user analysis program runs as part of this dispatcher task.
  4. The 'live task' controls the live display.
  5. The 'timer task' generates specific interrupts with a timer.
.**********************************************************

Dynamical Loading of Modules

SATAN consists of a resident part (SATAN 'nucleus') and many transient ('fetchable') modules. Due to the large functionality of SATAN, many load modules are not needed at start time, and some modules are not needed at all in a specific data analysis. Magnetic tape handling, for example, is normally not needed, if interactive graphics commands are applied to data elements from the data element library.

However, these modules must be made available when needed. This concept of a 'fetchable module' is implemented for most command procedures using the 'dynamic load' mechanism of the Operating System. The advantages of using fetchable modules are obvious:

  • reduction of initial starting time,
  • reduction of overall storage usage (only functions needed are in storage),
  • simplification when creating special SATAN versions, and
  • facilitation of system maintenance allowing the development and testing of fetchable procedures without leaving the SATAN session.
The execution time increases only slightly due to some housekeeping functions of the operating system.

The native PL/I FETCH statement cannot fulfill the following important requirements:

  • access and change of resident information,
  • call of resident procedures within a fetchable module, and
  • load and call of other fetchable modules within a fetchable module.
To perform these functions, interface programs have been developed. They have been designed as PL/I Preprocessor macros to enable easy invocation.

This extended fetch mechanism is used by most SATAN commands and may be used also for user commands. The rules and interfaces necessary to write fetchable user commands are described in the chapter :hdref refid=fetchmo.. :emedium

C1.4

.pa :medium .se mem = 'Documentation of SATAN' :head.

Documentation of SATAN

:iref refid=edasman.

The SATAN documentation is available online from the computer, and on printed paper, enabling access also without computer support. It is created from one common text source. Informations about SATAN may be obtained by:

  • an interactive HELP facility in SATAN,
  • an interactive HELP facility in TSO,
  • printed manuals, and
  • interactive SATAN tutorials.

Independent of the physical medium, the SATAN documentation consists of five parts:

  1. Introduction and Concepts
  2. SATAN-Commands
  3. TSO-Commands
  4. Macros
  5. Procedures
.**********************************************************************

The Interactive HELP Facilities and Tutorials

.******************* :iref refid=edahelp. .******************* All parts of the documentation are supplied online when using the command HELP in the SATAN or TSO environment. However, for access in TSO, the SATAN documentation must be made available by invoking the TSO-Command .ce EDASHELP ON outside of the ISPF. This can be done by the system, if this command is written into a data set named LOGON.CLIST. Both, the SATAN and the TSO HELP commands, allow access to selected parts or to the complete description of a command, macro, or procedure. .im f1#4#1

The libraries accessed by the SATAN help facility are version dependent (see :hdref refid=edasver.) and can be accessed directly with the BROWSE option of ISPF. Their names are put together in :figref refid=docall.. Each library has the members $$TOC and $$NEWS providing a table of contents and the latest updates, repectively.

The latest news and developments of SATAN are available issuing the HELP commands with the option NEW.

Several command lists are provided to demonstrate the usage and functionality of some important SATAN commands. They may be executed with the SATAN-Command TUTORIAL.

.******************* :iref refid=edasver. .******************* The SATAN-Commands HELP and TUTORIAL document the status of the SATAN version currently used (see :hdref refid=edasver.), whereas the TSO-Command HELP describes the new version of SATAN. For more details on the interactive help and tutorial features of SATAN see the section :hdref refid=helpcom.. .**********************************************************************

The SATAN Manual

The printed SATAN manual is available in a folder. As the functionality of SATAN is continuously increased, the documentation must be updated correspondingly. Tools are available, which enable each user to keep his SATAN manual up-to-date:

  • The TSO-Command SATDOC provides an overview on all updates available for the SATAN manual, including the date and the subject of update.
  • Using the information obtained by SATDOC, the TSO-Command DOCUPD allows to print all updates for the SATAN manual on a laser printer.
To insert the new pages into the folder, a suitable paper punch is available in the printer room. With all existing updates included, the manual describes the 'new' version of SATAN. .**********************************************************************

The Documentation of User Commands

.******************* :iref refid=userdoc. .******************* In SATAN a user may define own commands to invoke self written procedures interactively (see :hdref refid=usercom.). All features of the SATAN documentation system are offered to the user for the documentation of his own commands, including the interactive HELP facility (see the TSO-Command DOC). For more details refer to :hdref refid=userdoc.. :emedium

C2

.im @@hd .dh 2 npa .im c2#1 .dh 2 pa .im c2#2 .* .im c2#3 .* .im c2#4 .* .im @rhsup .*

C2.1

:medium.

Data Analysis with SATAN

.se mem = 'Introduction' :head. .se pre = 'Data Analysis with SATAN' :prefix.

The specific features of an experiment (like data types, logical relations, spectra, derived quantities) are defined within analysis programs, which are linked to the SATAN system. The data structures initialized and filled this way are parts of SATAN data elements and may be accessed during a SATAN session interactively via system and user commands.

Usage and structure of SATAN commands will be described in detail in :hdref refid=command.. This chapter will introduce mainly into the usage of initialization and analysis procedures. Towards the end of this chapter a bunch of examples will be given. They describe a lot of available tools and utilities, and deal with questions often occurring when writing an analysis program. .*********************************************************************

Introduction

Initialization and Analysis Procedures

Both, initialization and analysis procedures, must not have a PL/I 'PROCEDURE' statement as the first executable program statement, but a SIMPLE macro instead (see :hdref refid=maclan) defining a SATAN standard program header. Several standard program headers are available in SATAN for different tasks and raw data formats:

  • $GOOPROC for the analysis of any standard GOOSY events,
  • $LISTPROC for the analysis of fixed length events in EDAS format,
  • $LISTVAR for the analysis of variable length events in EDAS format,
  • $ANLPROC for analysis subroutines evaluating events of fixed length in EDAS or GOOSY format, and
  • $INITPROC for the definition of user commands.
Initialization procedures should have the program header '$INITPROC'. They may be used in SATAN sessions without raw data analysis for the evaluation of data elements by (interactive) user commands. User commands may be defined also in the definition part of 'normal' analysis procedures, but analysis and initialization procedures must not be used together for one SATAN session.

In the raw data input stream for analysis procedures, there may be two distinct data types (see also :hdref refid=datform.):

  • singles data (EDAS format only), and
  • list mode data.
.****************** :iref refid=datype. :iref refid=listmo. .****************** Singles data are uncorrelated data. They are incremented in the hardware without storing the data flow, thus forgetting the history of the events while saving computer effort.

List mode data consist of sets of several correlated parameters. These might be for instance measured quantities of a single particle. To keep track of the correlations between the different parameters for later analysis, list mode data are normally written event-by-event onto some mass storage device, usually magnetic tapes or cartridges. There are several hardware methods to get list mode data, discussed in detail in the corresponding GOOSY manuals. The corresponding formats are also described in this manual in section :hdref refid=goodata.. .*********************************************************************

Analysis Programs and the Analyzer Concept

:figref refid=telesc. shows the basic parts of a simple telescope experiment. .****************** :iref refid=telesc. :iref refid=exsite. .****************** It serves to illustrate the creation and analysis of list mode data. .im f3#1#1

A beam of particles hits a target. The reaction products create signals at the detectors, which are related to energy and energy loss. The time of flight between the two detectors is measured, too. These three signals are led to digital converters to create binary 16_bit numbers at the output. A trigger pulse (either external or from one of the detectors) initiates the computer to read this set of three correlated parameters (this event) into the memory. From there they are copied onto an external medium (tape, cartridge, or disk).

To get numbers of physical relevance, it is desirable for the experimentalist to calculate derived quantities from the event parameters. In this case energy, mass, and atomic number of the scattered particle are derived from the directly measured quantities energy loss, time of flight, and energy. Windows are defined and depending on whether a parameter hits the indicated interval or not (conditions), spectra are accumulated. In this case: if the energy is in a certain range, a spectrum of mass and atomic number (nuclear charge) is accumulated. Event after event is analyzed in the way described.

Data structures are needed, which contain the accumulated spectra and information about windows and conditions. For this purpose, SATAN provides the 'analyzer' data element, whose properties (called 'attributes') are described in more detail in the following sections. .*********************************************************************

Analyzer Identifiers

.**************** :iref refid=anconc. :iref refid=aid. .**************** Analyzers are identified by two names, the 'analyzer name' and the 'qualifier name'. A valid name consists of a sequence of one to 18 alphanumeric characters, which may be .ti 6d 6d .ce letters, digits, or the special characters '$', '@', '_', and '#'. .ti _ 41 The first character of a name must be a letter, '$' or '@'. The character '#' acts as a dimension separator used in display headings of multidimensional analyzers, for example.

The qualifier name of analyzers created in analysis programs (macro $AGEN) is 'LIST'. In contrast the qualifier name of dynamically created analyzers (command AGEN) may be defined arbitrarily by the user. For example, it is possible to have two analyzers with the name ENERGY, but one with the qualifier LIST, and the other with DMI.

Internally SATAN assigns in order of creation a unique integer to each analyzer and qualifier name. These numbers are used by most 'system' programs and also available for the users. From the names, the numbers may be obtained with the procedure $ATRACE, or, at command level, with the commands AATT and ALIST. .*********************************************************************

Analyzer Creation

Analyzers may be created with the macro $AGEN or the command AGEN. :iref refid=$agen. .ti 6D 6D For example the macro .ce $AGEN(REL_ENERGY) creates an analyzer with the name REL_ENERGY and the qualifier LIST. The equivalent command statement is .ce AGEN REL_ENERGY LIST .ti _ 41 Analyzers created 'dynamical' with the command AGEN may be deleted (command ADES), and all attributes can be modified (command AMOD). However, analyzers created with the macro $AGEN ('static') cannot be deleted, and some attributes (type, dimension, and qualifier name) cannot be changed in a session.

In analysis programs, but not at command level, several analyzers can be created with one statement. For example, the macro .ce $AGEN (MASS(3)); creates three analyzers. However, analyzers in SATAN are not really treated as arrays. Except in $AGEN, the brackets are part of the analyzer name and just facilitate the creation of many analyzers.

The analyzers created above have default attributes, that means

  • spectrum type 4 (4_byte integers)
  • one dimension,
  • limits 0 to 1023,
  • bin size 1,
  • no conditions,
  • no display windows, and
  • no error data.
.*********************************************************************

Dimensionality and Limits

.**************** :iref refid=adim. .**************** Analyzers may have up to four dimensions. A multidimensional analyzer can handle several input values simultaneously: 1 .ce $AGEN (DE#E) LIMITS(0,10,1,191); 1 creates a two-dimensional analyzer DE#E. The first dimension has 11 channels varying between 0 and 10, the second dimension has 191 channels varying between 1 and 191 (see :hdref refid=analchn). .*********************************************************************

Bin Size

.**************** :iref refid=alim. .**************** To reduce spectrum extents, more than one channel number in any dimension may be defined to belong to one spectrum element ("bin"). The number of adjacent channels of one dimension contributing to a spectrum element is called "bin size". 1 .ce $AGEN (CHR) BINS(16) LIMITS(0,511); 1 In this example, each 16 channels of analyzer CHR will be summed up to form one bin. The spectrum shrinks from 512 (for bin size 1) to 32 numbers. This may be useful to let bad statistics look better, and it will save storage.

Note:
All macros, commands, and displays use the original channel numbers of the incoming data, regardless of the analyzer bin size. .*********************************************************************

Conditions

.**************** :iref refid=acon. :iref refid=$acdef. :iref refid=acdef. .**************** A condition in the simplest case is a set of channel number limits with one pair -_the lower and upper limit_- for each dimension. Conditions may be set by the the commands ACDEF and DSWI, or by the macro $ACDEF in an analysis program:
                                                                         
.ti 6d 6d                                                                       
                                                                             
.ce $AGEN (REL_ENERGY) LIM(0,4095) NCND(2);                                     
.ce $ACDEF (REL_ENERGY,1,15,360);                                               
.ce $ACDEF (REL_ENERGY,2,315,512);                                              
The analyzer REL_ENERGY is created with two conditions. .ti _ 41 The subsequent invocations of $ACDEF set the condition limits to the values 15 and 360 for condition number_1, and to 315 and 512 for condition number_2.

When accumulating with the macro $ANAL, an associated flag is set by the system, if the analyzer input values for an event lie inside the condition limits. This flag can be checked in subsequent program sections using the macro $AC.

Conditions are numbered sequentially starting from 1. All conditions must lie within the analyzer limits. .*********************************************************************

Free Form Conditions

.***************** :iref refid=banana .***************** The concept of the simple rectangular condition has been extended to a more general one allowing any shape of the condition in the case of a two-dimensional analyzer. The free form condition limits are defined by a closed polygon in the x-y coordinate plane.

Using the command ACDEF, the coordinates of the polygon edges can be entered directly or via global parameters, and existing free form conditions can be copied from other analyzers. With the command D2COND, free form conditions can be created and edited using a graphic cursor. .*********************************************************************

Analyzer Types

.***************** :iref refid=atyp. .***************** The analyzer type specifies if and what kind of spectrum is attached to the analyzer.

Type_0 analyzers have no spectrum. Their main purpose is condition checking. They are also useful for live display output (see Volume_II, DL...-commands, :hdref refid=distyp., and :hdref refid=lidis.).

You can choose between 2_byte (type_2) and 4_byte (type_4) integers, and 4_byte floating point spectra (type_24). .*********************************************************************

Channels and Bins

The results of accumulation in analysis programs are stored in analyzer spectra. The spectrum elements are called 'channels' or 'bins'. For analyzers with dimension_d, a channel of the spectrum is specified by d_numbers.

One-dimensional analyzers, created with default attributes, have 1024_channels or bins: .ce 0, 1, 2, ..., 1023. The lower limit defines the first channel, and the upper limit the last channel. Corresponding to multichannel analyzer (MCA) hardware, the range of channel_n is the semi-closed interval .ce [n,n+1). The left border of channel_n has the value_n and belongs to channel_n, whereas the right border_n+1 belongs not to channel_n, but to the next channel_n+1.

If the analyzer bin size has a value_>_1, several channels are added to a bin. For example, the analyzer mentioned above has only 256_bins with bin size_4. In general, for an analyzer with lower limit_L, the lower and upper border of bin_n have the following values:

                                                                         
.if &$PDEV = 3820                                                               
.th .tp 49mm center 71mm center 98mm center                                     
.th .bx 41mm 57mm 85mm 111mm                                                    
.el .tp 25m center 37m center 52m center                                        
.el .bx 19m 30m 45m 60m                                                         
ºbin sizeºlower borderºupper border                                             
.bx                                                                             
   º1  ºn-1+L     ºn+L                                                          
   ºB  º(n-1)B+L  ºnB+L                                                         
.bx off                                                                         
The bin mean is the arithmetic mean of the lower and upper bin border. Again the left bin border belongs to the bin, and the right bin border not.

With the calibration data element, a tool is provided to assign any value to bin means or borders. This is especially useful for display purposes to calibrate display axes (see .x.x.x.).

In SATAN notation, the channel numbers are always associated with a bin size_1, and bins and channels are only identical for analyzers with bin size_1. Remember that the original channel numbers of the incoming data are used by all macros, commands, and displays, regardless of the analyzer bin size.

These conventions are valid correspondingly for each dimension of a more-dimensional analyzer. .*********************************************************************

Accumulation of Analyzer Spectra

.***************** :iref refid=$anal. .***************** Processing of an event in relation to an analyzer is performed by the macro $ANAL. The following actions are performed:

  • The active flag of that analyzer is set.
  • Each input value for an analyzer is converted to an integer channel number by rounding to the nearest integer.
  • The input values are compared with the analyzer limits. If inside, the 'input condition valid bit' is set, else the execution of $ANAL is finished.
  • The input values are compared with the condition limits, and the corresponding flags are eventually set.
  • Finally, if the analyzer contains a spectrum, the corresponding spectrum bin is incremented by 1 or by any specified amount.
.*********************************************************************

Analyzer Handling Functions

.****************** :iref refid=aatt. .****************** Being in a session you can get information about the attributes of a specific analyzer by issuing the command .ce AATT name qual, where 'name' and 'qual' may be names or the internal numbers. The names may contain 'wild' characters at any position:

  • '%' specifies one character,
  • '*' specifies a (sub)string of any length.
To get information about all analyzers, which have been defined within the session, just specify .ce AATT * *. For more examples, see .x.x.x.

.******************* :iref refid=analcom. .******************* A number of macros, procedures and commands is available for the user for various analyzer operations. The most important functions are summarized in the following:

  • creation of analyzers, definition and modification of their attributes
    (macro $AGEN, commands AGEN and AMOD),
  • setting of condition limits and windows
    (macro $ACDEF, commands ACDEF, D2COND, DSWI),
  • accumulation of spectra
    (macro $ANAL),
  • excluding from accumulation
    (commands AON, AOFF),
  • branching in the program, dependent upon results of a window check
    (macro $AC),
  • manipulation of spectra: zeroing, arithmetics, projecting, smoothing, and normalizing,
    (commands ACLR, ASUM, ACHANNEL, AOPER, APROJECT, ASMOOTH, ANORM),
  • definition of error data
    (command AERROR),
  • definition of calibration data for any analyzer dimension
    (command ACALIB),
  • copy of spectrum, error, or calibration data between data element structures and arrays in the analysis program or user command procedure
    (macros @AGETSPE, @AGETERR, @AGETCAL, @APUTSPE, @APUTERR, @APUTCAL)
  • display of spectra and window limits with calibrated axes
    (commands DISP, D2, DOVERLAY, ...),
  • showing of analyzer spectra and analyzer attributes
    (commands ALIST and AATT),
  • storing the analyzer contents into global parameters
    (command ASTORE),
  • reading analyzer spectra from Partioned Data Set (PDS) members
    (command AREAD),
  • saving analyzers on permanent disk data sets and retrieving them
    (commands ADUMP, AFETCH).
For more information refer to :hdref refid=command and to the volumes with the corresponding detailed descriptions of commands, macros, and procedures. :emedium.

c2.2

.se mem = 'The Structure of Analysis Procedures' :head.

The Structure of Analysis Procedures

.******************* :iref refid=analpro. .******************* The stream of experimental list mode raw data is passed on for further processing in an event-by-event sequence to the analysis program. The user has to provide a routine to determine all operations to be performed on the event parameter values (also called input values) of any single event, as for example window checking, numerical transformations, spectrum accumulation etc.

The analysis routines must be external PL/I procedures written in a standard form, which is facilitated by the usage of macros. With the exception of a few macros to be used as part of PL/I statements ($AACT, $AC, $ACSTAT, $BIT), all macros must be delimited by a semicolon (';'). As a convention, all macro names begin with a '$' or '@'.

  • '$-macros' may be used only within analysis programs with a standard program header (see :hdref refid=analpro).
  • '@-macros' may be used within any program or subroutine, including initialization procedures for user command definitions.
The names of all system variables also contain a '$' and_/_or a '@'. Therefore the user should avoid these characters in choosing his own variable names.

The following picture shows the sceleton of an analysis routine. .im f3#2#1

.******************* :iref refid=$endanl. .******************* The beginning of an analysis (main) program is marked by a standard analysis program header, such as $GOOPROC for the evaluation of GOOSY list mode data in this example. To evaluate list mode data in EDAS format, only the header $GOOPROC must be replaced by $LISTPROC or $LISTVAR for events with fixed or variable length, respectively. Also the structure of analysis subroutines (header $ANLPROC) is identical. The end of an analysis program is indicated by the macro $ENDANL.

The first part of the procedure ('definition part') contains definitions, initializations, and storage allocations of all items to be used. Here the (static) analyzers have to be created, the global parameters must be declared, and definitions of user commands may be performed using the procedures $CMDDEF or $CMDFET (see :hdref refid=usercom). This part is executed only once during the initial load of the SATAN system. Note that in SATAN all variables, if not declared otherwise, are static. Their values are kept from one call to another.

.******************* :iref refid=$antry. .******************* The following 'analysis part' starts with the macro $ANTRY. This part is executed each time a block of event data (8_kbytes for GOOSY data, 4_kbytes for EDAS data) is ready for processing.

.******************* :iref refid=$evloop. :iref refid=$evname. :iref refid=$endevt. .******************* Each block of event data consists of several events, which are handled event by event within a loop. This event loop is delimited by $EVENT and $ENDEVT. For more insight into the internals refer to :hdref refid=plIint..

.******************* :iref refid=exaana. :iref refid=healimo. .******************* The listing of :figref refid=ansim01. shows a simple program written for the analysis of GOOSY list mode data of type 4.1 in SATAN. All standard GOOSY raw data types are supported in SATAN. They are described in detail in :hdref refid=gooanl.. You recognize the analysis part formed by $ANTRY and $ENDANL. $GOOPROC is used to provide the proper entry point for GOOSY list mode data. .im f3#2#2

Three analyzers named AL, BETA, and GAMMA are created, each with the second ('qualifier') name LIST. AL has the default channel limits 0 to 1023. The analyzer type_2 means 2_bytes integers. The analyzers will contain spectra and control information. BETA, for example, consists of a spectrum running from channel number 0 to 2000, and has one condition, namely number_1, which is set by $ACDEF from 150 to 600.

Each event, which in this case consists of four parameters, is processed in the loop from $EVENT to $ENDEVT. Variable names are assigned to the event parameters (PATT, PA, PB, PC in this case) for subsequent reference in the program. For each event in the loop all condition flags of all analyzers will be cleared first.

Analyzer activity in the analysis part is invoked by the macro $ANAL with the analyzer name and event parameters ('input values') as arguments. If for any event this macro is encountered, the analyzer's 'active flag' is set first. Then the input values are compared with the analyzer and condition limits. The corresponding flags (analyzer input valid bit and condition bits) are set. Further the bin belonging to the input value (channel number) is incremented thus accumulating the analyzer spectrum.

.****************** :iref refid=$aact. :iref refid=$ac. .****************** The macros $AACT and $AC are provided in order to check the flags in subsequent program sections: $AACT checks the 'active flag', $AC the specified condition flags. In this example $AC is used to check the first condition flag of analyzer BETA whether it was set in the $ANAL macro in the previous line. That means, if the input value PB lies inbetween the channels 150 and 600, then and only then analyzer GAMMA is incremented.

After reaching $ENDEVT the process will continue again at the macro $EVENT, and the next event will be processed. This step is repeated as long as there are events in the buffer. $ENDANL in SATAN marks the end of processing one data buffer, and control is returned to the calling SATAN system routine which will provide for the next buffer.

The following example (:figref refid=antele.) shows a simplified evaluation of the telescope experiment of :figref refid=telesc.. The analysis program consists of macros, interspersed with PL/I, the language into which the macros will be expanded in SATAN.

The header and the generation of analyzers (macros $LISTPROC and $AGEN) are known already from the previous figure. Very often the problem occurs to read in data from the terminal. For this purpose it is recommended to use the prompting library procedures offered by the SATAN system. In the initilazation part of this example, with the procedure $PROMPT the specified text is printed on the terminal, and values for the various calibration factors are read in and passed to the corresponding PL/I variables. .****************** :iref refid=promch. .****************** All size checking and reprompting in the case of erroneous input is properly handled. For more details refer to the procedure descriptions in Volume_V.

Three parameters are offered with the $EVENT macro: DE (for energy loss), T (for time of flight) and E (for energy). These raw data are analyzed in the analyzers DENERGY, ENERGY, and TIME. Now derived quantities (the calibrated data) are calculated. The calibrated energy is fed into the analyzer CENERGY and as a result of some condition flag checking the analyzers MASSZ(i) are accumulated: mass and the square of the charge are kept for three different energy ranges. .im f3#2#3

In this example, the calibration factors can only be entered in the initilization phase at the beginning of the SATAN session. There is another and more flexible way of getting numbers into your program. If the calibration factors (R_EFAC, R_TFAC, R_DEFAC) are declared with the macro @PARDCL as being global parameters: .ce @PARDCL(R_EFAC, R_TFAC, R_DEFAC); .******************* :iref refid=glopdef. .******************* they are known to the analysis program as well as to the interactive part of SATAN. They can be set and modified now interactively by the command IPAR at any time during the SATAN session (see :hdref refid=glopcon.).

Default type of a global parameter is DEC FLOAT(6), but also other data types and indexed variables are allowed in SATAN (see :hdref refid=glopar.): $PARDCL(CTEXT) TYPE(80) INIT('Meine Messung:'); $PARDCL(BFLAGS(12)) TYPE(1); $PARDCL(DVAL,DERR) TYPE(4); A characterstring, an array of 12 bits and two double precision floating point global variables are declared.

If you want to take any of these examples as a start-up for your own analysis program, copy them, they are on &manexa.

Having completed the analysis program, it has to be compiled with the TSO-Commands PLO (in foreground) or PLOB (in batch) and loaded with the system (see :hdref refid=sysuser., or TSO-Command SATAN). Data input from any raw data device is then started with the EDAS-Command 'INPUT'.

C2.4

.se mem = 'Aids to Write Analysis Programs' :head.

Aids to Write Analysis Programs

In the following some hints are given to help in the solution of frequently asked questions.

Modular Analysis Programs

In SATAN analyzing list mode data can be distributed to several analysis routines, now beginning with $ANLPROC. The connection between them is established by the macros :iref refid=$branch. :iref refid=$brdcl. $BRANCH and $BRDCL. The source texts should be kept in different members. Thus a modular structure of related analysis routines is possible. It saves compile time and helps in debugging. .im f3#4#1

Pattern Word

:iref refid=pattb. :iref refid=patword.

Generally not all parameters in the event have a common trigger. Some ADCs might not have fired. To get information about that, the hardware provides a special parameter called 'pattern word'. Each bit in that 16 bit word stands for one ADC (or a group of ADCs, depending on the hardware configuration). If it is '1' the corresponding ADC (ADC group) was read out, if it is '0', the ADC(s) had not fired. Let us assume the following example of an event (in decimal representation), where the first parameter is the pattern word:

                                                                 
1                                                                            
   (22,0,13,918,0,9).                                                           
1 The pattern word value of 22 has the binary representation
                                                                 
1                                                                            
   '0000000000010110'                                                           
1 showing that the parameters no. 2, 3, and 5 are non-zero: in fact they have the values 13, 918, and 9.

As a tool to check the bits of the pattern word, EDAS provides the :iref refid=$bit. macro $BIT. As an example, following EDAS analysis program is given:

                                                                 
1                                                                            
   $LISTPROC   ;                                                                
   ...                                                                          
   $AGEN (AN) LIMITS(0,1023,0,1023) BINS(10) ;                                  
   $ANTRY;                                                                      
      $EVENT(P,AL,BET,PE,EE,IZ);                                                
      ...                                                                       
        IF $BIT(4,P) THEN $ANAL(AN,PE,EE);                                      
      $ENDEVT;                                                                  
   $ENDANL;                                                                     
1 Only if bit no. 4 (the fourth from the right) in parameter P is on, the input values PE and EE will be analyzed in analyzer AN.

Also other parameters in the event can be bit-checked. For that purpose P has to be replaced by the corresponding name of the parameter.

Events of Variable Length

If there is a multi-parameter experiment it is a waste of time and space to write out all parameters of the defined event because it mainly would contain zeros. It is sufficient to write only those which have been triggered. The information about the mapping of the numbers to the ADCs has to be put in the first parameter. From there the actual length of the event can be derived in the analysis program and therefore the beginning of the next control parameter is determined. The following analysis program processes events of a variable length less than or equal to 17. The actual length is determined by the number of bits being '1' in the pattern word PATTERN.

                                                                 
1                                                                            
    $LISTVAR;                                                                   
    ....                                                                        
    DCL (IL,I) BIN FIXED(15) ;                                                  
    $ANTRY;                                                                     
    $EVENT(PATTERN,P(16)) ;                                                     
       IL=1;                                                                    
       DO I=1 TO 16;                                                            
          IF $BIT(I,PATTERN) THEN IL=IL+1 ;                                     
       END;                                                                     
       ...                                                                      
       ...                                                                      
    $ENDEVT (IL) ;                                                              
    $ENDANL;                                                                    
1 :iref refid=healimo. Note that $LISTVAR has to be used instead of $LISTPROC and that $ENDEVT got an argument now: the length of the event that was just processed.

Another example is to evaluate the data produced by the program shown in :figref refid=modev._:

                                                                 
1                                                                            
    $LISTVAR;                                                                   
    ....                                                                        
    DCL (IL,I) BIN FIXED(15) ;                                                  
    $ANTRY;                                                                     
    $EVENT(PNUMBER,PAR(9));                                                     
       IF PNUMBER=3 THEN DO;                                                    
          ...                                                                   
       END;                                                                     
       ELSE IF PNUMBER=10 THEN DO;                                              
          ...                                                                   
       END;                                                                     
    $ENDEVT (PNUMBER) ;                                                         
    $ENDANL;                                                                    
1 At the moment there is no possibility to produce such compressed data directly with GOLDA. The new TADEX hardware will allow that in future. .***********************************************************

Executing Commands in Procedures

The user is enabled to use all functions of SATAN by calling system subroutines. Though universal, it is uncomfortable to look for the suitable routine, to get the parameters and the declaration correct. If it is not mandatory to return parameters, SATAN provides the possibility to invoke commands from a procedure by the macro $EXCMD. :iref refid=$excmd.

The :figref refid=excmd._ gives an example. At the very beginning of the analysis the display command is invoked. Then the y-scale is fixed to a range of 1 to 2,000. After that at every 10,000th event the spectrum ETOT is drawn on the graphic screen without erasing the previous picture. .im f3#4#2 Note that the argument of $EXCMD is a character string of variable length which can be assembled in the program:

                                                                 
1                                                                            
    $EXCMD('DISP AN('||IANL||')');                                              
1 An element of the analyzer array AN will be displayed, the index IANL might have been calculated in a previous program section. .***********************************************************

Data Reduction

Often it is useful to cut the process of the analysis in several pieces. The experimentalist might be interested in derived quantities, which he wants to evaluate later, or a calibration of the input parameters has to be done, which produces a new set of parameters which forms a new event. In such a process some events might be selected as being no longer interesting. SATAN provides for that purpose a system routine which writes the contents of an array containing a modified event to an external device, which has to be allocated previously by the command 'IOUTPUT'. The data written that way are formatted in the EDAS format, that means they can serve without further processing as data input for another analysis program.

In the example of :figref refid=modev. the input event is scanned: if the third and fourth bit of the pattern word are on, parameters 3 and 4 will be written, further if the 8th parameter is in the range between 1100 and 1456, the parameters 10 to 16 are modified and written to the external device, too. .im f3#4#3 The allocation of the data set is done via execution of a command in the analysis program using the macro $EXCMD. The necessary information to write a data block header (like run, experimenter's name, and a comment) as well as the name of the data set (which will be 'userid.EXAMPLE.DATA' in this example) are given. The data set will be established on a default volume having a default size. Because the macro $EXCMD is located in the initialization part of the analysis program (before $ANTRY), it is executed only once. Of course, the command could have been invoked also in the session. Then it should have been given before data input is started via 'GO' or 'INPUT'.

Note that the return code IRC is being checked on return from $IWRITE. :iref refid=usintwm. The first parameter in the assembled event tells the user the associated length and becomes useful when reading these events of variable length (see the paragraph :hdref refid=evarlen._). .******************************************************************

Accessing Analyzer Data in User Programs

Analyzer data in SATAN are deposited in the main memory in a specific format. SATAN provides routines to read and write spectrum data to and from PL/I arrays.

:figref refid=andup._shows a program section in which the contents of the analyzer AL of event type LIST is replaced by its logarithm. AL is a one-dimensional analyzer with the limits 0 and 511 and binsize 1. .im f3#4#4 1 Because the analyzers A and AL are supposed to be floating point (type 24) analyzers the routines $ACHGTF and $ACHSTF are used instead of $ACHGTS and $ACHSTS for analyzers of type 2 and 4. :iref refid=anspeg. :iref refid=anspest. :iref refid=usanl. Line 1 provides the proper declaration among others also for the system routines $ACHGTF and $ACHSTF by including a PL/I macro. Because the lower bound of RARR, the work array, is less than 0, $ACHGTF will return maximum and minimum of the data in RARR(0) and RARR(-1) respectively. The array ILIM contains information about limits and binsize.

$LFETCH in lines 5 and 18 serves to load the module which contains $ACHGTF or $ACHSTF, respectively, at run time. This is necessary for some SATAN routines (called 'fetchable' or 'dynamically loadable routines').

$ACHGTF then copies the analyzer data to the work array RARR. The parameters in the call specify how that transfer should be done: the analyzer will be copied completely and will replace the contents of RARR.

After a check for negative numbers the logarithm of RARR is taken and stored in analyzer AL. Note that A and AL must exist, created by $AGEN or AGEN, before refering to them. After each call the return code is checked, only IRC=0 guarantees error free execution. For more details look in volume_III.

Space Problems

:iref refid=space.

The memory in the PDP-11 available for data storage is about 192 kbytes. The allocation of spectra are done dynamically during the initialization of GOLDA. Since the PDP-11 memory hardware segmentation will be taken into account, it is not possible to calculate the used space of your spectra exactly. The PL-11 compiler output will give you some information about your memory needs. If the space will not be available, the system will give an error message during the start-up of GOLDA. Try to reduce your spectrum space (increase the bin size) or reduce the number of analyzers.

The space in the main memory of the large mainframe computers is limited, too. The default size of the storage mainly dedicated to the analyzers and work arrays (which is called 'ISA' = Initial Storage Area) is &isasize.. If this size gets exceeded, no more analyzers can be created and some analyzer and display commands can not be executed.

If the above mentioned standard size is not sufficient, the following macro, put in the analysis program at the very beginning, will modify this ISA-size:

                                                                         
1                                                                            
___$OPTION ISA(2000);                                                           
1 In this case the size of the storage is set to 2000K. Note however that the region size should be about 2000K bigger than the requested ISA size. That additional space is needed for SATAN modules and work arrays. Invoking the TSO command 'REGION' will tell you the remaining region size. If you have to increase that size, ask the SATAN group for help.

Another way to decrease the amount of storage, is to make the analyzers smaller: modify the limits or increase the bin size. Both may be done with help of the command 'AMOD'. The command ASPACE will report the space occupied by analyzers. In some cases two-dimensional spectra can be substituted by the usage of the live-display which will be described in the section :hdref refid=lidis.. .*************************************************************

Live-display

SATAN and GOLDA offer a way to observe the events like they come in. The incoming event accumulates a one-dimensional (only GOLDA) spectrum drawn on the screen or displays :iref refid=livedis. :iref refid=exaliv. two-dimensional correlations by marking the input value pair in a plane.

In the following a problem is given which is first solved without and then with live-display.

                                                                 
1                                                                            
   $LISTPROC;                                                                   
   ...                                                                          
   $AGEN (A#B) LIMITS(1,1024,1,1024) BINSIZE(10) TYPE(2);                       
   $AGEN (A#C) LIMITS(1,1024,1,1024) BINSIZE( 5) TYPE(2);                       
   $ANTRY;                                                                      
   $EVENT(U,V,W,X,Y,Z);                                                         
      ...                                                                       
      $ANAL(A#B,V,W) ;                                                          
      $ANAL(A#C,V,X) ;                                                          
      ...                                                                       
   $ENDEVT;                                                                     
   $ENDANL;                                                                     
1 The correlation between the parameters V and W are recorded in the twodimensional analyzer A#B, those between V and X in A#C. The space needed for the analyzers is about (42,000 + 84,000)*2 = 256,000 bytes.

Another way is to record the correlations in live-displays:

:boxfo                                                                  
1                                                                            
   $LISTPROC;                                                                   
   ...                                                                          
   $AGEN (A) LIMITS(1,1024)  TYPE(0);                                           
   $AGEN (B) LIMITS(1,1024)  TYPE(0);                                           
   $AGEN (C) LIMITS(1,1024)  TYPE(0);                                           
   $ANTRY;                                                                      
   $EVENT(U,V,W,X,Y,Z);                                                         
      ...                                                                       
      $ANAL(A,V) ;                                                              
      $ANAL(B,W) ;                                                              
      $ANAL(C,X) ;                                                              
      ...                                                                       
   $ENDEVT;                                                                     
   $ENDANL;                                                                     
1 The analyzers A, B, and C are created without spectra. Following command sequence has to be given in the session:
                                                                 
1                                                                            
   DLINIT 2 / POINTS(20000)                                                     
   DLIVE A B                                                                    
   DLIVE A C              .                                                     
1 Two live pictures on the screen are initialized. If during analysis an event satisfies the input condition of analyzer A and B (or A and C) the corresponding parameters are drawn as a dot in picture 1 (or picture 2) on the screen. In total 20,000 live points will be recorded and kept on the storage screen. Thus no spectrum space is needed and computing time is saved because no accumulation need to be done. A live display can as well be carried out with two-dimensional analyzers, which then also need not to have spectra.

By use of the command DLCND it is possible to run the live display under certain analyzer conditions. Let us assume there are three more one-dimensional analyzers Z2, MASS1, and MASS2. Analyzers A and B are provided with conditions. Then following command sequence may be given: .* :figref refid=ansim..

                                                                 
1                                                                            
   DLINIT 2 / POINTS(1000)                                                      
   DLIVE Z2 MASS1                                                               
   DLIVE Z2 MASS2                                                               
   DLCND 1 A  / COND(2)                                                         
   DLCND 1 B  / COND(1)                                                         
   DLCND 2 B  / COND(1)                                                         
1 Two live pictures are initialized and assigned to the analyzers Z2 and MASS1 or Z2 and MASS2 respectively. DLCND now confines which events are going to be plotted: the event which lies in the limits of Z2 and MASS1 (related to live picture number 1) is plotted only when the condition flag number 2 of analyzer A and the condition number 1 of B is set. Further, the condition flag of condition number 1 of B has to be set to let the event of Z2 and MASS2 (the second defined live display) to be plotted.

This enables the user to build a limited analysis interactively without having to recompile and reload the analysis program. Note also that the final picture can be stored on a data set (use the command DCOPY). For more details browse in volume_II. .*************************************************************

Debugging SATAN Analysis Programs

The first step is to prevent errors. It is recommended to use following conventions for the first character of variable names for the various data types: .im @deftext &lab15. It increases clarity and readability. Again: the dollar '$' and the at_sign '@' should not be used in the names of user variables to avoid conflicts with system variables.

Syntactical errors are easily found by the compilers. Severe system errors, like protection exception or operation exception, are harder to find. They are often caused by exceeding stringsizes or string- and subscript-ranges, by calling subroutines with the wrong number of arguments or with arguments whose attributes are inconsistent.

Following macro, set as first statement in your analysis program, will look for proper string sizes and subscript ranges:

                                                                         
                                                                            
___$OPTION DEBUG;                                                               
If this does not yet reveal the error the usage of the PL/I Checkout Compiler is recommended. CHECKER has to be specified when compiling the program under investigation via PLOB. Further, when running it, SATAN has to be called with the option CHECKER to execute the proper allocation of the data set $SPITSAT.ITEXT which provides additional information at runtime. The Checkout Compiler allows to set breakpoints, to modify the value of variables, to print its values at any break. The IBM manual "OS PL/I Checkout Compiler: Programmer's Guide" provides more information. .im c3#4#10

C3.4.10

Linearization

In this chapter a way to use the linearization data element in analysis programs is described. First, it has to be stressed that before any linearization can be performed a linearization prescription has to be defined by the EDAS command D2LIN. In this description it is assumed that the linearization prescription is stored on VSAM, having the name LINEAR.LIN.
Let us start now to create an analysis program to perform a linearization which will be executed in batch.
:boxfo                                                                  
1                                                                            
   $OPTION ISA(4000);                                                           
   $LISTPROC;                                                                   
   ...                                                                          
   DCL(I_ENERGY,I_ENERGY_LOSS) BIN FIXED(15),                                   
       R_CHARGE                DEC FLOAT(6);                                    
   ...                                                                          
   %INCLUDE($DCL($LINEAR);                                                      
   ...                                                                          
   $AGEN (ENERGY)       LIMITS(1,1024)  TYPE(24);                               
   $AGEN (ENERGY_LOSS)  LIMITS(1,1024)  TYPE(24);                               
   $AGEN (CHARGE)       LIMITS(1,1024)  TYPE(24);                               
   $ANTRY;                                                                      
   $EVENT(I_ENERGY,I_TIME);                                                     
      ...                                                                       
      $ANAL(ENERGY,I_ENERGY) ;                                                  
      $ANAL(ENERGY_LOSS,I_ENERGY_LOSS) ;                                        
      ...                                                                       
      $LFETCH($LINEAR);                                                         
      R_CHARGE = $LINEAR('LINEAR','LIN',FLOAT(I_ENERGY),                        
                         FLOAT(I_ENERGY_LOSS,RC),                               
      $ANAL(CHARGE,FLOOR(R_CHARGE*100));                                        
      ...                                                                       
   $ENDEVT;                                                                     
   $ENDANL;                                                                     
All what we have to mention is that the two variables I_ENERGY and I_ENERGY_LOSS will be rearranged due to the linearization prescription LINEAR.LIN and the result will be returned by R_CHARGE. This variable will be multiplied by 100 to have a better resolution. For simplicity we consider the case the above analysis will be performed in a batch job. This means we have to enter all out SATAN commands consecutively in a command list. This one can look like as the following one:
                                                                 
                                                                            
AFETCH LINEAR LIN/R(LIN) D(1) LIB(TUTORIAL) U(RS66)                             
LINIT LIN LINEAR                                                                
INPUT/DSN(KP02.MO9292A.DATA)                                                    
ADUMP * */R(LI) LIB(SATAN)                                                      
In this command list the linearization prescription LIN.LINEAR is fetched and the linearization is initialized. Finally the input data are read in and analysed by the above analysis program and all analyzer, including the old linearization prescription are stored on VSAM. If there is enough space available for initialization several different linearizations can be used simultanously.

C3.4.11

Calibration

FGOO.1

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .tp &colmax right :fig id=anscelg frame=none place=inline
                                                                         
.hr &colmin to &colmax                                                          
   $GOOPROC;                                                                    
        .                                                                       
        ... definition part                                                     
        .                                                                       
   $ANTRY; º/* End of Definition Part */                                        
      $EVENT( event parameters ); º/* Event loop */                             
          .                                                                     
          ... analysis                                                          
          .                                                                     
      $ENDEVT; º/* End of event loop */                                         
   $ENDANL; º/* End of analysis program */                                      
.hr &colmin to &colmax                                                          
:figcap.Sceleton of an analysis program for standard GOOSY data :figdesc. :efig.

FGOO.2

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .tp &colmax right :fig id=ansim01 frame=none place=top
                                                                         
.hr &colmin to &colmax                                                          
 /*-----------------------------------------------------------------*/          
 /*  GOOSY RAW DATA INPUT                                           */          
 /*  TEST PROGRAM FOR BUFFER TYPE 4,1                               */          
 /*     --- TIME STAMPS ARE IGNORED . THEY ARE NOT HANDED OVER TO   */          
 /*         THE ANALYSIS PROGRAM !!!                                */          
 /*     --- PACKED EVENTS , TYPE 4 SUBTYPE 2 ARE AUTOMATICALY       */          
 /*         UNPACKED UNLESS PREVENTED BY THE OPTION 'NO_UNPACK'     */          
 /*                                                                 */          
 /* 25.4.88                                                         */          
 /*-----------------------------------------------------------------*/          
 $GOOPROC;                                                                      
 $AGEN(PARAM(50)) LIMITS(1,4096);        /* EVENT PARAMETER        */           
 ;                                                                              
 DCL I BIN FIXED(15) INIT(0);            /* LOOP INDEX             */           
 ;                                                                              
 $ANTRY;                                                                        
    $EVENT(EVT_PARM(50));                /* 50 PARAMETER PER EVENT */           
                                         /* FIXED EVENT LENGTH     */           
 ;                                                                              
    /*---- FILL HISTOGRAMS ---------*/                                          
    DO I=1 TO 50;                                                               
       $ANAL(PARAM(I),EVT_PARM(I));                                             
    END;                                                                        
 ;                                                                              
    $ENDEVT;                                                                    
 $ENDANL;                                                                       
.hr &colmin to &colmax                                                          
:figcap.Analysis program with basic macros for buffer type 4 and event type 4 subtype 1,2 :figdesc.This SATAN program illustrates the use of the macro $GOOPROC and the accumulation of data from event type 4 with a fixed lenght of 50 paramters. Events of subtype 2 are automaticaly unpacked. :efig.

FGOO.3

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .tp &colmax right :fig id=ansim02 frame=none place=top
                                                                         
.hr &colmin to &colmax                                                          
 /*------------------------------------------------------------------*/         
 /*   GOOSY RAW DATA INPUT   25.4.88                                 */         
 /*   TEST PROGRAM FOR BUFFER TYPE 4,2 ---> NO UNPACK                */         
 /*      --- TIME STAMPS ARE IGNORED . THEY ARE NOT HANDED OVER TO   */         
 /*          THE ANALYSIS PROGRAM !!!                                */         
 /*      --- IF 'NO_UNPACK' IS SPECIFIED, THE FIRST 4 DATA WORDS     */         
 /*          ARE THE EVENT HEADER WORDS                              */         
 /*------------------------------------------------------------------*/         
 $OPTION NO_UNPACK;                        /* NO UNPACKING !         */         
 $GOOPROC;                                                                      
 $AGEN(DLEN) LIMITS(0,1024);               /* DATA LENGTH            */         
 $AGEN(TLEN) LIMITS(0,1024);               /*  NOT USED              */         
 $AGEN(TYPE);                              /* TYPE                   */         
 $AGEN(SUBTYPE);                           /* SUBTYPE                */         
 $AGEN(PARAM(50));                         /* EVENT PARAMETER        */         
 ;                                                                              
 DCL I       BIN FIXED(15) INIT(0);        /* LOOP INDEX             */         
 ;                                                                              
 $ANTRY;                                                                        
  $EVENT(EVT_HDR(4),EVT_PARM(100));        /* 50 PARAMETER PER EVENT */         
                                           /* + 50 channel numbers   */         
  $ANAL(DLEN,EVT_HDR(1));                   /* DATA LENGTH           */         
  $ANAL(TLEN,EVT_HDR(2));                   /* NOT USED = 0 ALWAYS   */         
  $ANAL(TYPE,EVT_HDR(3));                   /* EVENT TYPE            */         
  $ANAL(SUBTYPE,EVT_HDR(4));                /* EVENT SUBTYPE         */         
 ;                                                                              
  /*---- UNPACK EVENT ------------*/                                            
  DO I=1 TO EVT_HDR(1) BY 2;                                                    
   $ANAL(PARAM(EVT_PARM(I)),EVT_PARM(I+1));                                     
   END;                                                                         
 ;                                                                              
 $ENDEVT;                                                                       
 $ENDANL;                                                                       
.hr &colmin to &colmax                                                          
:figcap.Analysis program with basic macros for buffer type 4 event type 4 subtype 1,2 :figdesc.This simple SATAN program illustrates the use of the option NO_UNPACK. The event data together with the event header data are passed to the analysis routine. :efig.

FGOO.4

.* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .tp &colmax right :fig id=ansim03 frame=none place=top
                                                                         
.hr &colmin to &colmax                                                          
 /*------------------------------------------------------------------*/         
 /*   TEST PROGRAM FOR BUFFER TYPE 4 WITH OPTION USER_MODE           */         
 /*      --- FREE FORMAT DATA ARE PASSED TO THE ANALYSIS ROUTINE     */         
 /*          WITHOUT INTERVENTION BY SATAN.                          */         
 /*      --- THE BUFFER HEADER IS ALWAYS IN IBM FORMAT !!            */         
 /*------------------------------------------------------------------*/         
 $OPTION USER_MODE;                                                             
 $GOOPROC;                                                                      
 DCL (I,J,I_RC)  BIN FIXED(15) INIT(0);    /* LOOP INDEX             */         
 DCL $SWI2B ENTRY(POINTER,BIN FIXED(15),BIN FIXED(15));                         
 %INCLUDE $MACRO(SA$BUFHE);    /* include buffer header structure    */         
 %INCLUDE $MACRO(SA$EVHE);     /* include buffer element structure   */         
 $AGEN(DLEN) LIMITS(0,8192);   /*--- HISTOGRAMS FOR BUFFER PARAMETER */         
 $AGEN(TLEN) LIMITS(0,8192);                                                    
 $AGEN(USED) LIMITS(0,8192);                                                    
 $AGEN(TYPE);                                                                   
 $AGEN(SUBTYPE);                                                                
 $AGEN(E_DLEN) LIMITS(0,1024);  /*--- HISTOGRAMS FOR EVENT HEADER --*/          
 $AGEN(E_TLEN) LIMITS(0,1024);                                                  
 $AGEN(E_TYPE);                                                                 
 $AGEN(E_SUBTYPE);                                                              
 $AGEN(E_PARM(50));                /*--- HISTOGRAMS FOR EVENT DATA --*/         
 $ANTRY;                                                                        
 $EVENT(P(1));                             /* DUMMY PARAMETER        */         
   P_SA$BUFHE = ADDR(I_$EVBF(1));                                               
   /*---- SWAP DATA ----------------------------*/                              
   CALL $SWI2B(ADDR(S_SA$BUFHE.I_DATA(1)),S_SA$BUFHE.I_USED*2,I_RC);            
    $ANAL(DLEN,S_SA$BUFHE.I_DLEN);  /*- HISTOGRAMS FOR BUFFER HEADER */         
    $ANAL(TLEN,S_SA$BUFHE.I_TLEN);                                              
    $ANAL(USED,S_SA$BUFHE.I_USED);                                              
    $ANAL(TYPE,S_SA$BUFHE.I_TYPE);                                              
    $ANAL(SUBTYPE,S_SA$BUFHE.I_SUBTYPE);                                        
   P_SA$EVENT = ADDR(S_SA$BUFHE.I_DATA(1));    /* START OF EVENT DATA */        
 DO J=1 TO S_SA$BUFHE.L_EVT;                   /* EVENT LOOP          */        
    $ANAL(E_DLEN,S_SA$EVENT.I_DLEN);  /*- HISTOGRAMS FOR EVENT HEADER */        
    $ANAL(E_TLEN,S_SA$EVENT.I_TLEN);                                            
    $ANAL(E_TYPE,S_SA$EVENT.I_TYPE);                                            
    $ANAL(E_SUBTYPE,S_SA$EVENT.I_SUBTYPE);                                      
    ;                                                                           
    DO I=1 TO 50 ;                                                              
      $ANAL(E_PARM(I),S_SA$EVENT.I_DATA(I));                                    
      END;                                                                      
                                               /* MOVE TO NEXT EVENT */         
    IP_SA$EVENT = IP_SA$EVENT + (S_SA$EVENT.I_DLEN + 4)*2;                      
    END;                                                                        
 $ENDEVT;                                                                       
 $ENDANL;                                                                       
.hr &colmin to &colmax                                                          
:figcap.Analysis program with basic macros for type 4 events :figdesc.This simple SATAN program illustrates the use of the optin USER_MODE. The complete GOOSY buffer is passed to the analysis routine . The conversion from VAX to IBM format and the extraction of events has to be done by the user. :efig.

fgoo.5

.*-------- buffer type 6 ---------------------------------------------- .* &colmin, &colmax, Tabulator-Zeichen (º) und Platzhalter fuer blanks .* (_) sind vordefiniert .* .tp &colmax right :fig id=ansim04 frame=none place=top
                                                                         
.hr &colmin to &colmax                                                          
 /*----------------------------------------------------------------*/           
 /*   GOOSY RAW DATA INPUT                                         */           
 /*   TEST PROGRAM FOR BUFFER TYPE 6,1  (UNPACKED EVENTS )         */           
 /*   1.3.88                                                       */           
 /*----------------------------------------------------------------*/           
 $GOOPROC;                                                                      
 $AGEN(DLEN);                       /* DATA LENGTH                 */           
 $AGEN(TLEN);                       /* TOTAL LENGTH (NOT USED )    */           
 $AGEN(TYPE);                       /* EVENT TYPE                  */           
 $AGEN(SUBTYPE);                    /* EVENT SUBTYPE               */           
 $AGEN(C1_LEN);                     /* LENGTH OF SUBEVENT 1        */           
 $AGEN(C1(14));                     /* DATA FOR SUBEVENT 1         */           
 $AGEN(C2_LEN);                     /* LENGTH OF SUBEVENT 2        */           
 $AGEN(C2(14));                     /* DATA FOR SUBEVENT 2         */           
 $AGEN(C3_LEN);                     /* LENGTH OF SUBEVENT 3        */           
 $AGEN(C3(14));                     /* DATA FOR SUBEVENT 3         */           
 ;                                                                              
 DCL I BIN FIXED(15) INIT(0);                                                   
 %INCLUDE $MACRO(SA$MBD);            /* INCLUDE UNPACKED DEFAULT   */           
                                     /* MBD STRUCTURE              */           
 ;                                                                              
 $ANTRY;                                                                        
  $EVENT(P(7011));                   /* STRUCTURE LENGTH 7011 WORDS */          
                                     /* FIXED BY GOOSY'S           */           
  P_SA$MBD = ADDR(P(1));                                                        
  $ANAL(DLEN,IA$MBD_DLEN);                                                      
  $ANAL(TLEN,IA$MBD_TLEN);                                                      
  $ANAL(TYPE,IA$MBD_TYPE);                                                      
  $ANAL(SUBTYPE,IA$MBD_SUBTYPE);                                                
  $ANAL(C1_LEN,IA$MBD_C1_SLEN);      /*---- CRATE 1 -----------------*/         
  DO I=1 TO 14 ;                                                                
   $ANAL(C1(I),IA$MBD_C1(I));                                                   
   END;                                                                         
  $ANAL(C2_LEN,IA$MBD_C2_SLEN);      /*---- CRATE 2 -----------------*/         
  DO I=1 TO 14 ;                                                                
   $ANAL(C2(I),IA$MBD_C2(I));                                                   
   END;                                                                         
  $ANAL(C3_LEN,IA$MBD_C3_SLEN);      /*---- CRATE 3 -----------------*/         
  DO I=1 TO 14 ;                                                                
   $ANAL(C3(I),IA$MBD_C3(I));                                                   
   END;                                                                         
 ;                                                                              
 $ENDEVT;                                                                       
 $ENDANL;                                                                       
.hr &colmin to &colmax                                                          
:figcap.Analysis program for data of buffer type 6 :figdesc.This SATAN program shows an analysis program for standard MBD events of type 6 subtype 1 with 3 crates and 14 words of data per crate. The length of the structure is fixed to 7011 words. :efig.

F1.1.1

:fig id=datflw frame=none place=top.
                                                                         
.bx &colmin. &colmax.                                                           
 16cm                                                                        
.bx off                                                                         
:figcap.Data flow in SATAN :figdesc. The data may be fed in from an external device (disk, tape, or cartridge) and are distributed by the dispatcher to several analysis sections. The output may consist of modified raw data or spectra. All these processes are controlled interactively from the terminal via commands. :efig.

F1.2.1

:fig id=uexits frame=none place=top .tp 5mm 12mm 43mm 47mm 87mm 105mm
.bx &colmin. 40mm 80mm &colmax.                                                 
ºSATAN commandººProcedure invoked ºººFunction                                   
.hr thick &parb1 &parb4                                                         
ºº            ºº$INIT             ºcommand definitions (no analysis)            
.bx                                                                             
ºº GO         ºº$MYGO             ºstart data input                             
.bx                                                                             
ºº HALT       ºº$MYHALT           ºstop data input                              
.bx                                                                             
ºº EXIT       ºº$MYEXIT           ºleave SATAN                                  
.bx                                                                             
ºº INPUT      ºº$MYINP            ºallocate and start input                     
.bx                                                                             
ºº MFO28      ºº$MYFORM           ºconvert external raw data format             
.bx                                                                             
ºº FMY        ºº$MYFIT            ºuser defined fit function                    
.bx off
:figcap.SATAN user exits :figdesc.For more information refer to the corresponding procedure descriptions in the SATAN manual. :efig.

F1.3.1

:fig id=addrspu frame=none place=top :vlarge. .if &$PDEV = 3820 .th .tp 22mm right 25mm center 76mm center 128mm center 131mm .th .bx 25mm 128mm .el .tp 8m right 10m center 35m center 60m center 62m .el .bx 10m 60m .sb +3mm º2 Gbyte .sb -3mm 3 .********************************************* .bx ºººbased and controlled variablesºº:vhuge.HEAP:evhuge. ººº(all SATAN data elements) :huge. :ehuge. .bx .********************************************* 2 .bx can :evlarge. ºº&eqv.ºº&eqv. :vlarge. .if &$PDEV = 3820 .th .bx set 25mm 128mm .el .bx set 10m 60m 2 .********************************************* .bx ºººdynamically loadable modules .bx .********************************************* 3 .if &$PDEV = 3820 .th .hr thick 23mm 130mm .el .hr 8m 62m .sb +5mm º16 Mbyte .sb -5mm .********************************************* .bx ºººresident SATAN nucleus .bx .********************************************* .********************************************* .bx ºººautomatic variablesºº:huge.ISA:ehuge. .bx .********************************************* .bx off .sb +5mm º0 .sb -5mm :evlarge. :figcap. Scheme of the virtual address space of a SATAN user :figdesc. Fully utilizing the XA-feature of the operating system MVS, most SATAN program code and all SATAN data elements reside above the 16_Mbyte line. :efig.

F1.4.1

:fig id=docall frame=none place=inline
                                                                         
.in 0                                                                           
.bx &parb1. 60mm 120mm &parb4.                                                  
.tp 30mm center 65mm 137mm center                                               
ºSATAN documentationºdata set nameºSATAN version                                
.hr thick                                                     
ºIntroduction and ConceptsºRZ66.MANUAL.HELPºnew                                 
.bx                                                                             
ºSATAN-Commands ºRZ66.NEWEDAS.HELP  ºnew                                        
º               ºRZ66.EDAS.HELP     ºnormal                                     
º               ºRZ66.OLDEDAS.HELP  ºold                                        
.bx                                                                             
ºTSO-Commands   ºRZ66.TSO.HELP      º                                           
.bx                                                                             
ºMacros         ºRZ66.NEWMACRO.HELP ºnew                                        
º               ºRZ66.MACRO.HELP    ºnormal                                     
º               ºRZ66.OLDMACRO.HELP ºold                                        
.bx                                                                             
ºProcedures     ºRZ66.NEWPROC.HELP  ºnew                                        
º               ºRZ66.PROC.HELP     ºnormal                                     
º               ºRZ66.OLDPROC.HELP  ºold                                        
.bx off                                                                         
:figcap.The SATAN Help Libraries :figdesc.an overview on the different parts of the documentation for all SATAN versions. :efig.

F3.1.1

:fig id=telesc frame=none place=top
                                                                         
.bx &colmin &colmax                                                             
47                                                                           
.bx off                                                                         
:figcap.A simple telescope experiment :figdesc. A scattered particle initiates three signals which are digitized and form a set of correlated parameters, an event. These data are saved on tape or disc and fed into an analysis program, which calculates derived quantities and performs spectrum accumulation. :efig.

F3.2.1

:fig id=anscele frame=none place=inline
                                                                         
.bx &colmin. &colmax.                                                           
    $GOOPROC;                                                                   
        .                                                                       
        ... definition part                                                     
        .                                                                       
    $ANTRY;   /* begin of analysis part */                                      
       $EVENT( event parameters );                                              
          .                                                                     
          ... analysis                                                          
          .                                                                     
       $ENDEVT;                                                                 
    $ENDANL;                                                                    
.bx off                                                                         
:figcap.Sceleton of an analysis program :efig.

F3.2.2

.tp &colmax right :fig id=ansim01 frame=none place=top
                                                                         

&colmin to &colmax $LISTPROC; $AGEN(AL) TYPE(2); $AGEN(BETA) LIMITS(0,2000) NCND(1); $AGEN(GAMMA) LIMITS(0,100); $ACDEF(BETA,1,150,600); $ANTRY; º/* End of Definition Part */ $EVENT(PATT,PA,PB,PC); º/* Event loop */ $ANAL(AL,PA); $ANAL(BETA,PB); IF $AC(BETA,1) THEN $ANAL(GAMMA,PC); $ENDEVT; º/* End of event loop */ $ENDANL; º/* End of analysis program */
&colmin to &colmax
:figcap.Analysis program with basic macros :figdesc.This simple SATAN program illustrates the creation of analyzers ($AGEN) and the definition of a condition ($ACDEF) in the definition part. In the analysis part events are read in ($EVENT), and analysis and accumulation ($ANAL), as well as condition flag checking ($AC) take place. :efig.

F3.2.3

:fig id=antele frame=none place=top .tp &colmax right
                                                               
.bx &colmin &colmax                                                             
 $LISTPROC;                                                                     
  /* */                                                                         
  DCL (R_TZERO, R_EZERO, R_DEZERO) DEC FLOAT(6) INIT(0.0),                      
      (R_MCAL, R_Z2, R_ECAL, R_TCAL, R_DECAL,                                   
       R_TFAC, R_EFAC, R_DEFAC) DEC FLOAT(6),                                   
      I BIN FIXED(15);                                                          
  /* */                                                                         
  %INCLUDE $MACRO($PROM);  º/* includes declarations for prompting */           
  /* */                                                                         
  $AGEN (DENERGY)  LIMITS(0,100)  BINS(2)  TYPE(2);                             
  $AGEN (ENERGY)  LIMITS(0,100)  BINS(2)  TYPE(2);                              
  $AGEN (TIME)  LIMITS(0,100)  BINS(2)  TYPE(2);                                
  $AGEN (MASSZ(3))  LIMITS(0,100,0,100)  BINS(4)  TYPE(2);                      
  $AGEN (CENERGY)  LIMITS(0,3000) BINS(1)  TYPE(24)  NCND(3);                   
  /* */                                                                         
  $ACDEF(CENERGY,1,21,23);               º/* energy conditions  */              
  $ACDEF(CENERGY,2,201,233);                                                    
  $ACDEF(CENERGY,3,2000,3000);                                                  
  /* */                                                                         
  CALL $PRTCL('ENTER CALIBRATION DATA',1);º/* read some calibration  */         
                                          º/* factors                */         
  CALL $PROMPT('ENERGY FACTOR',R_EFAC); º/* from the terminal      */           
  CALL $PROMPT('TIME FACTOR',R_TFAC);    º/* using system prompting */          
  CALL $PROMPT('ENERGY LOSS',R_DEFAC);   º/* routines               */          
  /* */                                                                         
 $ANTRY;                                  º/* start of the analysis  */         
  /* */                                                                         
   $EVENT(DE, T, E);                                                            
      $ANAL(DENERGY,DE);                  º/*  accumulate from the  */          
      $ANAL(ENERGY,E);               º/* counters of the experiment */          
      $ANAL(TIME,T);                                                            
      /* */                                                                     
      R_ECAL=R_EFAC*(E-R_EZERO); º/* calibrate energy and energy loss */        
      R_DECAL=R_DEFAC*(DE-R_DEZERO);                                            
      $ANAL(CENERGY,R_ECAL);  º/* save calibrated energy          */            
      R_TCAL=R_TFAC*(T-R_TZERO); º/* calibrate time               */            
      /* */                                                                     
      R_MCAL=R_ECAL*R_TCAL*R_TCAL;          º/* evaluate the mass and */        
      R_Z2 = (R_ECAL/R_MCAL) *R_DECAL*R_EFAC;º/* square of the charge */        
      /* */                                                                     
      DO I=1 TO 3;                                                              
         IF $AC(CENERGY,I) THEN  º/* for three energies accumulate */           
         $ANAL(MASSZ(I),R_MCAL,R_Z2); º/* mass and charge        */             
      END;                                                                      
      /* */                                                                     
   $ENDEVT;                             º/* end of event loop      */           
 $ENDANL;                               º/* end of analysis        */           
.bx off                                                                         
:figcap.SATAN analysis program for telescope experiment :figdesc. The transformation of the experimental setup of :figref refid=telesc. to an appropriate analysis program is demonstrated. Further it can be seen how to read data from the terminal using the system prompting routines. 2 :efig.

F3.3.1

:fig id=anscele frame=none place=inline
                                                                         
.bx &colmin &colmax                                                             
    $LISTPROC;                                                                  
        .                                                                       
        ... definition part                                                     
        .                                                                       
    $ANTRY;   /* begin of analysis part */                                      
       $EVENT( event parameters );                                              
          .                                                                     
          ... analysis                                                          
          .                                                                     
       $ENDEVT;                                                                 
    $ENDANL;                                                                    
.bx off                                                                         
:figcap.Sceleton of an analysis program :efig.

F3.3.1I

:fig id=ansceli frame=none place=inline
                                                                     
.bx &colmin &colmax                                                             
    $INITPROC;                                                                  
        .                                                                       
       DCL myentry ENTRY( ... );                                                
        .                                                                       
        .                                                                       
       CALL $CMDDEF('cmd-string',myentry);                                      
        .                                                                       
        .                                                                       
    $ENDINIT;                                                                   
.bx off                                                                         
:figcap.Example of an initialisation program :efig.

MACROS

The names and the keywords of the macros must not contain any lower case characters. Macro lines should be delimited by a semicolon. They are expanded into executable PL-11 or PL/I code by special compilers, which are invoked by the TSO commands PL11 or PL11B (GOLDA) and PLO or PLOB (SATAN). There are two groups of EDAS macros distinguished by their first character. All macros beginning with a '$'-sign can be used only in analysis programs starting with a standard program header.
All macros beginning with a '@'-sign (SATAN only) can also be used in 'normal' subroutines in the SATAN environment, including user defined commands.

MFO28

After the measurements, the recorded data can be used as input for further evaluation ('replay mode'). This is usually done in SATAN, the IBM side of EDAS. For that purpose it might be necessary to convert the format of the PDP tapes to that of IBM tapes: ASCII characters have to be changed into EBCDIC characters and the bytes have to be swapped (see command MFO28 in volume_II and :hdref refid=exampt2.). By use of commands the data wanted can be picked out, either the spectra, which were accumulated by the PDP (command IPDP), or the list mode data, for which then a suitable analysis routine has to be provided.

R

(see :hdref refid=cosuser.).

User Interfaces

SPECTRA

The analyzer qualifier is In SATAN: a sequence of one to 18 alphanumeric characters (letters, digits, or special characters .ti 6d 6d '$','@','_'); .ti _ 41 the first character of the name must be a letter, '$' or '@'. The following qualifiers are defined by default:
  • 'LIST' if the spectrum was created from SATAN list mode data
  • 'GLIST' if the spectrum was created from GOLDA list mode data (GOLDA event type_1)
  • 'DMI' if the analyzer was created using a DMI or a CMI spectrum (GOLDA event type >_1)

X

using the analyzer concept as the basis. An extensive introduction into writing SATAN analysis programs with many examples is provided in :hdref refid=datanal.. A detailed description of each SATAN macro may be referenced in Volume III of this manual.