OTMA client descriptor syntax and parameters

To specify global attributes that apply to all OTMA clients, use the DFSOTMA global client descriptor.

An OTMA client descriptor can also be used to set the global tpipe limit for all the OTMA members or clients.

OTMA client descriptors are optional.

You can specify a maximum of 254 OTMA client descriptors in the DFSYDTx member of the IMS PROCLIB data set. If you do not use the DFSOTMA descriptor, you can specify 255 OTMA client descriptors.

Client descriptors are always loaded from the DFSYDTx PROCLIB member regardless of the IMS restart type. There are no checkpoint log records for client descriptors.

Format

You can use up to 50 lines in the specification of a descriptor. Columns 1 - 18 must be the same for each line. You must delimit all parameters by using a blank space.

The following table includes information about the format of an OTMA client descriptor.

Parameters

You can specify the following parameters on the OTMA client descriptor:

ALTPCBE=NO | YES

Specifies whether the OTMA shared queues alternate PCB (ALTPCB) output, which is originated from an OTMA front-end IMS and generated at the back-end IMS, must be delivered to the front-end IMS for the OTMA client. This parameter is optional and defaults to ALTPCBE=NO.

If the super member function is activated for the ALTPCB output at the shared queues back-end IMS, the super member takes precedence.

DRU=exit_name

8-character OTMA Destination Resolution exit routine name. Duplicate exit routine names are allowed.

DSAP

Specifies the minimum allocation of save area prefixes (SAPs) for this OTMA client.

Valid values are 18 - 500.

A DSAP value specified on an OTMA client descriptor overrides the DSAP value specified on the DFSOTMA descriptor, if any.

If the DSAP parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the DSAP parameter for OTMA clients. If the DSAP parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, DSAP=18 is the default for an OTMA client.

DSAPMAX

Specifies the maximum allowable number of SAPs that this OTMA client can have allocated at the same time.

Valid values are 18 - 500. If the value that is specified on the DSAPMAX parameter is less than the value of the DSAP parameter, a value of 500 is used.

A DSAPMAX value specified on an OTMA client descriptor overrides the DSAPMAX value specified on the DFSOTMA descriptor, if any.

If the DSAPMAX parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the DSAPMAX parameter for OTMA clients. If the DSAPMAX parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, DSAPMAX=500 is the default for an OTMA client.

INPT=

A 1- to 5-digit decimal integer that indicates the maximum flood limit for input messages from this member.

Valid values are 200 - 65000, or 0. If the value is 1 - 200, it is treated as 200. If the value is over 65000, a value of 65000 is used.

When this value is higher than the default global flood limit of 8000, the default global flood limit will be changed to this value. If more than one client descriptor has input (INPT) values that are higher than the default global flood limit, the highest value will become the default global flood limit.

If you specify a value of 0, OTMA deactivates the input message flood detection for this client; however, OTMA still includes the input messages from this client in the calculation of the global message counts.

This value might also affect the global flood limit:

• If the INPT parameter is not specified for the OTMA system client name DFSOTMA descriptor, then the global flood limit is determined by these criteria:
  • If a member flood limit through INPT parameter is specified for a client descriptor and the value is higher than the default global flood limit of 10000, then the global flood limit is set to this value. If more than one client descriptor has INPT values higher than the default global flood limit, then the global flood limit is set to the highest INPT value.
  • If there are no member flood limit INPT higher than the default global flood limit of 10000, then the global flood limit is set to 10000.
• If the INPT parameter is specified for the DFSOTMA descriptor, then the global flood limit is set to its value.

Internally, each OTMA input message is represented by a transaction instance block (TIB). Therefore, within the context of OTMA, the terms TIB and input message are generally synonymous.

When message flood control is active for the OTMA client and the number of input messages from this client reaches 80% of the INPT= value, OTMA issues the DFS1988W warning message to the master terminal operator (MTO) and system console, and issues a protocol messages to the OTMA client. Thereafter, OTMA reissues DFS1988W at every 5% increase in the message count, until the number of messages reaches the maximum.

