Trap Summary (9.6)

The Trap Summary screen (9.6) displays traps of transaction abends and/or breakpoints set by all terminals in the region. Traps can be added, deleted, moved, or copied from this screen. From this screen the user can set traps for transaction breaks or abends initiated from anywhere in the CICS region. You may also set enhanced conditions that allow traps and breakpoints to only be taken when data in predefined areas, such as the Initial Task COMMAREA (ICA), specific container (CONT+containername), MQ Message Descriptor (MQMD), or MQ Message Data (MQD), matches a certain value.

To help in the identification of a specific transaction instance, sites are adding identifiers to data areas so they can identify the instance and allow it to be processed successfully. Code Debug CICS recognizes the need to trap abends or take breakpoints when transaction-specific data is present and has added an Enhanced Trap facility to provide this ability.

Enhanced traps allow you to use the TRAP CONDITION field, indicated by the word IF, to specify an optional condition which must be true in order for abends and breakpoints to be trapped. This condition field is specifically designed to enable you to trap transactions that may be initiated as a result of MQ messages or browser-initiated transactions. In these types of transactions, data may be placed in the CICS COMMAREA, individual containers, Transient Data, Temporary Storage, MQ Message Descriptor, or MQ Message Data that can uniquely identify the owner or initiator of the task.

To provide further granularity, the Trap Summary screen also allows you to specify TCP/IP information instead of NETNAME and terminal. Client IP address, server IP address, and server port number trap criteria can be specified for tasks started from TCPIPSERVICE (Socket Domain tasks) or after tasks have issued a TAKESOCKET (MVS CICS Sockets). Change the MODE of the Trap Summary screen from TERM to either IP or ALL to allow creation of this type of trap. The ALL mode displays both TERM and IP mode traps.

The characters => on the left side of the screen highlight the exact trap entry that caused the current interception.

Access this screen by typing in the number 6 on the System Facilities Menu (9), or as described in Transferring Between Screens.

Trap Summary Screen (9.6)

The Trap Summary screen allows a master terminal to trap abends and/or breakpoints occurring on other terminals or in non-terminal tasks:

• To set a trap for a specific terminal, type the terminal ID in the TERM field and/or the NETNAME in the NETNAME field.
• To set a trap for non-terminal tasks only, type NONE in the TERM field and all asterisks (*) in the NETNAME field.
• To set a trap for all terminals and for non-terminal tasks, type all asterisks (*) or ALL in the TERM and NETNAME fields.
• To set a trap for a specific client IP address, server IP address, and/or server port number, type IP or ALL in the MODE field, press Enter, then type the desired values in the appropriate input fields.

Input Fields

MODE

Designates the type of trap displayed and entered. Valid entries are:

• TERM (default): Traps are based on terminal ID.
• IP: Traps are based on the IP address of the server or client.
• ALL: Both terminal and IP traps are displayed.

When an entry is added in ALL mode, its format determines the type of trap that will be created. In the NETNAME/CLIENT IP field, a NETNAME is one to eight positions long and does not contain embedded periods. In the TERMID/SERVER IP field, TERMID is one to four positions long and does not contain embedded periods.

The last MODE value used is saved in your profile and becomes the default for your next debugging session.

CMD

Line command entry field. Valid entries are:

• A (After): Line after which a moved (M) or copied (C) entry is to be inserted.
• B (Before): Line before which a moved (M) or copied (C) entry is to be inserted.
• C (Copy): Line that is to be copied. (Must be used with the A or B line command.)
• D (Delete): Line that is to be deleted.
• I (Insert): Line after which a blank line is to be inserted.
• M (Move): Line that is to be moved. (Must be used with the A or B line command.)
• S (Save): Saves the specified trap into the profile data set immediately, rather than at the end of the session.

USERID

User Identifier for which abends will be trapped. Wildcard character is asterisk (*). If global parameter TRAP_SUMMARY_USE_USERID=YES, current user ID is the default. If TRAP_SUMMARY_USE_USERID=NO, asterisks are the default.

