Monitoring tpipe usage

Transaction pipes (tpipes) use significant amounts of IMS resources and processing time, so try to limit the number of tpipes that are created for each tmember.

IMS removes transaction pipes after they have been idle for three consecutive system checkpoints, except in the following circumstances:
  • Commit-then-send messages are queued on the tpipe or the tpipe hold queue.
  • The tpipe is stopped.
  • A trace is set on the tpipe.
  • The tpipe is a synchronized tpipe, such as a tpipe used by MQSeries® for commit-then-send input transactions.
  • The tpipe is in a WAIT state for a resume tpipe request that specified either the AUTO or the SINGLE-WAIT options.
  • The tpipe is in an MCP state, which indicates that the tpipe is running in a shared queues environment and might have output messages on the global queue.
    Tip: If no messages are queued to the TPIPE but the MCP status is displayed for the TPIPE so that the tpipe cannot be removed, issue the /DISPLAY TMEMBER tmembername TPIPE tpipename QCNT command or the /DISPLAY TMEMBER tmembername QCNT command to reset the MCP status.
  • The tpipe is being scanned by IMS.

You can use the /DISPLAY TMEMBER TPIPE command to see whether a tpipe cannot be removed by IMS because one of the circumstances in the preceding list is true for the tpipe.

One way you can control the number of tpipes that are created for a particular OTMA client, is to set a maximum allowable number of tpipes for each OTMA client and for the IMS system.

Tpipe limits for individual OTMA clients

A maximum number of tpipes is specified for an OTMA client by specifying the MAXTP parameter on the OTMA client descriptor in the DFSYDTx member of the IMS.PROCLIB data set.

When the MAXTP parameter is specified for an OTMA client, OTMA monitors the number of tpipes created for the client and issues warnings when the number reaches certain levels.

After a MAXTP value is set for an OTMA client, OTMA monitors the number of tpipes that are created for the client. If the total number of tpipes reaches 80% or a user-specific percentage through the MAXTPWN parameter of the maximum allowable number, IMS issues the warning message DFS4382W to the system console and the MTO. IMS also issues a protocol command TMAMMNTR (X'3C' Resource Monitor) message with the warning status of the server to the OTMA client.

If the number of tpipes reaches 100% of the maximum allowable number, IMS issues error message DFS4383E to the system console and the MTO. Any input transactions that require a new tpipe are rejected with a NAK with OTMA sense code X'29'.

After the warning or error messages is issued and the total number of the tpipes for the client drops 50% or a user-specified percentage through the MAXTPRL parameter of the maximum allowable number, IMS issues message DFS4384I to indicate that the number of tpipes returned to normal.

Tpipe limits in the IMS system

You can define a global TPIPE warning threshold for all of the OTMA clients by defining an OTMA client descriptor with the name DFSOTMA and specifying the MAXTP parameter. The DFSOTMA descriptor is the OTMA system client descriptor that defines values for the IMS system that apply to all OTMA clients.

When the number of tpipes in the IMS system reaches 80% or a user-specified percentage of the DFSOTMA MAXTP value through the DFSOTMA MAXTPWN parameter, IMS issues message DFS4515W to both the system console and MTO. OTMA also issues a protocol message to all OTMA clients. After that, OTMA continues creating new tpipes until the number of tpipes reaches the maximum number as defined by the DFSOTMA MAXTP value.

If the total number of tpipes in the IMS system reaches 100% of the DFSOTMA MAXTP value, OTMA rejects all new tpipe creation requests from any OTMA members with a NAK that contains the sense code X'29'. IMS sends DFS4516E error message to the system console and the MTO, and notifies all OTMA clients with an OTMA protocol message.

After a DFS4515W or DFS4516E is issued and the total number of monitored tpipes in the system drops down to 50% or another user-specified level of the global tpipe warning threshold through the DFSOTMA MAXTPRL parameter, IMS issues message DFS4517I to indicate that the number of tpipes returned to normal.

If the OTMA DFSOTMA system client descriptor does not define a global maximum for the number of tpipes in an IMS system, and one or more OTMA clients have a maximum allowable number of tpipes defined in their OTMA client descriptors, the highest MAXTP value among all of the client descriptors serves as a global warning threshold for the IMS system. When the total number of tpipes in use by all OTMA clients that are subject to tpipe monitoring reaches the global warning threshold, IMS issues warning message DFS4385W to the system console and the MTO.

