S variable stream mechanism (SYSINF, SYSMSG and SYSVAR)

SDF-P supports a mechanism known as “streams for structured variables” (henceforth referred to as S variable streams). S variable streams are an alternative or a supplement to output in system files. SDF-P is responsible for controlling the S variable streams. By default, the operating system supplies three S variable streams: SYSINF, SYSMSG and SYSVAR. If necessary, users can also declare and name their own S variable streams.

The SYSINF, SYSMSG and SYSVAR S variable streams

SYSINF:	Structured output from commands and programs is passed to the assigned S variables.
SYSMSG:	Guaranteed messages are passed to the assigned S variables in structured output format.
SYSVAR:	Both structured command and program output and guaranteed messages are passed to the assigned S variables. SYSVAR subsumes SYSINF and SYSMSG.

For further information on S variable streams refer to the “SDF-P” manual [34].

The following diagram illustrates both output to SYSOUT by the system file manager and redirection of output information to the SYSINF and SYSMSG S variable streams under the control of SDF-P.

Command and program output to the SYSINF and SYSMSG S variable streams or to SYSOUT

SYSINF

Working with S variables generated in the structured output of specific SHOW commands is discussed in detail in section "Declaring S variables" and the following subsections, starting on.

SYSMSG

The format and contents of the S variables generated for guaranteed messages by the system component MIP are briefly discussed here. For further information on the subject refer to the “Introduction to System Administration” manual [14].

SDF-P is responsible for controlling the SYSMSG S variable stream, which serves to redirect guaranteed messages to S variables. In guaranteed messages, the message ID and the numbering and meaning of the inserts are constant message components.

The following actions are required in order for guaranteed messages to be output in a structured S variable:

1. The user must declare a list variable of type STRUCTURE.

   /DECLARE-VARIABLE VAR-NAME=<var-name>(TYP=*STRUCTURE),
                  MULTIPLE-ELEMENT=*LIST

2. The user must assign the SYSMSG S variable stream for structured output in S variables. One of the following declarations is required:

   On command level:

   1. Using the EXECUTE-CMD command: structured output in S variables is declared for one command.

      /EXEC-CMD (<cmd-name>),MSG-STRUCTURE-OUTPUT=<var-name>

   2. Using the ASSIGN-STREAM command: the assignment of the S variable stream remains valid for all subsequent commands until it is explicitly canceled (ASSIGN-STREAM SYSMSG,TO=*STD).

      /ASSIGN-STREAM STREAM-NAME=SYSMSG,TO=*VARIABLE(<var-name>)

   On program level:

   The CMD macro declares structured output in S variables for a number of commands.

   CMD '<cmd-name>',...,VER=4,MSGVAR@=<add>,MSGVARL=<length>,[,MSGEXT=YES]

   <add> is the symbolic address of the location containing the name of the S variable. For details of the CMD macro refer to the “Executive Macros” manual [22].

3. The message output destination must be defined in the MSG7X macro. If DESTINATION=SYSOUT is specified, guaranteed messages will always be output in S variables, provided that the user has declared an S variable. In addition, the BUFFER operand can be assigned a user-specific storage area, and BUFFUSE=EXTERNAL can be assigned. On the MSG7X macro refer to the “Executive Macros” manual [22].

4. Using the MSGMAKER utility, the message must be identified as guaranteed (also refer to the “Utility Routines” manual [9]). MIP generates the following S variables for guaranteed messages:

   MSG-ID: contains the message ID.

   REPLY: contains the reply to the message if it expects an answer from the user.

   I0 through I14: default insert names; I0 through I14 are the defaults used by MIP as names for S variables. If the user defines names for inserts with the MSGMAKER utility, these names (in uppercase) are used as S variable names.

   MSG-TEXT: contains the message text inclusive of all replaced inserts.

   
   Note

   The S variables that MIP generates are of the type *ANY, the values contained are of the data type *STRING.

The completed S variable that MIP outputs is composed of the S variable name declared by the user and the S variable name generated by MIP. These two subnames, separated by a dot, form the actual name of the S variable. Each S variable that exists for a guaranteed message is associated with an element of a list. Each additional guaranteed message is incorporated as a new list element.