Global parameter TRAP_SUMMARY_USE_USERID does not apply to TCPIP-based traps. For TCPIP-based traps, if global parameter TRAPS_USE_TERM_USERID_IN_IP_TRAPS=YES, current user ID is the default. If TRAPS_USE_TERM_USERID_IN_IP_TRAPS=NO, asterisks are the default.

NETNAME

Terminal NETNAME for which abends will be trapped. If global parameter TRAP_SUMMARY_USE_TERM_NETNAME=YES, the current terminal NETNAME is the default. If TRAP_SUMMARY_USE_TERM_NETNAME=NO, the default is ALL (asterisks). Valid options are:

• asterisk (*): Wildcard character. Code Debug CICS matches any character with it.
• ALL: Sets the trap for all terminal NETNAMEs. ALL is translated to a field of asterisks.
• HERE: Causes the terminal NETNAME of this terminal to be entered in the NETNAME field.

CLIENT IP

Client IP address for which abends will be trapped. Valid options are:

• The desired address in nodal format with four segments separated by periods (n.n.n.n). The value of each segment must be from 0 to 255. An asterisk (*) wildcard character can be substituted for any of the segments, but not for part of a segment.
• ALL: Sets the trap for all client IP addresses. ALL is translated to: *.*.*.*
• HERE: Causes the IP address associated with this terminal to be entered in the field. This keyword is only valid when the terminal is connected to the mainframe by TCPIP.

TERM

Terminal for which abends will be trapped. If global parameter TRAP_SUMMARY_USE_TERM=YES, current terminal ID is the default. If TRAP_SUMMARY_USE_TERM=NO, the default is ALL (asterisks). Valid options are:

• asterisk (*): Wildcard character. Code Debug CICS matches any character with it.
• ALL: Sets the trap for all terminals and non-terminal tasks. ALL is translated to a field of asterisks.
• HERE (Default): Causes the ID of this terminal to be entered in the TERM field.
• *(W) (display only): The trap was set with <HERE> specified in the TERMINAL ID field on the Traps tab of a Code Debug Eclipse debug configuration in Workbench for Eclipse. The *(W) entry indicates that the trap will be taken whenever a transaction is initiated from a 3270 terminal emulator running on the same workstation as the Code Debug Eclipse debugging session.
• NONE: Sets the trap for only non-terminal (asynchronous) related tasks for the TRAN/PROGRAM combination.

SERVER IP

Server IP address for which abends will be trapped. Valid options are:

• The desired address in nodal format with four segments separated by periods (n.n.n.n). The value of each segment must be from 0 to 255. An asterisk (*) wildcard character can be substituted for any of the segments, but not for part of a segment.
• ALL: Sets the trap for all server IP addresses. ALL is translated to: *.*.*.*
• HERE: Causes the IP address associated with this terminal to be entered in the field. This keyword is only valid when the terminal is connected to the mainframe by TCPIP.

PORT

Server port number for which abends will be trapped. Enter a numeric value from 1 to 65536. Enter a zero to trap all server ports.

TRAN

Transaction in which abends will be trapped. Wildcard character is asterisk (*).

PROGRAM

Program in which abends will be trapped. Wildcard character is asterisk (*).

TRAP ABEND

Allows the optional bypass of abend trapping. Breakpoints continue to be trapped. Disabling of abend trapping allows debugging of CICS handle abend routines and Language Environment user condition handlers (UCHs). Valid entries are:

• YES: Abends will be trapped as specified in the entry. The default of YES can be modified by changing the value of the TRAP_ABEND_FIELD_VALUE_ON_TRAP_SUMMARY global parameter. For more information, see the section entitled “Configuration-Parameters” in the Code Debug CICS Advanced Configuration space.
• NO: Only breakpoints will be trapped as specified in the entry. Can be used to debug handle abend routines and UCHs.

TRAP CONDITION

