SATAN User plug-ins and extensions

NOTE: the features described here are not yet available.

At several points it is possible for a user to define own extensions to the SATAN system. He/she may define additional commands or provide function plug-ins for certain standard tasks.

Commands

For interactive usage of special applications or for functions not yet implemented, the user may write his own commands and add them to the system.

Command definitions

Definition of a command is done by the procedures $CMDDEF (resident commands) or $CMDFET (fetchable commands) which must be called anywhere in the initialization part of the analysis program. Alternatively, fetchable commands may be defined within the SATAN session by the command $CMDFET. Two arguments are passed:
  1. String consisting of Each name may be followed by an argument containing attribute keywords which define
  2. The entry to the command procedure which is called by the command decoder each time the corresponding command is typed in. The parameters entered following the command name (or their default values) are passed to the entry via a parameter list; a 1:1 correspondence is maintained between the parameters defined in the command string and those in the parameter list of the specified entry.
For a detailed description see procedure $CMDDEF. There are three ways to add the routine to the system when starting it with the TSO command SATAN:

Example for a resident command processor

Definition

$INITPROC; DCL AOVER ENTRY(CHAR(18) VAR, CHAR(18) VAR); CALL $CMDDEF('OVERLAY | ANLID(T(18)) EVTID(T(18) R(LIST))',AOVER); END;
The command 'OVERLAY' is declared with the two optional positional parameters 'analyzer identifier' and 'event type identifier', both character strings of 18 bytes maximum length. Replaceable default for the event type is 'LIST'.

Command processor

AOVER: PROCEDURE(CANLID,CEVTID); /* command to add the first half of an analyzer to the second half */ %INCLUDE $MACRO($ANLFET), /* declarations of entries */ $MACRO($PROENT); DECLARE CEVTID CHAR(18) VAR, /* event name */ CANLID CHAR(18) VAR, /* analyzer name */ IEVTID BIN FIXED, /* event number */ IANLID BIN FIXED, /* analyzer number */ ICND BIN FIXED, /* number of conditions */ IDIM BIN FIXED, /* number of dimensions */ ILIM(4,4) BIN FIXED, /* analyzer limits */ ITYPE BIN FIXED, /* analyzer type */ IL BIN FIXED, /* upper limit (temporary) */ IRC BIN FIXED, /* return code */ (I,J) BIN FIXED; /* loop variables */ ; IEVTID,IANLID = 0; /* force use of names */ $LFETCH($ACHECK);; /* get analyzer limits */ CALL $ACHECK(CEVTID,IEVTID,CANLID,IANLID,ITYPE,ICND,IDIM,ILIM,IRC); IF IRC^=0 THEN DO; /* errors? */ CALL $PRTCL('ERROR CHECKING '||CANLID||' '||CEVTID|| ', RETURNCODE IS'||CHAR(IRC),1); RETURN; END; IF IDIM^=1 THEN DO; /* more than 1 dimension? */ CALL $PRTCL('ANALYZER IS NOT ONE-DIMENSIONAL',1); RETURN; END; IL = ILIM(1,4); /* upper bound of work array */ ; ABEGIN: BEGIN; DECLARE SPEC(IL) BIN FIXED(31); /* allocate spectrum work array */ ; $LFETCH($AGTSPC);; /* fetch the spectrum */ CALL $AGTSPC(IEVTID,IANLID,ILIM,SPEC,0,IRC); IF IRC^=0 THEN DO; CALL $PRTCL('ERROR FETCHING SPECTRUM. RETURNCODE ='||CHAR(IRC),1); RETURN; END; J = 0; DO I=IL/2+1 TO IL; /* loop over channels */ J = J + 1; SPEC(I) = SPEC(I) + SPEC(J); END; $LFETCH($ASTSPC);; /* store processed spectrum */ CALL $ASTSPC(IEVTID,IANLID,ILIM,SPEC,0,IRC); IF IRC^=0 THEN CALL $PRTCL('ERROR STORING SPECTRUM, RETURNCODE ='||CHAR(IRC),1); END ABEGIN; RETURN; END AOVER;

Example for a fetchable (dynamically loaded) command processor

Creating Here are some rules
  1. The data attribute 'CONTROLLED' is not allowed. Instead, the usage of 'BEGIN' blocks or 'BASED' allocation of storage is recommended.
  2. For data which have to be kept, the attribute 'STATIC' must be replaced by 'EXTERNAL'.
  3. FILES, resident ENTRY names and EXTERNAL variables must be defined in 'root groups'.

Calling Before calling a module, it has to be loaded and the entry point must be provided. A fetchable module is loaded into storage by its name, which must be identical with a member name or alias in a partitioned data set ('fetch library'). If this module is not yet in storage, the dynamic load service is called, which returns its entry point (PL/I entry variable) on successful termination. Fetchable modules may
Accessing resident information To access resident information a ROOT GROUP must be defined. The root group which is a collection of resident elements, such as PL/I externals, PL/I files or entry points to PL/I procedures, is identified by a unique name. A fetchable module which has to access these items must also declare elements and name of the root group. To get the addresses of the resident information an interface procedure is called via the macro $LROOT.
Calling program: In the calling program, the fetchable module is declared as VARIABLE ENTRY and loaded by the macro $LFETCH.

DECLARE MYFETCH VARIABLE ENTRY(...) INIT($LTDMY); ... $LFETCH(MYFETCH); CALL MYFETCH(...); ...
Fetchable program: Assume, the fetchable module shall access the external pointer P, the external structure S, the file F and the resident procedures MYENTRY and $PRTCL. The following declarations have to be coded:

MYFETCH: PROC(...); %INCLUDE $MACRO(@LFETCH); DCL $LEXT(P,USER) POINTER, 1 $LEXT(S,USER), 2 C_ID CHAR(20) VAR INIT('MY_COUNTER'), 2 L BIN FIXED(31) INIT(0), $LENTRY(MYENTRY,USER) (CHAR(*) VAR,BIN FIXED), $LENTRY($PRTCL,USER) (CHAR(*) VAR,BIN FIXED), $LFILE(F,USER); $LROOT(USER) EXT(P,S) ENTRY(MYENTRY,$PRTCL) FILE(F);; ... CALL $PRTCL(C_ID ||' = '||L,1); ... END MYFETCH;
Resident root definition: Resident elements and root groups used by the fetchable module must be declared in a resident program, too. However, in this case the macro @LBASE instead of @LFETCH is required to resolve the code.

%INCLUDE $MACRO(@LBASE); DCL $LEXT(P,USER) POINTER, 1 $LEXT(S,USER), 2 C_ID CHAR(20) VAR INIT('MY_COUNTER'), 2 L BIN FIXED(31) INIT(0), $LENTRY(MYENTRY,USER) (CHAR(*) VAR,BIN FIXED), $LENTRY($PRTCL,USER) (CHAR(*) VAR,BIN FIXED), $LFILE(F,USER); ... $LROOT(USER) EXT(P,S) ENTRY(MYENTRY,$PRTCL) FILE(F);;

Functions

Here's a correspondence of SATAN commands, invoked functions and purpose
Command Function Purpose

        $INIT    command definitions (no analysis)
GO      $MYGO    start data input
HALT    $MYHALT  stop data input
EXIT    $MYEXIT  leave SATAN
INPUT   $MYINP   allocate and start input
MFO28   $MYFORM  convert external raw data format

Valid HTML 3.2!

Last updated: M.Kraemer@gsi.de, 9-Jun-1999