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:
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.
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
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 SATAN environment consists of the following main components:
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:
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 macro concept has many other advantages:
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.
.********************************************************************
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:
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).
.********************************************************************
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 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.
Three different types of command parameters are possible.
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.
.********************************************************************
SATAN runs on the IBM host in the computing center with the
operating system MVS/ESA. Sessions may be executed
.tp &colmax right
In principle, there are several possible ways to start a SATAN
session. Typical sequences of TSO commands are:
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.
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.
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.
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.
.********************************************************************
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 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.
The data element linearisation consists of
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
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:
Independent of the physical medium, the SATAN
documentation consists of five parts:
.*******************
: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
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.
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:
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
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.
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:
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.
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
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.
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
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.
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(....).
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.
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.
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.
Time stamps are recognized by SATAN but not passed to the analysis
program.
.*----------- buffer header ----------------------------------------
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 ------------------------------------
Length of buffer without this buffer header in 16-bit words
A number specifying the buffer type
A number specifying the buffer subtype
The number of 16-bit words actualy used in this buffer
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.
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.
Total number of fragments and data elements in this buffer.
A current number of buffers of the same kind
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.
VAX binary time stamps (64 bit)
The data field of the buffer. The structure of data is specified
by the buffer type and subtype.
.im @gooele
Length of buffer element without this header in 16-bit words.
A number specifying the element type
A number specifying the element subtype
Any structure of data depending on type and subtype.
Length of buffer in 16-bit words excluding this header.
For file header buffer always = 2000.
For file header buffer always = 1.
Depends on length of comment.
This field is always = 0.
This field is always = 0.
for this file header always = 1.
A current number of buffers of the same type.
Indicates VAX /IBM format of this buffer header and data.
A value of -1 indicates IBM data any other >= 0 indicates VAX
data format.
A quadword for the system time in VAX/VMS binary format.
Number of characters used in the next field
Contains the tape label of the ANSI tape if the file was created
on a tape.
Number of characters used in the next field
Name of file at the time of creation.
Number of characters used in the next field
User name of the creating VAX/VMS process.
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.
Number of characters used in the next field
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 characters used in the next field
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 78 character comment lines following
Number of characters used in the next field
Character string array to characterize the contents of this file.
The lines are user defined. The header can have a maximum of 46
lines.
.* &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
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).
Structure declaration
.im @gooev61
Length of buffer element without this header in 16-bit words.
A number specifying the element type = 6
A number specifying the element subtype
Length of subevent in words excluding header longword .
A counter to check the correct order of events and subevents.
In IBM format the counter and CRATE bytes are swaped !
The number of the CAMAC crate where the subsequent subevent data
come from.
In IBM format the counter and CRATE bytes are swaped !
Data
.kp on
Structure declaration
.kp on
The data element linearisation consists of
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
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:
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:
In principle, information is available at three levels,
differing from each other by the depth of information and the
number of details.
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.
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, 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:
In the raw data input stream, SATAN recognizes two distinct
data types:
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.
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..
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:
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.
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
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.
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.
A set of PL/I subroutines is supplied
offering
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 interactive SATAN command language allows the execution of
standard functions. Commands enable
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.
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.
.******************
: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.
.*****************
:iref refid=gooint
.*****************
GOOSY raw data and spectra can be transferred to the central
processor of the computer center in several ways:
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
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.
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:
For storage and retrieval of data elements, a data element
library is available (see :hdref refid=sanalib.).
The data element linearisation consists of
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.
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:
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.
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.
There are a number of ways to add user written code to SATAN:
There are two possibilities to run SATAN sessions with user
sections included.
.*****************
: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:
.*****************
:iref refid=intbat
.*****************
Since the same functions are available interactively and in
batch, the user may separate the work into two parts:
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
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..
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.
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 SATAN graphic software is integrated in the general
graphic concept of the GSI computer center, which is based on
Pictures (including live displays) can be stored in plotfile
format, either
Pictures stored in the GDF vector file format may be further
processed in two ways.
Some more details can be found in section
:hdref refid=gradev..
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.
The extended architecture (XA) feature of the
operating system allows to address
For the control of load modules at run time, the Linkage
Editor and the Loader have two options:
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:
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
.******************
: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:
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:
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.
Entering the TSO command 'SATAN', the following functions
are performed initially:
Utilizing the PL/I multitasking facility, the task structure
of SATAN allows for asynchronous execution of different
functions:
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 native PL/I FETCH statement cannot fulfill the following
important requirements:
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
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:
Independent of the physical medium, the SATAN
documentation consists of five parts:
.*******************
: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
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 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:
.*******************
: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
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.
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:
In the raw data input stream for analysis procedures, there
may be two distinct data types (see also :hdref
refid=datform.):
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..
: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.
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.
In analysis programs, but not at command level, several
analyzers can be created with one statement. For example,
the macro
The analyzers created above have default attributes,
that means
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.
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.
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).
One-dimensional analyzers, created with default attributes,
have 1024_channels or bins:
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:
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.
.*****************
:iref refid=$anal.
.*****************
Processing of an event in relation to an analyzer is
performed by the macro $ANAL.
The following actions are performed:
.******************
:iref refid=aatt.
.******************
Being in a session you can get information about the
attributes of a specific analyzer by issuing the command
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').
Naming Conventions
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.
ºuid.LMDI.vvvvvvff.vaxfile º(IBM representation, with option CONVERT)
.if &$PDEV = 3820
.th .se tsize = 25mm
.el .se tsize = 12
tsize=&tsize termhi=1
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.
Reduced Raw Data
Raw Data Transfer between IBM and VAX
COF3SAT
.se mem = 'SATAN Overview'
:head.
SATAN Overview
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
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
.********************************************************************
Like all SATAN commands, also user commands may be invoked
interactively
: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.).
The Programming Language
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').
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.
Analysis Programs
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
Initialisation Programs
The Command Language
The interactive SATAN command language allows execution of
standard functions. It gives the possibility
utilizing the powerful global parameter tool of SATAN,
compact tsize=8 termhi=0.
.kp off
A few frequently used commands do not obey these naming rules (e.g.
'HALT', 'HELP', 'REPEAT', 'TUTORIAL', 'EXIT').
Each optional parameter is provided with a default value. Two
kinds of default values are possible:
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.
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 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'.
Most command and parameter names may be abbreviated as long as
the remainder is unique
Their values are unchanged and take effect each time the
corresponding parameters are not explicitely specified.
They act like static defaults, but their values are overwritten
by the corresponding parameter values used last.
Example:
Display analyzer A of event type LIST within the limits of channel
numbers 100 and 260.
Example:
Write the character string "SATAN'S_ANALYZER" (positional parameter)
as comment on the current picture.
Example:
Assume the command EXAMPLE to be defined with three positional
parameters.
compact tsize=20 termhi=0.
.********************************************************************
The SATAN Versions
Calling SATAN
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.
SATAN NEW OBJ( MYANAL(GAMMA) ) º(2)
SATAN NEW CALL(SGAMMA) º(4)
The special SATANGD System
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
.********************************************************************
The Data Element: Analyzer
An analyzer may consists of
All these components are optional.
The Spectrum
The Error Spectra
The Conditions
The Display Windows and Points
The Data Element: Calibration
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 Element Library
Documentation of SATAN
The Interactive HELP Facilities and Tutorials
How to keep your SATAN Manual up-to-date
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
COF4GOO
.ti 6d 6d
.se mem='Processing GOOSY data with SATAN'
:head
Processing GOOSY data with SATAN
Introduction
Data Analysis providing unpacked Event Parameters
Data Analysis without unpacking of Event Parameters
Data Analysis without unpacking of Buffers
.im fgoo#4
Standard MBD Data (Event Type 6)
Appendix
Supported GOOSY Buffer and Event Types
GOOSY Buffer Structures
Structure declaration
.*------------- buffer element header -------------------------------
Structure declaration
.kp on
Structure declaration
Buffer Type 1, Subtype 1
Buffer Type 4, Subtype 1
Buffer Type 6, Subtype 1
.kp off
/*---- $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
...rawend
/*---- $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 */
;
CT
.********************************************************************
The Data Element: Calibration
.********************************************************************
The Data Element: Linearization
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.
.****************
:iref refid=guide
.****************
How to Use this Documentation
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.
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 Summary
The Raw Data
.kp on
.*****************
:iref refid=listmo
.*****************
Data Flow and Analysis in SATAN
The principal structure of data flow is shown in
:figref refid=datflw..
.im f1#1#1
Analysis Procedures
Any SATAN-Command can be invoked in analysis procedures using
the SATAN-Macro @EXCMD. Examples of standard functions
offered are:
This modular construction makes the system very flexible, allowing the
user to integrate new routines easily.
Program Development
The Library Functions
Additionally interfaces are available, which allow access to
the data element libraries from FORTRAN main programs running
independent of the SATAN environment.
- handling of random number distributions,
- peak search algorithms,
- smooth and spline algorithms, and
- linearizing of spectra.
The Command Language
.*******************
: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.
Additionally the user may define own commands invoking self
written routines interactively.
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.
SATAN Versions
Interfaces to GOOSY
:emedium.
C1.2
.pa
:medium.
.se mem = 'Basic Concepts'
:head.
Basic Concepts
The Raw Data Concept
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.
Data Elements in SATAN
Analyzers
:iref refid=anconc
An analyzer consists of
.*
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
Linearizations
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
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
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
The User Section of SATAN
.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
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.
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).
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 principal Procedure of Experiment Data Processing
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.
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'.
Interactive and Batch Processing
Data Transfer with External Installations
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).
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.
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 essential advantage of using the plotfile or the GDF file
is the easy transfer of pictures between graphics devices and
systems.
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).
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
Some Aspects of the Operating System
The Extended Architecture (XA) Feature
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:
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.
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.
The Adress Space of a SATAN User
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 Programming Language
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:
.******************
: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.
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
The Debugging Environment
SATAN Internals
.
The SATAN Multitasking
.
Dynamical Loading of Modules
The execution time increases only slightly due to some
housekeeping functions of the operating system.
To perform these functions, interface programs have been
developed. They have been designed as PL/I Preprocessor
macros to enable easy invocation.
C1.4
.pa
:medium
.se mem = 'Documentation of SATAN'
:head.
Documentation of SATAN
:iref refid=edasman.
The Interactive HELP Facilities and Tutorials
The SATAN Manual
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
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.
Introduction
Initialization and Analysis Procedures
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.
.******************
: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.
Analysis Programs and the Analyzer Concept
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
Analyzer Creation
Analyzers may be created with the macro $AGEN or the command
AGEN.
:iref refid=$agen.
.ti 6D 6D
For example the macro
Dimensionality and Limits
.****************
:iref refid=adim.
.****************
Analyzers may have up to four dimensions. A multidimensional
analyzer can handle several input values simultaneously:
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".
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
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.
Analyzer Types
.*****************
:iref refid=atyp.
.*****************
The analyzer type specifies if and what kind of spectrum is
attached to the analyzer.
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.
.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
Accumulation of Analyzer Spectra
Analyzer Handling Functions