Execution Considerations for MSG Rules

Coding Each AOF Rule Type › Message Rules › Execution Considerations for MSG Rules

Execution Considerations for MSG Rules

The processing section of a rule that responds to a message event executes in the address space from where the message originated. Therefore, any type of logic that could possibly suspend the processing of an MSG rule must be performed by scheduling an OPS/REXX program to a CA OPS/MVS OSF TSO, TSL, or TSP server. For more information, see Code and Debug AOF Rules.

MSG rules execute on both single-line messages (WTOs) and multiple line messages (MLWTOs). Single-line WTOs are processed once, meaning they enter the rule, and then exit. A )MSG rule with the MLWTO option specified executes upon the issuing of the end-line of the multiline message.

Note: While processing a multi-line message, if the MLWTO keyword is omitted, the rule logic executes for each line of the MLWTO. Meaning, that the primary line is processed first by the rule logic, and then each subsequent data line and the end-line is processed. Thus a four line multi-line message would cause the rule to execute four times.

Adhere to the following guidelines when attempting to perform automation on true MLWTOs:

Using the OPSFLAGS display field in the OPSLOG, verify that the message is a true MLWTO (primary line, data lines, end-line). Some applications internally issue multiple single WTOs, making them appear as one MLWTO. For details on this field, see the discussion of the event variable MSG.FLAGS in AOF Variables Available in an MSG Rule. Single-line WTOs have an eight in the first byte of this field and MLWTOs have a 2 or a 3 in the first byte.
Identify the complete message specifier for the )MSG rule. To see exactly what CA OPS/MVS sees as this message ID, display the MSGID column in the OPSLOG for the MLWTO. Specify the complete message ID. Wildcarding is not allowed when using the MLWTO keyword. While processing a multi-line message, if the MLWTO keyword is omitted, the rule logic executes for each line of the MLWTO. Meaning, that the primary line is processed first by the rule logic, and then each subsequent data line and the end-line is processed. Thus a four line multi-line message would cause the rule to fire four times.
```
)MSG IST663I MLWTO or )MSG IST663I MLWTO SUPPRESS 
```
Add the SUPPRESS keyword if the suppression of the MLWTO is desired.

Note: If you are attempting to modify the route or descriptor codes of a multi-line message, then this logic cannot be accomplished when specifying the MLWTO optional keyword. This is because the MLWTO keyword causes the rule to process after the end-line has been issued, and disposition alteration logic (change route or desc codes) must be performed at the time the primary line of the multi-line message is issued.

The following MSG event variables are available to manipulate multiline messages when the MLWTO optional keyword is included on the message specifier:

msg.text.0

Shows the number of lines available in the MLWTO.

msg.text.n

Text of individual lines. For example, msg.text.1 is the first line, msg.text.2 is the second line.

msg.linetype.0

Shows number of lines available in the MLWTO.

msg.linetype.n

The line type of each line in the MLWTO. For example, msg.linetype.1 is the line type of the first line, msg.linetype.2 is the line type of the second line.

C: Control line
L: Label line
D: Data line
E: End line
DE: Data and end line

Suppose you have the following VTAM multi-line message:

IST663I CDINIT REQUEST FROM A55X99 FAILED, SENSE=08570002 
IST664I REAL OLU=USILDA02.A13IOML0 REAL DLU=USILDA01 
IST314I END

Using this test rule to dump these environmental variables for this message:

)MSG IST663I MLWTO SUPPRESS
)Proc
say '**Total Number of lines in message='msg.text.0
do l = 1 to msg.text.0
say ' **Line 'l' contents =>'msg.text.l
say ' **Line type of line 'l'=>'msg.linetype.l
do w = 1 to WORDS(msg.text.l)
say ' **Word 'w 'of line 'l' =>'WORD(msg.text.l,w)
end
say ''
end

Resulting SAY output from test rule:

*Total Number of lines in message=3
**Line 1 contents =>IST663I CDINIT REQUEST
                 FROM A55X99 FAILED, SENSE=08570002
**Line type of line 1=>D
**Word 1 of line 1 =>IST663I
**Word 2 of line 1 =>CDINIT
**Word 3 of line 1 =>REQUEST
**Word 4 of line 1 =>FROM
**Word 5 of line 1 =>A55X99
**Word 6 of line 1 =>FAILED,
**Word 7 of line 1 =>SENSE=08570002

**Line 2 contents =>IST664I REAL OLU=USILDA02.A13OML0
                 REAL DLU=USILDA01
**Line type of line 2=>D
**Word 1 of line 2 =>IST664I
**Word 2 of line 2 =>REAL
**Word 3 of line 2 =>OLU=USILDA02.A13IOML0
**Word 4 of line 2 =>REAL
**Word 5 of line 2 =>DLU=USILDA01

**Line 3 contents =>IST314I END
**Line type of line 3=>DE
**Word 1 of line 3 =>IST314I
**Word 2 of line 3 =>END

If logic is needed to pass the complete contents of a multi-line message to an OPS/REXX program in order to perform asynchronous processing that cannot be performed in an MSG rule. Then the corresponding msg.text.n variables can be stored in unique GLVTEMP variables and then obtained within the OPS/REXX program. For example, writing the message to some data set. Refer to the sample rule member MLWTO of the opsmvshlq.CCLXRULS data set for specific coding details on passing the contents of a MLWTO to an OPS/REXX program.
For more information, about a specific sample rule that utilizes the MLWTO option in addition to the MLWTOx samples of the opsmvshlq.CCLXRULS library, see MSG Rules Examples.

These samples outline various coding techniques that can be used to process MLWTOs including altering message disposition.