When the message flood limit is reached, OTMA rejects all the new input transactions from the member. OTMA issues DFS1989E error message to the console and MTO, and a server state protocol command to the OTMA client. The OTMA client can then choose to take corrective action, such as rerouting new transaction requests to a different IMS system. The /DISPLAY TMEMBER command shows FLOOD.

When the input messages in the system are processed and the number of total TIBs in the system is 50% or less of the global limit, the flood status is relieved. A DFS0767I message is sent to the MTO and system console, and a server state protocol message is sent to the OTMA client.

LIMITRTP

Specifies the maximum number of active RESUME TPIPE requests for any tpipes of this OTMA client and, if MULTIRTP=YES is not already specified, enables support for multiple active resume tpipe requests for the tpipes that are created for this client.

Valid values are a 2- to 4-digit decimal integer between 10 and 4095. IMS treats values between 0 and 9 as 10. IMS treats any 4-digit decimal number greater than 4095 as 4095.

If the MULTIRTP= parameter is not specified when the LIMITRTP parameter is specified, the MULTIRTP setting is automatically set to YES. However, if MULTIRTP=NO is specified, the LIMITRTP parameter is ignored.

The default value for LIMITRTP parameter is 100.

If the maximum number of RESUME TPIPE requests are already active, any additional requests that are received are queued and will become active when an currently active request ends.

When the LIMITRTP parameter is specified on the DFSOTMA global client descriptor, it is used to set the default only for clients that do not specify the LIMITRTP parameter. Also, if the MULTIRTP parameter is not specified on the DFSOTMA descriptor, the specification of LIMITRTP parameter changes the system default to MULTIRTP=YES.

For the super member function, the LIMITRTP value of the first OTMA client that connects to the IMS defines the LIMITRTP value of the super member.

Using the OTMA client descriptor is the only way to specify or change the LIMIRTP value. OTMA clients cannot set or change the LIMITRTP value in a client bid protocol message.

LOGSTR=NO | YES

Specifies whether the first 255 bytes of network security credentials, which includes a network user ID or network session ID, or both, is included in the RACF® SMF process records. The network security credentials must exist in the security-data section of the input OTMA message prefix to be included in the SMF records. The format of network user ID and network session ID in the SMF records is identical to the corresponding format in the OTMA security prefix. This parameter is optional and defaults to LOGSTR=NO.

MAXTP=

A 1- to 6-digit decimal integer from 0 - 999999 that defines the maximum number of tpipes that this OTMA client member can have in an IMS system. If 0 is specified, OTMA does not monitor or limit the number of tpipes that this OTMA client can have in the IMS system. If a value of 1 to 200 is specified, it is treated as 200. Any number over 999999 is rejected.

Before an OTMA member's MAXTP value is reached, IMS issues message DFS4382W as a warning when the number of tpipes reaches a threshold through a percentage of the maximum number that is either 80% or a user-specified percentage as shown in the MAXTPWN value. OTMA also issues a protocol command TMAMMNTR (X'3C' Resource Monitor) message with the warning status of the server to the OTMA client. After the threshold is reached, OTMA continues creating new tpipes until the number of tpipes reaches the maximum number of tpipes allowed as defined by the MAXTP value.

If the total number of tpipes from this client reaches the maximum number, OTMA rejects all new tpipe creation requests from the OTMA member with a NAK with sense code X'29'. IMS sends DFS4383E error message to the system console and master terminal operator (MTO), and notifies the OTMA client with an OTMA protocol message. The /DISPLAY TMEMBER command shows MAX TPIPE in the user status of the client member.

When the number of tpipes for the OTMA member drops to 50% of the maximum number, or a user-specified percentage through MAXTPRL parameter, IMS issues message DFS4384I to the IMS system console and MTO, and notifies the OTMA member with a heartbeat protocol message.

If MAXTP parameter is not specified in the DFSOTMA descriptor, the OTMA client descriptor with the highest MAXTP value defines a global warning threshold for the total number of tpipes in the system for all OTMA clients. When this global warning threshold is reached, IMS issues message DFS4385W to the MTO and system console, and OTMA issues a server state protocol command to all OTMA clients. IMS does not prevent the creation of new tpipes.

