|
GSI
FRS
| |
SATAN Help
LIST OF MACROS AND PROCEDURES TO BE USED IN USER-SUPPLIED PROGRAMS Conventions: In the text below the following conventions are used:
I7, BIN FIXED(7), I15 = BIN FIXED(15), I31 = BIN FIXED(31),
R6 = DEC FLOAT(6), R15 = DEC FLOAT(15),
CV = CHARACTER VARYING.
In the macros AGET, ANAL, and ASET defined by $EXTENSIONS.PLI,
the parameter C_ANALYZER is interpreted as a character-string variable:
==> C_ANALYZER = 'Mass';
==> ANAL(C_ANALYZER,I_A);
To specify a character string directly, the parameter C_ANALYZER
has to be put in quotes:
==> ANAL('A_MASS',I_A);
In the macros AGEN, ACDEF, AGET, ANAL, ASET, and AC defined by
$MACROS.PLI, the parameter C_ANALYZER is interpreted as a
character string directly.
==> ANAL(A_MASS,I_A);
Macros and procedures for any user-supplied program
provided by %INCLUDE '\FRSTOOLS\TRI\SATAN\$EXTENSIONS.PLI';
R6 = PRN; [RETURNS(DEC FLOAT(6))]
uniform random generator (between 0 and 1)
R6 = PGAUSS(R6_mean,R6_sigma); [RETURNS(DEC FLOAT(6))]
Gaussian random generator
R6 = PEXP(R6_tau); [RETURNS(DEC FLOAT(6))]
exponential random generator
R = AGET(C_ANALYZER,I_CHANNEL1,{I_CHANNEL2});
get the content of a channel of an analyzerANAL(C_ANALYZER,I_CHANNEL1,(I_CHANNEL2)) INCR(R6_INCR);
increment the content of a channel of an analyzer by R6_INCR
or
ANAL(C_ANALYZER,I_CHANNEL1,(I_CHANNEL2)) VALUE(R6_VALUE);
set the content of a channel of an analyzer to R6_VALUE
ASET(C_ANALYZER,I_CHANNEL1,(I_CHANNEL2)) VALUE(R6_VALUE);
set the content of a channel of an analyzer to R6_VALUE
(ASET(..) VALUE(..) is identical to ANAL(..) VALUE(..)
EXCMD(C_COMMAND);
excecute a SATAN command
Ixx = $FIXED(value,xx);
convert any value of a any numeric variable into BIN FIXED(xx)
format
(xx = 7, 15 or 31 are supported;
the conversion is protected against FIXEDOVERFLOW)
R6 = $IPARVAL(CV_name);
get value of the dynamic parameter CV_name
CALL $PROMPT(CV,any);
prompt a variable
CALL $PROMPTO(CV,any);
propose and prompt a variable
"any" may be DEC FLOAT(6),
DEC FLOAT(15),
BIN FIXED(15),
BIN FIXED(31),
(*) DEC FLOAT(6),
(*) DEC FLOAT(15),
(*) BIN FIXED(15),
(*) BIN FIXED(31),
BIT(1) ALIGNED.
Macros and procedures for the analysis of list-mode data:
provided by %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI'; General remarks for syntax and use of macros:
Macros are specified with positional and keyword arguments.
In "AGEN(TEST) LIMITS(1,100)", TEST is a positional argument,
"1,100" is a keyword argument with the keyword "LIMITS".
Positional arguments must appear in sequence, keyword arguments may
appear in any order.
The macros given below may only be used in the user-supplied
analysis procedure! The language-sensitive editor provided with the PL/I compiler
for WINDOWS can be modified to recognize the SATAN macros
(see HELP MSWINDOWS). However, for this purpose the macros have
to be used without a leading "$" sign! The compiler supports
both versions. LISTPROC;
begin of analysis program DEBUG;
activate debug option LIST(p1,p2,p3,p4, ...);
list a series of numerical variables (integer or real) and text.
p1,p2,... may be a numerical variable, a text variable or a text.
==> LIST('Program Version: ',i_version);
-----------------------------------------------------------------------
| Syntax of LIST (list character strings and numerical variables)
| Positional arguments: numerical variable {BIN FIXED(15),
| BIN FIXED(31), DEC FLOAT(6), DEC FLOAT(15)}, CHAR(x) VAR, text.
----------------------------------------------------------------------- PARDCL(SLOPE) INIT(8.79) COMMENT('SLOPE OF TIME CALIBRATION');
PARDCL(A0,A1) INIT('0.5,27.3') COMMENT('SHIFT,FACTOR');
PARDCL(X(5)) INIT('7,3,5,9,3.5') COMMENT('X-ARRAY');
declare global parameters
-----------------------------------------------------------------------
| Syntax of PARDCL (only DEC FLOAT(6) data type; 1-dim arrays
| or a list of variable names supported)
| 1. argument: variable name(s),
| ==> "PARDCL(SLOPE)" defines one parameter,
| ==> "PARDCL(OFFSET,SLOPE)" defines two parameter,
| ==> "PARDCL(OFFS(3))" defines an array of 3 parameter,
| ==> "PARDCL(OFFS(-2:3))" defines an array of 6 parameter,
| INIT keyword: value (optional; default = 0),
| COMMENT keyword: comment (optional; default = '').
| For arrays, the INIT and COMMENT keywords are assigned to the
| different elements in sequence. Missing values are
| repeated from the last given value.
| For a list of variable names, the INIT and COMMENT keywords may
| contain a list of names.
| Arrays and lists of variables cannot be mixed in one PARDCL.
| PARDCL appears in the analysis routine. A global parameter may
| be used in the analysis routine like a normal variable declared
| by DECLARE "name" DEC FLOAT(6) STATIC INIT(..); .*/
----------------------------------------------------------------------- AGEN(C_ANALYZER) TYPE(C_TYPE) LIMITS(x1,x2{,y1,y2}) BINS(bx{,by})
NCND(I) CXAXIS(C) CYAXIS(C) TITLE(C) COMMENT(C) FCAL(r1{,r2})
LINESYMBOL(C);
generate an analyzer or an array of analyzers
(Arrays of analyzers up to 5 dimensions are supported.)
-----------------------------------------------------------------------
| Syntax of AGEN (1-dimensional analyzer)
| 1. argument: analyzer name or array of analyzer names,
| ==> "AGEN(MUSIC)" defines one analyzer,
| ==> "AGEN(ATAR(3))" defines an array of three analyzers,
| ==> "AGEN(Z_RESPONSE(80:92))" defines an array of 13
| analyzers.
| ==> "AGEN(TEST(5:9,27:37))" defines a 2-dim. array of
| analyzers.
| TYPE keyword: FIXED or FLOAT (optional; default = FIXED),
| and PROTECTED (against ACLR)
| ==> "AGEN(TEST) TYPE(FLOAT,PROTECTED)"
| MODE keyword: ANALOG or DIGITAL (optional; default = ANALOG),
| LIMITS keyword: list of limits (2 values),
| BINS keyword: binsize (optional; default = 1),
| NCND keyword: number of conditions (optional; default = 0),
| CXAXIS keyword: description of x axis (optional; default =
| Channel),
| CYAXIS keyword: description of y axis (optional; default =
| Counts),
| TITLE keyword: title of analyzer (optional; default =
| analyzer name),
| COMMENT keyword: comment of analyzer (optional; default = '').
| FCAL keyword: calibration factor.
| LINESYMBOL keyword: line and symbol (==> LTR11 , default is HT0)
| In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
| element number of an array of analyzers.
-----------------------------------------------------------------------
| Syntax of AGEN (2-dimensional analyzer)
| 1. argument: analyzer name or array of analyzer names
| (see above),
| TYPE keyword: FIXED or FLOAT (optional; default = FIXED),
| and PROTECTED (against ACLR)
| ==> "AGEN(TEST) TYPE(FLOAT,PROTECTED)"
| LIMITS keyword: list of limits (4 values),
| BINS keyword: binsizes (optional; default = 1,1),
| NCND keyword: number of conditions (optional, default = 0),
| CXAXIS keyword: description of x axis (optional; default =
| Dimension 1),
| CYAXIS keyword: description of y axis (optional; default =
| Dimension 2),
| TITLE keyword: title of analyzer (optional; default =
| analyzer name),
| COMMENT keyword: comment of analyzer (optional; default = '').
| FCAL keyword: calibration factors.
| In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
| element number of an array of analyzers.
----------------------------------------------------------------------- ACDEF(C_ANALYZER,I_CONDITION) ID(C) LIMITS(x1,x2{,y1,y2});
define name (ID) and limits of condition SCAN GOOREAD(I1)
{TIMESTAMP, PATTERN(IP), SCALERS(IS), ADC(IA), TDC(IT), QDC(IQ)}
SLOT(IS);
attribute data channels on VME slots to GOOREAD data arrays
-----------------------------------------------------------------------
|The SCAN macro is only needed for data format VMEFRS (see macro EVENT).
| Syntax of SCAN
| One SCAN macro refers to one slot of the VME crate.
| The SCAN macro must appear before the ANTRY macro in the
| declaration part of the user analysis programme.
| GOOREAD keyword: defines to which GOOREAD macro the actual SCAN
| macro refers. (First GOOREAD: I1 = 1, second GOOREAD: I1 = 2 ...)
| (Instead of GOOREAD, also CONTROL or PROCID of the
| corresponding subevent may be specified.)
| TIMESTAMP, PATTERN, SCALERS, ADC, TDC, QDC keywords:
| One of these keywords defines the kind and the number of data
| in the corresponding VME slot.
| SLOT keyword: denotes the slot of the VME crate.
| (GEO is also accepted as an alias for SLOT.)
----------------------------------------------------------------------- ANTRY;
end of declaration part of analyzer program
EVENT DATA(I1,I2,I3,...) FORMAT({FIXED,FLOAT,GOOSY,ASCII,CAMDA,..});
begin of event loop
-----------------------------------------------------------------------
| EVENT defines the names and the nature of the list-mode data.
| Syntax of EVENT:
| DATA keyword defines the names of the event variables
| (e.g. DATA(IA(3),I4,IB(20)) defines 24 event variables.)
| The event variables are already declared by the EVENT macro.
| FORMAT keyword defines the nature of the list-mode data
| FIXED: standard SATAN format, 2 byte integers (= default),
| FIXED LONG: SATAN format, 4 byte integers (= default),
| FLOAT: SATAN format, 4 byte reals,
| FLOAT LONG: SATAN format, 8 byte reals,
| GOOSY: data in GOOSY format
| (needs additional macros GOOREAD, see HELP GOOSYDATA)
| The data are available as BIN FIXED(31) variables
| (4-byte integers) in the analysis procedure.
| FRS2003: FRS standard data format.
| (A special GOOSY format, containing a time stamp,
| bit pattern, unpacked 32-bit scaler data and packed
| 16 bit ADC data. See HELP GOOSYDATA for details)
| VMEFRS: FRS data format for VME crates.
| (A special GOOSY format, containing a time stamp,
| bit pattern, unpacked 32-bit scaler data and packed
| 16 bit ADC data. See HELP GOOSYDATA for details)
| ASCII: data in ASCII format, numbers may be integers or
| reals, divided by at least one blank.
| The data are available as DEC FLOAT(6) variables
| (4-byte reals) in the analysis procedure.
| One or more events per line are allowed.
| Lines beginning with * are considered as comment lines.
| IN2P3: Standard data format of IN2P3 (France). Presently,
| only EVENTD and EVENTDB data types of 2-byte integers
| with WORDC (word-count) structure and a record size of
| 16384 bytes are supported. The number of variables provided
| in the EVENT DATA macro is not critical for synchronizing
| consecutive events, since the length of each event is coded
| in the WORDC value. However, EVENT parameters exceeding the
| number of input parameter have unpredictable values!
| The first two EVENT parameters contain the total number of
| parameters read in the actual event (= WORDC value) and the
| running event number.
| CAMDA: CAMDA data format
| Records of 2048 bytes length
| 1. record: 5 bytes: M1 (ASCII)
| M1 bytes: CAMC list file
| 5 bytes: M2 (ASCII)
| M2 bytes: comment
| 5 bytes: number of parameters per event
| 5 bytes: total # of parameters (not relevant)
| 5 bytes: number of events per record
| 6 bytes: number of histogramm channels
| 8 bytes: date
| 8 bytes: time
| Following records: Data (2-byte numbers)
-----------------------------------------------------------------------
ANAL(C_ANALYZER,I_CHANNEL1{,I_CHANNEL2}) INCR(amount of increment);
accumulate into an analyzer (INCR(1) can be omitted)
or
ANAL(C_ANALYZER,I_CHANNEL1{,I_CHANNEL2}) VALUE(value to set);
fill a value into an analyzer
-----------------------------------------------------------------------
| Syntax of ANAL (for 1-dimensional analyzer)
| 1. argument: analyzer name,
| 2. argument: channel number,
| INCR keyword: increment (optional; default = 1) or
| VALUE keyword: set value (INCR and VALUE are exclusive).
| Analyzers used in ANAL must be created by the macro AGEN.
-----------------------------------------------------------------------
| Syntax of ANAL (for 2-dimensional analyzer)
| 1. argument: analyzer name,
| 2. argument: channel number 1. dimension,
| 3. argument: channel number 2. dimension,
| INCR keyword: increment (optional; default = 1) or
| VALUE keyword: set value (INCR and VALUE are exclusive).
| The value of the INCR() or VALUE() parameter may be any real
| number.
| Analyzers used in ANAL must be created by the macro AGEN.
|---------------------------------------------------------------------- AGET(C_ANALYZER,I_CHANNEL1,{I_CHANNEL2}); [RETURNS(DEC FLOAT(15))]
get the content of a channel of an analyzer
(For analog-type analyzers:
If the channel does (resp. the channels do) not coincide with the
lower limit of a bin, an interpolated value is returned. Zero is
returned for channel numbers outside the range of the analyzer
limits.)
-----------------------------------------------------------------------
| Syntax of AGET (for 1-dimensional analyzer)
| 1. argument: analyzer name,
| 2. argument: channel number,
| AGET returns the content of the analyzer channel.
| Analyzers used in AGET must have been created by AGEN.
-----------------------------------------------------------------------
| Syntax of AGET (for 2-dimensional analyzer)
| 1. argument: analyzer name,
| 2. argument: channel number 1. dimension,
| 3. argument: channel number 2. dimension,
| AGET returns the content of the analyzer channel.
| Analyzers used in AGET must have been created by AGEN.
----------------------------------------------------------------------- AC(C_ANALYZER,I_CONDITION); [RETURNS(BIT(1))]
check the condition of an analyzer
-----------------------------------------------------------------------
| Syntax of AC (for 1-dim. and 2-dim. analyzers)
| 1. argument: analyzer name,
| 2. argument: condition number or condition ID.
| (character string or variable beginning with "C"
| is interpreted as condition ID, number or any
| other variable is interpreted as condition
| number)
| ==> "IF AC(TOF,3) THEN ..." condition number
| ==> "IF AC(TOF,I_WIN) THEN ..." condition number
| ==> "IF AC(TOF,'FRAGMENTS') THEN ..." condition ID
| ==> "IF AC(TOF,C_FIRST) THEN ..." condition ID
| AC yields always true for conditions which are not set (= open)!
| AC yields always false for conditions which are closed.
----------------------------------------------------------------------- EXCMD(C_COMMAND);
execute a SATAN command
-----------------------------------------------------------------------
| Syntax of EXCMD
| One positional argument: command text.
| ==> EXCMD('HALT');
----------------------------------------------------------------------- In the following the following conventions are used:
I15 = BIN FIXED(15), I31 = BIN FIXED(31),
R6 = DEC FLOAT(6), R15 = DEC FLOAT(15),
CV = CHARACTER VARYING. LOUT DATA(array) N(number) DSN(output dataset) FORMAT(format);
write list-mode data on file
-----------------------------------------------------------------------
| Syntax of LOUT
| DATA keyword: array of data elements to be written
| (The data array may be I15, I31, R6 or R15.)
| N keyword: number of data elements to be written
| DSN keyword: dataset name for output (optional)
| (The dataset may also be specified by the command LOUTPUT.)
| FORMAT keyword: output formats ( E(x,y) and F(x,y) are supported )
| (If the FORMAT keyword is specified, the data are written in
| ASCII format. Otherwise, the data are written in SATAN format.)
-----------------------------------------------------------------------
R15 = $2FIX16FLOL(I15_low,I15_high); [RETURNS(DEC FLOAT(15))]
combine and convert two unsigned 16-bit numbers provided in
two BIN FIXED(15) variables to one DEC FLOAT(15) variable. R15 = $2FIXL24FLOL(I31_low,I31_high); [RETURNS(DEC FLOAT(15))]
combine and convert two unsigned 24-bit numbers provided in
two BIN FIXED(31) variables to one DEC FLOAT(15) variable. R15 = $2FIXL16FLOL(I31_low,I31_high); [RETURNS(DEC FLOAT(15))]
combine and convert two unsigned 16-bit numbers provided in
two BIN FIXED(31) variables to one DEC FLOAT(15) variable. Ixx = $FIXED(value,xx);
convert any value of a any numeric variable into BIN FIXED(xx)
format
(xx = 7, 15 or 31 are supported;
the conversion is protected against FIXEDOVERFLOW) I31 = NEVENT;
event counter
(Value is 1 for the first event after INPUT, ICONNECT or START.) ENDEVT;
end of event loop CONDITION_CHECK();
check on unused conditions (must be placed directly after ENDEVT)
(Unused conditions make unnecessary long object codes and increase
the analysis time.) ENDANL;
end of analysis program Special macros for Monte-Carlo simulations:
provided by %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
START;
entry for START command
LOOP; /* or LOOP(N); for loop over N events */
event loop
R6 = PRN; [RETURNS(DEC FLOAT(6))]
uniform random generator (between 0 and 1)
R6 = PGAUSS(R6_mean,R6_sigma); [RETURNS(DEC FLOAT(6))]
Gaussian random generator
Provides events according to the distribution
f(x) = norm. * exp(-(x-R6_mean)**2/(2*R6_sigma**2))
R6 = PEXP(R6_tau); [RETURNS(DEC FLOAT(6))]
exponential random generator
Provides events according to the distribution
f(x) = 1 / ABS(R6_tau) * exp(- x / R6_tau)
in the range [0 <= x <= +infinity] for R6_tau > 0 and
in the range [-infinity <= x <= 0] for R6_tau < 0.
R6 = PMAXWELL(R6_T); [RETURNS(DEC FLOAT(6))]
Maxwellian random generator
Provides events according to the distribution
f(x) = norm. * x * (exp - x/R6_T)
in the range 0 <= x <= + infinity. R6_T must be > 0.
Algorithm (exact): R6 = -R6_T * (LOG(PRN) + LOG(PRN)) R6 = PGAUSSTAIL(R6_mean,R6_sigma,R6_tau) [RETURNS(DEC FLOAT(6))]
random generator of Gaussian (PGAUSS(R6_mean-R6Tau,R6_sigma))
f1(x) = norm. * exp(-(x-R6_mean+R6_tau)**2/(2*R6_sigma**2))
convoluted with an exponential (PEXP(R6_tau))
f2(x) = 1 / ABS(R6_tau) * exp(- x / R6_tau).
R6_mean is the mean value of the convoluted function.
R6_sigma is the standard deviation of the Gaussian.
R6_tau is the decay constant of the exponential.
R6_tau > 0: The function has a tail to positive x values.
R6_tau < 0: The function has a tail to negative x values.
NEXT;
end of event loop
Additional procedures:
R6 = $IPARVAL(CV_name);
get value of the dynamic parameter CV (Normally not necessary in
the analysis procedure, there ,the dynamic parameter is
directly accessible as a variable.)
Declaration: DCL $IPARVAL ENTRY(CHAR(*) VAR) RETURNS(DEC FLOAT(6));
CALL $PRTCL(CV,I15);
list character string
on protocol and screen (I15 = 1)
on screen only (I15 = 11)
on screen without linefeed (I15 = 12)
on protocol only (I15 = 0)
Declaration: DCL $PRTCL ENTRY(CHAR(*) VAR, BIN FIXED(15));
CALL $PROMPT(CV,any);
prompt a variable
CALL $PROMPTO(CV,any);
propose and prompt a variable
any may be DEC FLOAT(6),
DEC FLOAT(15),
BIN FIXED(15),
BIN FIXED(31),
(*) DEC FLOAT(6),
(*) DEC FLOAT(15),
(*) BIN FIXED(15),
(*) BIN FIXED(31),
BIT(1) ALIGNED.
CV256 = GEDIT(R15,Cformat)
transform a DEC FLOAT(15) number into a character string with a
format defined by Cformat
==> CV256 = GEDIT(R15,'F9,3'); gives 9 digits with 3 digits
behind the decimal point.
Declaration: DCL GPEDIT ENTRY(DEC FLOAT(15), CHAR(*) VAR)
RETURNS(CHAR(256) VAR);
CV256 = GPEDIT(R15,I15)
transform a DEC FLOAT(15) number into a character string with given
precision. The length of the characterstring is variable.
Declaration: DCL GPEDIT ENTRY(DEC FLOAT(15), BIN FIXED(15))
RETURNS(CHAR(256) VAR);
CV256 = GPEDFL(R15,I15)
transform a DEC FLOAT(15) number into a character string with
minimum length I15.
Declaration: DCL GPEDFL ENTRY(DEC FLOAT(15), BIN FIXED(15))
RETURNS(CHAR(256) VAR);
-----------------------------------------------
See "HELP GOOSYDATA" for macros needed for reading GOOSY (MBS) data.
|
