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.

Start of change 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. End of change

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.

Start of change 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. End of change

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'.

Start of change 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. End of change

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.

Start of change 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. End of change

Start of change 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. End of change

Start of change 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. End of change

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.