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 which the message originated. Therefore, any type of logic that could possibly suspend the processing of a MSG rule should be performed by scheduling an OPS/REXX program to a CA OPS/MVS OSF TSO, TSL, or TSP server, as described in the chapter “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 processes a MLWTO for as many lines that make up the MLWTO. For example if you have MLWTO made up of 3 lines-primary (line 1), data line (line 2), end line (line 3)-then the primary is evaluated first, the data line second, followed by the end line.

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

1. Verify (using the OPSFLAGS display field in the OPSLOG) that the messages are truly a MLWTO. Some applications will internally issue single WTOs, making them appear as one MLWTO. For details of this field, see the discussion of the event variable MSG.FLAGS in AOF Variables Available in a MSG Rule in this chapter. Single-line WTOs will have an 8 in the first bit of this field and MLWTOs will have a 2 or a 3 in the first bit.
2. The message specifier for the )MSG rule will be that of the message ID on the primary line (first line of MLWTO). To see exactly what CA OPS/MVS sees as this message ID, display the MSGID column in the OPSLOG for the MLWTO.

   Note: The same message ID is associated for all lines of the MLWTO.

3. If you are attempting to modify the disposition of the MLWTO such as route codes, descriptor codes, or suppression, this code must be performed while the logic of the )MSG rule is processing the primary (first line) of the MLWTO. If message disposition needs to be determined by some condition in a data or end line of the MLWTO, you need to incorporate logic to suppress the rule on the primary line, save each line in variables, and then determine if the message should be reissued when the end line is processed. See the example in this section.
4. The following MSG event variables will be evaluated as noted:

   MSG.TEXT

   Populated with the complete message text of the line that is currently being processed. This means that, as the primary is being processed, MSG.TEXT would be that of the primary, as the second line is being processed, MSG.TEXT would be that of the second line text, and so on.

   MSG.OMAJORTEXT

   Contains the contents of the primary line regardless of what line is being processed.

   MSG.OTEXT

   Contains the complete text of secondary lines (data and end lines, NO primary). This means that, because the primary line is processed first, MSG.OTEXT will be null. As the second line (data line) is being processed MSG.OTEXT will contain the text of the second line.

   Suppose you have the following VTAM MLWTO message:

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

   Using this test rule:

   )MSG IST663I
   )PROC
   say '**TEXT='MSG.TEXT 
   say '**OMAJ='MSG.OMAJORTEXT 
   say '**OTEXT='MSG.OTEXT
   

   Primary line (IST663I CDINIT REQUEST FROM....) is processed, producing:

   **TEXT=IST663I CDINIT REQUEST FROM A55X99 FAILED, SENSE=08570002
   **OMAJ=IST663I CDINIT REQUEST FROM A55X99 FAILED, SENSE=08570002
   **OTEXT=
   

   Secondary line (IST664I REAL OLU=USILDA02....) is processed, producing:

   **TEXT=IST664I REAL OLU=USILDA02.A13IOML0 REAL DLU=USILDA01
   **OMAJ=IST663I CDINIT REQUEST FROM A55X99 FAILED, SENSE=08570002
   **OTEXT=IST664I REAL OLU=USILDA02.A13IOML0 REAL DLU=USILDA01 
   

   End line (IST314I END) is processed, producing:

   **TEXT=IST314I END
   **OMAJ=IST663I CDINIT REQUEST FROM A55X99 FAILED, SENSE=08570002
   **OTEXT=IST314I END
   

5. Logic is usually needed to see what line you are on (for example, the primary or a data line). You can do this by either looking for some particular text in the MSG.TEXT or interrogating the MSG.FLAGS and MSG.MLWTOMIN variables. For example:

   if MSG.MLWTOMIN = 0 then....        /* 0 = primary 1 = data lines */
   if WORD(MSG.TEXT,1) = 'IST314I'.    /* this is part of end line */
   if BITAND(MSG.FLAGS,'0600'X) = '0600'X  /* must be end-line     */
   

6. Logic is usually needed to correlate data between the primary and data lines for MLWTOs. For example, you may want to extract the third word of the primary line and, based on the second word of the end line, make a decision. You can do this by storing your retained information in unique temporary variables, as noted in Examples of MSG Rules in this chapter. For a template for creating an AOF MSG rule that processes a MLWTO Message, see the sample rule member MLWTO of the hlq.SAMPLE.RULES data set.