Traps tab

The Traps tab of a CICS launch configuration allows you to define the traps to be set upon startup of your Xpediter debug session. Traps define the CICS activity subject to being trapped into a debug session. Among other purposes, this tab can be used to intercept and debug a program based on values found within the CICS COMMAREA associated with a program. The Traps tab has two traps set by default: one to trap based on your 3270 terminal/emulator and one to trap based on your user ID. The CICS-Traps-view allows users to view the traps that have been set and to add, edit, and remove traps while a debugging session is active.

Note: Traps are also used to define the CICS activity that is displayed within a Runtime Visualizer session. Refer to the Topaz Workbench Program Analysis and Runtime Visualizer User Guide.

Note: When debugging in CICS, you must log on to the specified region via a 3270 terminal/emulator and enter the transaction that will run your program or invoke the program by another means, such as a web application or incoming MQ message.

Note: The default traps set by Xpediter/Eclipse are sufficient for most users. Add or edit traps only if the default traps are known to be insufficient.

Any transactions executed in the specified region by the specified user ID are trapped by Xpediter/Eclipse.

The Traps tab contains the following fields:

  • User ID
  • Terminal ID
  • Netname
  • Client IP
  • Server IP:Port
  • Transaction
  • Program
  • Abends
  • Data

These fields function as described in the following section.

The Traps tab allows users to add, edit, or remove traps as well as move traps up or down within the table.

Adding or Editing a Trap

When you click Add, the Add CICS Trap dialog box appears. When you click Edit, the Edit CICS Trap dialog box appears. The fields on the two dialog boxes are identical.

These dialogs present a number of options for you to create a specific trap you want to add to your debug session. By default, traps are set for breakpoints. Traps are set for abends only if the Trap abends that may occur check box is selected. Once you click OK, the trap is added to/edited in the table.

The fields on these dialog boxes are as follows:

  • Communications
    • Trap this workstation’s emulators: Select to trap all transactions that originate from this workstation's terminal emulators. This option assumes that the terminal emulator and Topaz Workbench execute on the same workstation (that is, that they have the same IP address). If the workstation emulator and Topaz Workbench do not run on the same workstation (which may be the case if Topaz Workbench is executing on a server) or if you are unsure whether they run on the same workstation, select Trap all communication activity instead. Selecting Trap this workstation’s emulators results in the <HERE> placeholder displaying on the Traps tab's Terminal ID column.
    • Trap all communication activity: Select to set a trap for all terminals and for non-terminal tasks.
    • Trap by terminal ID: Select to set a trap for a specific terminal, then enter any of the following:
      • The terminal ID for which you want to set a trap
      • An asterisk as a wildcard character
      • NONE to set the trap for only non-terminal (asynchronous) related tasks for the TRAN/PROGRAM combination
    • Trap by netname: Select to set a trap for a specific netname, then enter the terminal netname for which you want to set a trap. An asterisk can be used as a wildcard character.
    • Trap non-terminal IP communications: To set a trap for non-terminal tasks only, do one of the following:
      • Client activity>Use this workstation’s IP address: Select to use the current terminal’s IP address for the trap.
      • Client activity>All non-terminal client activity: Select to set the trap for all client IP addresses.
      • Client activity>Other client IP: Select and then enter the client IP address to be used for the trap. Enter 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 can be used as a wildcard character for any of the segments but not for part of a segment.
      • Server activity>All non-terminal server activity: Select to set a trap for all server IP addresses.
      • Server activity>Use the CICS region’s IP address: Select to cause the IP address associated with this terminal to be used for the trap.
      • Server activity>Other server IP/port:
        • IP: Select and then enter the desired server IP 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 can be used as a wildcard character for any of the segments but not for part of a segment.
        • Port: Select and then enter the server port number for the trap. Enter a numeric value from 1 to 65536. Enter a zero to trap all server ports.
  • User ID
    • Trap user ID specified at login: Select to trap abends for the current user ID. The <LOGIN> placeholder on the Traps tab is converted to a real value when a CICS debug session is started.
    • Trap all users: Select to trap abends for all user IDs.
    • Trap other user ID: Select and then specify the user ID for which to trap abends. An asterisk can be used as a wildcard character.
  • Application
    • Trap all transactions and programs: Select to trap by transaction or program, then specify the transaction or program name.
    • Trap by transaction/program: Select to trap by transaction or program, then specify the transaction or program name.
      • Transaction: Specify the transaction in which breakpoints will be trapped. An asterisk can be used as a wildcard character.
      • Program: Specify the program in which breakpoints will be trapped. An asterisk can be used as a wildcard character.
  • Data
    • Trap using data intercept: Select this check box to trap transaction based on the data in a transaction's COMMAREA.
    • Data area: Select from the drop-down list either Initial COMMAREA or Current COMMAREA. The initial COMMAREA is the COMMAREA passed to the initial program in a transaction (task), while the current COMMAREA is the current COMMAREA of a transaction (tasks) when there is a transfer of control within the task.
    • Data value: Enter the data value within the COMMAREA to trap the transaction based on. For example, if the initial COMMAREA contains the characters "Commarea" in bytes 1 to 8, supplying a value of "comm' in the Data value field, a start position of 1, and an operator of "Equal" will cause the transaction to be trapped. Refer to the descriptions of the Start position and Operator fields below.
    • Data type: Select from the drop-down list the type of data to be trapped. The available options are EBCDIC (not case-sensitive), EBCDIC (case-sensitive), Hex, ASCII (not case-sensitive), and ASCII (case-sensitive).
    • Select one of the following:
      • Search entire data field: Select this radio button to search the entire data field. When this option is selected, the Start position field is set to * and the Operator field is set to Equal; these are not modifiable.
      • Specify data location: Select this radio button to search only a specific data location. Then specify the start position and operator for the search.
  • Trap abends that may occur: Select this check box to trap abends, or clear it to bypass abend trapping. When abend trapping is bypassed, breakpoints continue to be trapped. Disabling of abend trapping allows debugging of CICS handle abend routines and Language Environment user condition handlers (UCHs).

When you select a trap and click Remove on the Traps tab, the selected trap will be deleted. When you select a trap and click Move Up, the selected trap will switch positions in the table with the trap above it. When you select a trap and click Move Down, the selected trap will switch positions in the table with the trap below it.


Your configuration setup is now complete and you are ready to launch your debug session. Refer to Debugging-in-Xpediter-Eclipse.










 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*