After a global warning is issued and the total number of tpipes drops down to 80% of the global warning threshold, IMS issues message DFS4386I to indicate that the number of tpipes returned to normal.

X'3C' protocol command notifications

OTMA also sends out the X'3C' protocol command to the OTMA clients at the various warning, error, and relief thresholds. Upon receiving the X'3C' protocol command for a warning or error, the client applications can reroute any subsequent transactions to a different IMS system as appropriate. When the number of tpipes drops below the relief threshold, the X'3C' protocol command is issued again with the warning or error flag turned off.

Displaying information about the number of tpipes

The IMS commands /DISPLAY OTMA and /DISPLAY TMEMBER can show the current number of tpipes for the OTMA clients that have a MAXTP value set. If an OTMA client reaches the maximum allowable number of tpipes, the command output shows MAX TPIPE as the USER_STATUS for the OTMA client.

The global warning threshold set by the highest MAXTP value among multiple OTMA clients is displayed under the output field TPNCT for the IMS server.

Reducing tpipe storage by using the lightweight tpipe function

You can enable the lightweight tpipe function by specifying LITETP=YES in the DFSOTMA descriptor in the DFSYDTx IMS.PROCLIB member. When this function is enabled, less storage is used when a tpipe is created in a shared queues back-end IMS system to process front-end input transactions. Specifying LITETP=YES enables IMS to support more tpipes. If LITETP=YES is specified, message DFS7411I is issued on IMS initialization to indicate that this function is enabled.

Because a lightweight tpipe requires less storage than a regular tpipe, a weighting factor is used on back-end tpipes when calculating the tpipe count for tpipe flood control. The weighting factor is the percentage of the lightweight tpipe storage size relative to the regular tpipe storage size, which is usually 28%. See the description of the LITETP= parameter in DFSOTMA descriptor syntax and parameters for the calculation of the adjusted tpipe count.

Increasing tpipe cleanup frequency by using the FASTTPCU function

You can enable the fast transaction pipe checkpoint cleanup (FASTTPCU) function by specifying FASTTPCU=YES in the DFSOTMA descriptor in the DFSYDTx IMS.PROCLIB member. When this function is enabled, the IMS system can delete an idle OTMA tpipe more frequently. A tpipe that has been idle for two consecutive system checkpoints will be cleaned up. If the function is disabled or not specified, the IMS system uses the default tpipe cleanup. The IMS system cleans up a tpipe that has been idle for three consecutive system checkpoints instead.

The FASTTPCU settings in a shared queues environment

In a shared queues environment, if you activate the FASTTPCU parameter in the front-end IMS system, the behavior could vary in the back-end IMS system. Because the FASTTPCU parameter applies only to IMS 15.3 and later versions, the number of checkpoints for removing idle tpipes could be different depending on:
  • the versions of the front-end IMS system and the back-end IMS system
  • the installation of APAR PH52141 in the back-end IMS system

If both the front-end IMS system and the back-end IMS system are in IMS 15.3, and the back-end IMS system has APAR PH52141 applied, the back-end IMS system inherits the FASTTPCU setting from the front-end IMS system for any OTMA tpipes generate for the work from the front-end IMS system. This overwrites any FASTTPCU setting in the back-end IMS system.

If the back-end IMS system is in IMS 15.2 or lower versions, the following table provides information about how many checkpoints it takes to remove idle tpipes in a shared queues environment in different cases:
Table 1. The number of checkpoints for removing idle otma tpipes
  Front-end IMS system in IMS 15.2 or lower versions Front-end IMS system in IMS 15.3 or higher versions
Back-end IMS system with APAR PH52141 applied

Front-end IMS: 3 checkpoints

Back-end IMS: 3 checkpoints

Front-end IMS: 2 checkpoints

Back-end IMS: 2 checkpoints
Back-end IMS system without APAR PH52141 applied

Front-end IMS: 3 checkpoints

Back-end IMS: 3 checkpoints

Front-end IMS: 2 checkpoints

Back-end IMS: 3 checkpoints
Important: While you can clean up inactive tpipes faster than before with the FASTTPCU function, the performance of your IMS systems could remain unchanged.