Messages are normally output via SYSOUT to the terminal or a temporary spoolout file. The software product SDF-P offers the additional option of outputting guaranteed messages in structured S variables (see section "Guaranteed messages"). SDF-P assumes control of the S variable stream SYSMSG, by means of which the guaranteed messages are diverted to S variables. More detailed information can be found in the “SDF-P” manual [45].
The system component MIP creates the S variables whose values can be used as input data in S procedures.
The figure below shows both the output to SYSOUT by the system file manager and the diversion of the output information to the S variable streams SYSMSG (and SYSINF) controlled by SDF-P. Further information on SYSINF can be found in the “Commands” manual [27].
Figure 25: Output of messages to the S variables stream SYSMSG and to SYSOUT
The use of S variables offers users considerable advantages:
The S variables permit simple access to the messages because the information is stored in structured format. The output layout of the message is immaterial for the user.
The S variable name and the allocation of its contents are also guaranteed to remain the same in future subsystem versions or versions of BS2000 OSD/BC.
The contents of the S variable can be used as input in S procedures.
The following entries are necessary in order to output guaranteed messages in structured S variables:
The user must declare a list variable of the type structure.
/DECLARE-VARIABLE <var-name>(TYPE=*STRUCTURE),MULTIPLE-ELEMENT=*LISTThe user must assign the S variable stream SYSMSG for the structured output in S variables. One of the following declarations must be made:
At command level:
The EXECUTE-CMD command declares the structured output in S variables for a command.
/EXEC-CMD (<cmd-name>),MSG-STRUCTURE-OUTPUT=<var-name>The ASSIGN-STREAM command; the assignment of the S variable stream applies to all subsequent commands until the declaration is retracted
(ASSIGN-STREAM SYSMSG,TO=*STD).
/ASSIGN-STREAM STREAM-NAME=SYSMSG,TO=*VARIABLE(<var-name>)
At program level:
The CMD macro declares the structured output in S variables for two or more commands.
CMD '<cmd-name>',...,VER=4,MSGVAR@=<adr>,MSGVARL=<len>,[,MSGEXT=YES]<addr>is the symbolic address contained in the S variable name.
CMD macro, see the “Executive Macros” manual [30].The destination of the message output must be declared in the MSG7X macro. If DESTINATION=SYSOUT is specified, guaranteed messages will always be output in S variables, provided the user has declared an S variable.
In addition, the BUFFER operand can be assigned a user-specific memory and BUFFUSE=EXTERNAL.
MSG7X macro, see the “Executive Macros” manual [30].The message must be identified as follows by MSGMAKER:
The message to be output must be identified as guaranteed (//ADD-MSG MSG-ID=...,WARRANTY=YES). MIP creates the following S variables for warranty messages (guaranteed messages):
MSG-ID:
contains the message codeREPLY:
contains the reply to the message, if it requires a reply from the user.I0 through I29:
default names of the inserts; by default MIP allocates I0 through I29 as S variable names if the user declares no insert names using MSGMAKER (see b)).MSG-TEXT:
contains the message text including all replaced inserts.
Names are declared for the inserts of the message to be output (//ADD-MSG MSG-ID=...,INSERT-ATTRIBUTES=...(NAME=...)). If the message is not guaranteed and a name is nevertheless assigned to at least one insert of the message to be output, the following S variables are created:
<insert-name>:
name declared with MSGMAKER is converted to uppercase and used by MIP as S variable nameMSG-ID:
contains the message codeREPLY:
contains the reply to a message.MSG-TEXT:
contains the message text including all replaced inserts.
The S variables created by MIP are of the data type STRING.
The final S variable output by MIP is made up of two names:
Name of the variable declared by the user: <var-name> (<var-name> is the first part of the S variable name)
MIP supplies the second part of the name (MSG-ID, I0 to I29, <insert-name>, REPLY, MSG-TEXT)
Together the two parts of the name, separated by a period, make up the S variable name
<var-name>.MSG-ID
<var-name>.I0 ... <var-name>.I29
<var-name>.<insert-name>
<var-name>.REPLY
<var-name>.MSG-TEXT
All the variables (MSG-ID, I0, ...) that exist for a warranty message are part of one list element. Any other message is included as a new list element. This applies when there are several warranty messages for one command (the command is called by means of EXECUTE-CMD) or the output of warranty messages is diverted to an S variable by the /ASSIGN-STREAM command.
Example
The example below illustrates how a message output is diverted to an S variable. The attributes of the file called TEST are to be output, but there is no corresponding file. Error message DMS0533 is a warranty message and is output in the S variable MSG:
/DECLARE-VARIABLE NAME=MSG(TYPE=*STRUCTURE(DEFINITION=*DYNAMIC)), MULTIPLE-ELEMENTS=*LIST 1. /EXECUTE-CMD CMD=(SHOW-FILE-ATTRIBUTES FILE-NAME=TEST),TEXT-OUTPUT=*NONE, MSG-STRUCTURE-OUTPUT=MSG(WRITE-MODE=*EXTEND) 2. /SHOW-VAR MSG 3. MSG(*LIST).MSG-TEXT = % DMS0533 REQUESTED FILE NOT CATALOGED IN PUBSET '1SBZ'. COMMAND TERMINATED MSG(*LIST).MSG-ID = DMS0533 MSG(*LIST).I0 = 1SBZ 4.
The S variable MSG is declared as a list variable that can be dynamically extended.
The output of the SHOW-FILE-ATTRIBUTES command is diverted to the S variable MSG by means of the EXECUTE-CMD command. Output to SYSOUT is suppressed.
The list variable MSG is output by means of SHOW-VAR MSG.
MIP creates the S variables MSG-TEXT, MSG-ID and I0 for this warranty message. The values of these S variables represent the first list element of the S variable MSG. If the EXECUTE-CMD command is executed again, each further message is added as a new list element because WRITE-MODE=*EXTEND is specified (see (2)).