When the global tpipe count falls to 80% of the global tpipe warning threshold or below, IMS issues message DFS4386I to the MTO and system console and OTMA notifies all OTMA clients with another protocol message.

When MAXTP parameter is specified in the DFSOTMA descriptor, IMS uses the DFSOTMA MAXTP value as the global warning limit instead of the highest MAXTP value among the OTMA client descriptors and the warning thresholds are different. For more information about the effect of the DFSOTMA MAXTP parameter, see DFSOTMA descriptor syntax and parameters.

The /DISPLAY OTMA and /DISPLAY TMEMBER commands result in displays of the current numbers of tpipes and MAXTP value for members and OTMA server using the function.

Note:

If LITETP=YES is specified in the DFSOTMA descriptor, the lightweight tpipe function will be enabled. As a result, tpipes that are created in a shared queues back-end IMS system use less storage. To take this reduction in storage size into account, a weighting factor is applied to these lightweight tpipes when calculating the total number of tpipes. An adjusted tpipe count is used instead of the total tpipe count, which consists of the number of front-end tpipes plus the number of back-end tpipes, to check if the IMS system reached the maximum tpipe limit.

The adjusted tpipe count is calculated as follows:

• A: the number of front-end tpipes (total tpipes - back-end tpipes)
• B: the number of back-end tpipes
• W: the weighting factor
• adjusted tpipe count=A+(B*W)

For more information on the LITETP= parameter, see DFSOTMA descriptor syntax and parameters.

MAXTPBE=YES | NO

Specifies whether (YES) or not (NO) the MAXTP must be monitored when this IMS is a shared queues back-end system processing a front-end initiated OTMA input transaction at the application GU time. This is designed for member when MAXTP parameter is specified. It is ignored if the member does not have MAXTP parameter specified.

A MAXTPBE value specified on an OTMA client descriptor overrides the MAXTPBE value specified on the DFSOTMA descriptor, if any.

If the MAXTPBE parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the MAXTPBE parameter for OTMA clients. If the MAXTPBE parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, MAXTPBE=YES is the default for an OTMA client.

MAXTPRL=

Specifies the relief level for the MAXTP value as a percentage of the maximum number of tpipes that this client can have. Valid values are 50 - 95. If a value less than 50 is specified, it is set to 50. Values over 95 are set to 95.

A MAXTPRL value specified in an OTMA client descriptor overrides the MAXTPRL value that is specified in the DFSOTMA descriptor, if any.

If the MAXTPRL parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the MAXTPRL parameter for OTMA clients. If the MAXTPRL parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, MAXTPRL=50 is the default for an OTMA client.

If LITETP=YES is specified in the DFSOTMA descriptor, the adjusted tpipe count is used instead of the actual number of tpipes in use to check if the IMS system reached the maximum tpipe limit. See the LITETP= parameter in the DFSOTMA descriptor for the calculation of the adjusted tpipe count.

MAXTPWN=

Specifies the warning level for the MAXTP value as a percentage of the maximum number of tpipes that this client can have. Valid values are 50 - 95. If a value less than 50 is specified, it is set to 50. Values over 95 are set to 95.

A MAXTPWN value specified on an OTMA client descriptor overrides the MAXTPWN value that is specified on the DFSOTMA descriptor, if any.

If the MAXTPWN parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the MAXTPWN parameter for OTMA clients. If the MAXTPWN parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, MAXTPWN=80 is the default for an OTMA client.

MULTIRTP=YES | NO

Specifies whether or not a given TPIPE supports multiple active resume tpipe requests.

When MULTIRTP=YES is specified, the tpipes that are created for this client support multiple active resume tpipe requests. Commit-then-send (CM0) output messages or callout request messages from IMS application programs can retrieved by multiple client instances in parallel.

When MULTIRTP=NO is specified, the tpipes that are created for this client support only one active resume tpipe request at a time. IMS commit-then-send (CM0) messages or callout messages are delivered to client one message at a time. Any subsequent RESUME TPIPE requests that are received while the first one is still active are queued.

