Enabling the IMS Commander Message Trap

This is an optional step. To enable the Message Trap function in IMS Commander on the enhanced 3270 user interface for highlighting or suppressing specific messages, you must code MSGTRAP definitions.

The MSGTRAP definitions can be coded in a new KIPIMTRP member of the RKANPARU data set for your IMS agent job. In order to allow easy migration from I/CF Trap configurations, the ICFTRAP command syntax has been retained and with the exception of the ACB() operand, which is specific to ICFTRAP, the MSGTRAP and ICFTRAP commands can be used interchangeably. For simplicity, this topic will reference using MSGTRAP other than where a distinction is to be drawn on usage.

The MSGTRAP command has two formats:
  • The first form specifies a text pattern for selecting messages to be highlighted or suppressed. :

    MSGTRAP IMSID(ims_id) TEXT(text_pat) COLOR(color)2 NOVIEW ACB(acb_name)2

    Note:

    1. The COLOR() operand can also be specified as COLOUR().

    2. Only valid with ICFTRAP command.

  • The second form is used to set default highlighting for commands, responses or messages in general:

    MSGTRAP IMSID(ims_id) MTYPE(msg_type) COLOR(color)

Where:
ims_id
The IMS ID of the IMS system from which a message must originate in order to match the MSGTRAP definition. If no IMS ID is specified, the definition will be checked against Log messages from all IMS systems. The specification can include wildcard characters as described later in this section.
text_pat
3 to 60 characters of text that must match against as many characters from an incoming IMS Log message in order for the MSGTRAP definition to apply. The specification can include wildcard characters as described later in this section. An implicit asterisk is assumed at the beginning and end of the message text specification. Neither blank spaces nor wildcard characters are acceptable as one of the first three characters of the message text specification.
color
1 or 2 characters that specify the color and optional highlighting that IMS Commander will paint Log messages that match the MSGTRAP definition. The following values are permitted: R, B, G, Y, W, P and T (respectively Red, Blue, Green, Yellow, White, Pink and Turquoise). Optionally, the color specification can include a suffix of X to indicate that the color is to be displayed with reverse-video highlighting.
acb_name
3 to 8 characters that specify an IMS ACB name from an ICFTRAP command and is allowed for compatibility only. The actual value provided will be ignored, since contextually it has no relevance to the manner in which IMS Commander operates.
msg_type
One of the following:COMMAND, RESPONSE, MESSAGE, CMD, RESP or MSG. These values are used to indicate the type of message to which an MTYPE() MSGTRAP definition applies. This type of definition is used to set default colors for the indicated message type. If no default values are provided, all messages (including commands and responses) will be displayed in turquoise unless a specific TEXT() MSGTRAP definition matches the message.
NOVIEW
Use to suppress messages that match the TEXT() MSGTRAP definitions that specify it. If specified together with COLOR(), then NOVIEW takes precedence. Additionally, if two definitions have the same text pattern, with the latter specifying NOVIEW, that second definition will override the first. A message will be issued to indicate the override has occurred.
The IMSID and TEXT values can include wildcard characters in the form of either an asterisk (*) to represent 0 or more characters, or a percent sign (%) or question mark (?) to represent a single character. Multiple consecutive asterisks will be treated as a single asterisk. Multiple consecutive percent signs and/or question marks represent the same number of characters as there are percent signs and/or question marks. Both percent signs and question marks adjacent to an asterisk will be treated as multiple adjacent asterisks. For example, the following text patterns are syntactically equivalent:
  • ‘A??*B%?’
  • ‘A*B??’

Definitions will be applied to incoming IMS Log messages from longest to shortest according to text length.

MSGTRAP definition rules

Rules for defining the MSGTRAP definitions in RKANPAR(MSGTRAP) are as follows:
  • All MSGTRAP definitions must start on a new line. One or more spaces can precede the MSGTRAP key-word, and it must be followed by one or more spaces.
  • TEXT() MSGTRAP definitions must include either COLOR() and/or NOVIEW to be deemed complete.
  • MTYPE() MSGTRAP definitions must include COLOR() to be deemed complete.
  • MSGTRAP operands can appear in any order.
  • Any characters in or after column 72 will be ignored.
  • MSGTRAP definitions may span multiple lines. It is not necessary to specify any indication of continuation since the end of one MSGTRAP definition will be indicated by the start of another or end of data. A single hyphen, + or / is acceptable as a continuation character, but it will be effectively ignored.
  • Lines that start with an asterisk are comments and will be ignored, as will lines that are entirely blank. A line containing only a continuation character will also be effectively ignored.
  • Any non-blank columns that follow a complete MSGTRAP definition (whether or not syntactically correct) will be considered erroneous.

Activating MSGTRAP Definitions

The IMS Commander Message Trap definitions in DD:RKANPAR member KIPIMTRP are processed and activated during IMS Agent start-up for active, monitored IMS Systems, and also for monitored IMS Systems started while the IMS Agent is running.

Message Trap definitions can also be reactivated while the IMS Agent is running by using IMS Commander KIPIMTREF command. When issued from an IMS Commander work-space, KIPIMTREF instructs the IMS Agent to reactivate the Message Traps for all the active IMS systems it is currently monitoring. Nominally, the following messages will be issued by the IMS Agent as the definitions for each such IMS System are processed and activated:
  • KIPILT09I MSGTRAP TERMINATION FOR imsid COMPLETED SUCCESSFULLY. nnn MSGTRAP/S DEACTIVATED
  • KIPILT00I READING MSGTRAP DEFINITIONS FOR imsid FROM DD:RKANPAR
  • KIPILT01I MSGTRAP INITIALIZATION FOR imsid COMPLETED SUCCESSFULLY. ACTIVE TRAP COUNT IS nnn

These messages are issued to the IMS Agent's JES Message log.

Examples and guidance

When defining Message Traps keep the following in mind:
  • MTYPE() Message Trap definitions will override previously defined MTYPE() definitions with the color specified. Therefore, you should define any color defaults that apply to generically specified IMS IDs before those that resolve to less generic and/or specific IMS IDs.
  • Conversely, TEXT() Message Trap definitions with the same text pattern as previously defined TEXT() definitions will not override the earlier definition unless the latter specifies NOVIEW. Therefore, you should define TEXT() definitions with more specific text patterns before those with less specific text patterns.
  • Text patterns from Message Trap definitions are processed from longest to shortest text length when scanning messages.
  • Text patterns are internally translated to upper-case, and the process of scanning messages for matching text patterns is not case sensitive.

Examples of valid TEXT() operands and resulting text patterns:


TEXT(ABC )                ‘*ABC *’
TEXT("Abc ")              ‘*ABC *’
TEXT(’abc ?’)             ‘*ABC *’
TEXT("TEXT(abc )")        ‘*TEXT(ABC )*’
Examples of invalid TEXT() operands with explanations:

TEXT(A*)                   Too short and a wild-card in first three character positions. 
TEXT(text())               Ambiguous embedded parentheses.
TEXT(My text-pattern)      Space in first three character positions.