IMS Connect traces

You can trace two types of information about IMS Connect: information about the messages that are processed by IMS Connect and information about the IMS Connect subsystem.

The information about the messages that are processed by IMS Connect is captured by the IMS Connect Recorder Trace facility. Information about the IMS Connect subsystem is captured by the Base Primitive Environment (BPE) tracing services. The information that is captured by both types of traces is stored in BPE trace tables.

Recommendation: Use the BPE trace tables to store information that is captured by the IMS Connect Recorder Trace facility. The IMS Connect Recorder Trace facility can store information in either a BPE trace table or in an IMS Connect-managed Recorder Trace data set (HWSRCDR).

IMS Connect Recorder Trace facility

When the IMS Connect Recorder Trace facility is active, IMS Connect takes a snapshot of the first 670 bytes of messages at key points during IMS Connect processing. The first 670 bytes of most messages include the message header and the message data. Included in the information that is captured by the IMS Connect Recorder Trace facility are elements such as:

Time stamps
The client ID
The user message exit routine

Recommendation: If network security credentials are included in IMS Connect client input messages, enable the BPE External Trace facility for the IMS Connect Recorder Trace facility. If network security credentials are passed to IMS Connect, the size of both input and output messages to and from IMS Connect might be larger than 670 bytes and the BPE External Trace facility would be required to capture the data of the entire message.

When the BPE trace level is set to MEDIUM, or when the HWSRCDR trace data set is used to capture the trace data, IMS Connect takes a snapshot of each input and output message at the following points:

Immediately before a message is passed to a user message exit routine by IMS Connect
Immediately after a message is returned to IMS Connect by a user message exit routine

When the BPE trace level is set to HIGH, the trace information includes a complete snapshot of the message. The recorder trace record also includes a message type code that identifies the source or destination type. IMS Connect takes a snapshot of each complete message, including the message prefixes, at the following points:

Table 1. IMS Connect recorder trace points with BPE trace level HIGH
ID	Type of message	Trace point
TR	ISC, MSC, ODBM, OTMA, or OM	A TCP/IP message was received by IMS Connect.
TS	ISC, MSC, ODBM, OTMA, or OM	A TCP/IP message was sent by IMS Connect.
IR	OTMA	An XCF message was received from OTMA by IMS Connect.
IS	OTMA	An XCF message was sent to OTMA by IMS Connect.
SR	ISC, MSC, ODBM, or OM	An SCI message was received by IMS Connect.
SS	ISC, MSC, ODBM, or OM	An SCI message was sent by IMS Connect.

Recommendation: Setting the trace level to HIGH can cause a significant impact to IMS Connect performance. Do not set the trace level to HIGH except when troubleshooting problems with connectivity.

If you use the BPE External Trace facility for the IMS Connect Recorder Trace, BPE manages the trace data sets. You must perform certain setup tasks, such as defining the GDG base and specifying the EXTTRACE parameter in the BPE configuration member in the IMS.PROCLIB data set. You can then start the IMS Connect Recorder Trace facility by issuing the BPE command UPDATE TRACETABLE NAME(RCTR) OWNER(HWS) LEVEL(MEDIUM) EXTERNAL(YES) or by specifying TRCLEV=(RCTR,MEDIUM,HWS) in the BPECFG member of the IMS.PROCLIB data set and restarting IMS Connect. To view the results of the trace, you can use the BPE Dump Formatter.

If you use a data set that is managed by IMS Connect, it must be a single, fixed-block data set with a fixed logical record length. The data set must be identified by an HWSRCORD DD statement in the IMS Connect startup JCL. When this data set fills, the IMS Connect Recorder Trace facility is disabled. Starting a new trace overwrites any existing trace data in the data set. To change the data set, you must shut down IMS Connect. From an IMS perspective, you can manage this trace data set in the same way as the IMS Monitor Trace (IMSMON) data set.

IMS Connect subsystem traces

The IMS Connect subsystem traces are captured by using BPE services. Subsystem traces trace events that occur within the IMS Connect address space and write them to BPE-managed trace tables. Specific types of events are captured in specific trace table types by IMS Connect or BPE. For example, TCP/IP activity is captured in the IMS Connect TCPI trace table type and BPE dispatcher events are captured in the BPE DISP trace table type.

BPE traces of the IMS Connect are enabled either by issuing the UPDATE TRACETABLE command or by including a TRCLEV parameter for IMS Connect in the BPECFG configuration member and restarting IMS Connect support.

For more information about configuring BPE and preparing for IMS Connect diagnosis, see IMS Version 15.5 System Definition.

Enabling and starting all IMS Connect traces at the same time

You can enable tracing for all trace table types, excluding the Recorder Trace facility trace table (RCTR), by specifying an asterisk in the first position of the TRCLEV parameter in the BPECFG file member, for example TRCLEV=(*,HIGH,HWS). When the TRCLEV parameter is specified in the BPECFG file, the IMS Connect traces run continuously and resume every time IMS Connect starts.

Recommendation: Do not run IMS Connect Recorder trace facility continuously. The IMS Connect Recorder Trace facility can affect performance and should be used only when detailed information is needed about a specific problem with IMS Connect message handling. Remember to disable the IMS Connect Recorder Trace after the problem is resolved.

To enable all traces except the Recorder Trace facility, specify the following parameters:

TRCLEV=(*,HIGH,HWS)

BPE exempts the Recorder trace (RCTR) from wildcard arguments, so it must be enabled with the following trace level configuration statement:

TRCLEV=(RCTR,MEDIUM,HWS)

Recommendation: Start the IMS Connect Recorder Trace with the command, rather than with the TRCLEV parameter. Only use the TRCLEV parameter when you are diagnosing problems that prevent you from issuing commands.

BPE traces can be started and stopped by using BPE commands. If you start a trace by using the UPDATE TRACETABLE command, the traces are only active for the current execution of IMS Connect. The trace tables that are used by BPE to store the trace information, such as the RCTR trace table, are also managed by using BPE commands.