A MULTIRTP value specified on an OTMA client descriptor overrides the MULTIRTP value specified on the DFSOTMA descriptor, if any.

If the MULTIRTP parameter is specified in the DFSOTMA descriptor, the DFSOTMA specification determines the default value of the MULTIRTP parameter for OTMA clients. If the MULTIRTP parameter is not specified on the DFSOTMA descriptor or no DFSOTMA descriptor exists, MULTIRTP=NO is the default for an OTMA client.

A MULTIRTP specification made in a client bid request by an OTMA client overrides a MULTIRTP specification made in an OTMA client descriptor.

SENDALTP=NO | YES

Specifies whether or not ALTPCB output needs to be sent to IMS Connect.

When SENDALTP=YES is specified, ALTPCB output is sent back to the IMS Connect client that originally initiated the commit-then-send send/receive call. If the OTMA destination descriptor or DFSYDRU0 user exit specifies a member that is not the initial IMS Connect client, and the member is not a super member, the output is saved in a TPIPE hold queue.

When SENDALTP=NO is specified, ALTPCB output for IMS Connect is kept in a TPIPE hold queue. It can be retrieved by a RESUME TPIPE call.

This parameter is optional and defaults to SENDALTP=NO.

TODUMP=NO | YES | U243

Specifies whether the pseudo ABENDU0243 is needed at application GU time for one of the following reasons:

• An OTMA transaction expired.
• An OTMA input transaction that requires a new tpipe is rejected because the maximum number of tpipes as defined by the MAXTP= parameter is reached.
• An OTMA input transaction that requires a new tpipe is rejected when the tpipe flood limit that is defined in the INPT parameter has been reached.

This parameter is optional and defaults to TODUMP=NO.

If you use IMS shared queues and the TODUMP= parameter is specified, the parameter needs to be set in the OTMA client descriptor in the front-end IMS system.

If the TODUMP= parameter is specified in the DFSOTMA descriptor, the value of the DFSOTMA TODUMP= parameter is used by OTMA clients that do not specify the TODUMP= parameter.

You can specify one of the following values for this parameter:

NO

If NO is specified, IMS discards the affected transaction without the ABENDU0243 to save CPU cycles. Because pseudo ABENDU0243 is not issued for each affected transaction at GU time, no additional IMS type X'56' log records are written. However, IMS writes a type X'67D0' diagnostic information log record for each affected transaction at GU time.

YES

If YES is specified, a pseudo ABENDU0243 with message DFS554A and symptom dump is generated at the GU time for each expired or rejected OTMA transaction. If you specify YES, the console might become flooded and the IMS system might require more CPU cycles if many transactions are expired or rejected.

U243

If U243 is specified, a pseudo ABENDU243 is generated without message DFS554A and without symptom dump for each affected transaction at GU time. To identify the transactions that pseudo ABENDU243 is issued for, see the IMS type X'56' log record.

T/O=

A 1- to 3-digit decimal integer 0 - 255. It indicates the timeout value, in seconds, for OTMA to wait for acknowledgments. If the value is over 255, OTMA uses 255. If the value is 0, OTMA deactivates the timeout function. The default value is 120.

ACK timeout intervals can be specified for the following types of OTMA output messages:

• Transaction messages that are sent to a remote IMS system for processing
• Some send-then-commit (CM1) response messages
• Commit-then-send (CM0) response messages

You can override the descriptor timeout value by taking one of the following actions:

• Issuing the /START TMEMBER TIMEOUT command to reset the timeout value
• Specifying a lower timeout value by using the client bid of an OTMA client, such as IMS Connect.

The T/O parameter also applies to acknowledgments for messages that are sent to remote IMS systems by way of an IMS-to-IMS TCP/IP connection. For these types of messages, if the timeout interval expires before an acknowledgment is received, OTMA reroutes the message to the timeout queue designated by IMS Connect or to the OTMA default timeout queue, DFS$$TOQ.