Enter the optional trap condition following the word IF. A substring-expression is used to specify a condition that can be used for conditional traps and breakpoints. A substring-expression consists of three components:

• substring-phrase
• operator
• string-literal.

During execution, the contents of the storage pointed to by the substring-phrase is tested against the string-literal value using the operator. If the substring-expression is entered on the Trap Summary screen (1.6 or 9.6, based on Code Debug transaction) and the condition evaluates as true, the trap will be taken if all other trap values match. If the substring-expression is entered as a conditional breakpoint, the breakpoint will be taken if all trap values also match.

For a more detailed explanation of a substring-expression, see substring-expression.

Examples

MQMD(5:3) EQ 'ABC'

specifies that if the MQ message header starting in position 5 for a length of 3 is equal to ABC, the condition evaluates as true.

INITCOMM(3:7) GT 'AAAA123'

specifies that if the initial COMMAREA for the transaction starting in position 3 for a length of 7 is greater than AAAA123, the condition evaluates as true.

CURRCOMM(11:4) LT 'A123'

specifies that if the current COMMAREA for the transaction starting in position 11 for a length of 4 is less than A123, the condition evaluates as true.

MQDATA(17:1) NE 'X'

specifies that if the MQ message data at position 17 is not an X, the condition evaluates as true.

CONTAIN+PAYROLL1(40:2) EQ 'MI'

specifies that if the program has access to a container named PAYROLL1 whose position 40 for a length of 2 equals MI, the condition evaluates as true.

TD(1:9) = '135724680'

Specifies that if the most recent Transient Data input begins with 135724680, the condition evaluates as true.

TS(8:5) = T'Weiss'

Specifies that if the most recent Temporary Storage input contains Weiss in position 8 for a length of 5 (including matching the exact case), the condition evaluates as true.

TIOA(*:6) = 'ABCDEF'

Specifies that if the most recent terminal input message contains ABCDEF anywhere within it and in any case, the condition evaluates as true.

Output Fields

ENTRY

Relative entry number that is represented by the first entry on the screen.

TRAP BY

Terminal ID of the terminal that set the abend trap. Check this field when using the M (Move) or C (Copy) commands to make sure that trap entries are not moved or copied from one terminal to another. If a trap entry is inserted, it is assigned to the terminal shown in the TRAP BY field on the line where the I (Insert) command was entered.

Trapping in a CICSPlex Environment

Be as specific as possible when defining trap masks for use in a CICSPlex environment with transaction and distributed program link (DPL) routing. Use non-generic mask information for at least one of the following fields:

• USERID
• NETNAME
• TERM
• TRAN
• Client IP address
• Server IP address
• Server port number

The values of the other fields are not routeable attributes. For more information, see User Transaction and Distributed Program Link Routing.

Trapping Remote Abends or Breakpoints

When the remote transaction abends, it is halted and this terminal may investigate all areas permitted by Code Debug CICS at abend time. The remote transaction remains active. The remote user is not able to clear the screen or start another transaction until the investigation is complete and the remote transaction is resumed or terminated.

Code Debug CICS takes control of the remote terminal when a remote abend has been trapped. A bulletin appears on the local terminal when the abend occurs.

• If Code Debug CICS is not currently active on the monitoring terminal, it is automatically started when the remote abend occurs.

• If Code Debug CICS is started on the monitoring terminal, you can view an active remote abend on the List-Abends-1-3 screen. The highlighted tasks are active and can be selected by typing an S next to the task to be investigated. Local abends must resume or terminate before you can select a remote abend.

Remote tasks can resume from a breakpoint or from certain program check abends. To view the task at the next breakpoint or at another abend, access the List-Abends-1-3 screen after the bulletin informs you that a break/abend has been encountered.

Resuming a remote task produces a TASK HAS BEEN RESUMED message on the System Facilities Menu. You can terminate the remote task from a breakpoint or abend by accessing the Exit Session screen, typing YES in the DUMP OPTION field, and pressing Enter.