DFSOTMA descriptor syntax and parameters

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 shows the format of the DFSOTMA descriptor.

Parameters

You can specify the following parameters on the DFSOTMA descriptor:

ABEND=NO|YES

Specifies IMS initialization terminates abnormally when an invalid parameter is specified in an OTMA client descriptor or a DFSOTMA descriptor.

This parameter is an OTMA global attribute and cannot be specified in an OTMA client descriptor. It has no effect on OTMA destination descriptors. The default value is NO.

NO

Specifies that OTMA accepts the valid parameters in the client descriptor or the DFSOTMA descriptor. Any invalid parameters specified are rejected with a DFS2385E error message.

YES

Specifies that the IMS system abends with ABEND0078 when an invalid parameter is specified in an OTMA client descriptor or a DFSOTMA descriptor.

ACEEUSR=

A 1- to 6-digit decimal integer in the range 0 - 999,999 that defines the maximum number of RACF user IDs that can have cached accessor environment elements (ACEEs) stored in subpool 249.

If you specify a value for the ACEEUSR= parameter but you explicitly specify TOACEE=NO, the ACEE flood control function is disabled and the ACEEUSR= parameter is ignored.

If you specify a value for the ACEEUSR= parameter but you do not specify the TOACEE= parameter, the value of TOACEE= is automatically set to YES and the value that you specify for the ACEEUSR= parameter is used.

If OTMA caches ACEEs but you do not specify the ACEEUSR= parameter, OTMA uses the default value of 30,000 for ACEEUSR=.

If you specify both ACEEUSR=0 and TOACEE=YES, OTMA uses the default value of 30,000 for ACEEUSR=.

DDESCMAX

A 3- to 4-digit decimal integer from 510 to 4095 that defines the maximum number of destination (type-D) descriptors that can be defined in the IMS system, either by the CREATE OTMADESC command or by coding them in the DFSYDTx member of the IMS PROCLIB data set.

Any value less than 510 is set to 510. Any 4-digit value greater than 4095 is set to 4095. The default value is 510.

This parameter is only valid for the DFSOTMA descriptor.

Destination descriptors are stored in the extended common storage area (ECSA). The more destination descriptors that are defined, the more ECSA storage is used.

DSAP

Specifies the system default setting for the minimum allocation of save area prefixes (SAPs) for OTMA clients that do not specify a value in the OTMA client descriptor.

Valid values are 18 - 500. The default value is 18.

DSAPMAX

Specifies the system default setting for the maximum allowable number of SAPs that an OTMA client can have allocated at the same time. The DFSOTMA DSAPMAX value applies only to those OTMA clients that do not specify a DSAPMAX value in the OTMA client descriptor.

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.

ENDCONV=

A 1- to 4-digit decimal integer in the range 0 - 7200 that defines the timeout value in seconds for an idle OTMA conversational transaction. If the conversational transaction remains idle for the specified number of seconds after the prior iteration of the conversational transaction completes, OTMA ends the transaction and releases IMS resources that were allocated for the transaction.

If this parameter is not specified, the default value is 3600 seconds, which is 1 hour.

If 0 is specified for this parameter, OTMA deactivates the timeout function for conversational transactions.

If a value in the range 1 - 119 is specified, OTMA automatically sets the value to 120.

If a 4-digit value greater than 7200 is specified, OTMA automatically sets the value to 7200.

If a 5-digit value is specified, the number will be rejected.

ICALRTP=YES|NO

Specifies whether IMS rejects the ICAL call when there is no outstanding RESUME TPIPE request. The default value is YES.

YES

Specifies that IMS rejects the ICAL call if there is no outstanding RESUME TPIPE request. This prevents the IMS application program that issues the ICAL call from getting an ICAL timeout error due to a missing RESUME TPIPE request.

NO

Specifies that IMS does not reject the ICAL call if there is no outstanding RESUME TPIPE request. The IMS application program that issues the ICAL call waits for an active RESUME TPIPE request until the ICAL call times out.

INPT=

A decimal integer from 0 - 99999 that defines the maximum number of input messages from all OTMA clients or members that can be waiting to be processed at the same time. If you specify a value of 0, OTMA deactivates the input message flood detection. If the value is 1 - 0200, it is treated as 0200.

When an OTMA client sends a transaction to IMS, OTMA internally creates a transaction instance control block (TIB) in storage to track each active input message. Activating a global flood threshold protects IMS from getting storage-related abends as a result of too many TIBs in the system.

If the number of TIBs reaches 80% of the global flood limit, IMS issues the DFS3428W warning message to the MTO and system console, and sends OTMA protocol messages that reflect a warning status to all the OTMA member clients. This message is issued every 5% thereafter until the global message limit is reached.

When global flood control is active and the global flood limit is reached, IMS takes the following actions:

• OTMA rejects all new input transactions from all the members, including synchronous program switch requests from the internal OTMA member DFSYICAL
• The status of the OTMA server member is set to SERVER-FLOOD. The status can be displayed by issuing the /DISPLAY OTMA.
• IMS issues a DFS3429E error message to the console and MTO
• OTMA sends an unavailable for work protocol message (command type X'3C') to all the OTMA members. OTMA members can then choose to take corrective action, such as rerouting new transaction requests to another IMS system.

This global flood status is relieved when the input messages in the system are processed and the number of total TIBs in the system is reduced to 50% or less of the global limit. A DFS0793I is sent to IMS MTO and system console along with OTMA protocol messages that reflect a good status to all the OTMA members.

If no global limit is specified in the DFSOTMA descriptor, any client descriptors, or the /START TMEMBER ALL INPUT command, the default global flood processing takes place in the system, and the default global flood limit is set to 10000 to protect the system. The default OTMA global flood actions include:

• Warning message DFS3428W starting at the 80% level of the flood limit and every 5% thereafter.
• Warning message DFS4388W when 100% level is reached.
• Relief message DFS0793I when the flood is relieved and back to 50% level.

The OTMA protocol message that reflects a warning or good status is sent to all the OTMA members.

LIMITRTP

For any OTMA client that does not make its own LIMITRTP specification, specifies the default maximum number of active RESUME TPIPE requests that the tpipes of the OTMA client can support. If MULTIRTP=YES is not already specified, specifying a value on LIMITRTP parameter enables support for multiple active RESUME TPIPE requests for any client that does not specify the MULTIRTP parameter itself.

Valid values are a 1- 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. The default value for LIMITRTP parameter is 100.

When the maximum number of active RESUME TPIPE requests is reached, any additional RESUME TPIPE requests that are received are queued and become active after a currently active request ends.

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 OTMA type-M descriptors is the only way to specify or change the LIMITRTP value. OTMA clients cannot set or change the LIMITRTP value in a client bid protocol message.

LITETP=NO|YES

Specifies whether the OTMA lightweight tpipe function is enabled.

NO

Specifies that the OTMA lightweight tpipe function is disabled. This is the default for an IMS cold start.

YES

Specifies that the OTMA lightweight tpipe function is enabled. 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.

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

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)

When the DFSOTMA MAXTP= parameter is specified, if the LITETP= parameter is enabled, IMS monitors if the number of tpipes reaches the maximum allowable number by using the adjusted tpipe count instead of the total tpipe count, which consists of the number of front-end tpipes plus the number of back-end tpipes. If the LITETP= parameter is disabled, IMS keeps using the total tpipe count for flood control.

The value of the LITETP= parameter value is saved at check point. On IMS restart, IMS may use one of the following values for the LITETP= parameter:

• If the LITETP= parameter is specified, then IMS uses the new value.
• If the LITETP= parameter is not specified, or the DFSYDTx member does not exist, then IMS restores and uses the previous saved value.

MAXTP=

A 1- to 6-digit decimal integer from 0 - 999999 that defines the maximum total number of tpipes in an IMS system for all OTMA clients. If a value of 0 is specified, which is the default, OTMA stops monitoring the creation of the tpipes. If the value is between 1 and 200, it is treated as 200. Any number over 999999 is rejected.

Before the DFSOTMA MAXTP value is reached, IMS issues message DFS4515W as a warning when the number of tpipes in the IMS system reaches a threshold through a percentage of the maximum number that is either 80% or a user-specified percentage through the MAXTPWN parameter. OTMA also issues a protocol message to all OTMA clients. 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 in the IMS system reaches the number that is specified on the DFSOTMA MAXTP parameter, OTMA rejects all new tpipe creation requests from all OTMA members with a NAK with 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. The /DISPLAY OTMA command shows MAX TPIPE in the user status of the OTMA server.

When the number of tpipes for all members falls to 50% or a user-specified percentage of the global tpipe warning threshold through the MAXTPRL parameter, IMS issues message DFS4517I to the IMS system console and the master terminal operator (MTO). OTMA also notifies all OTMA clients of the improved status with a protocol message.

If MAXTP parameter is not specified in the DFSOTMA descriptor and one or more OTMA members define a MAXTP value, the highest MAXTP value that is specified among the OTMA clients defines only 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 does not prevent the creation of new tpipes, but merely issues message DFS4385W to the MTO and system console. OTMA also warns all OTMA clients with a server state protocol message. 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. OTMA also notifies all OTMA clients with another protocol message.

The /DISPLAY OTMA command and the /DISPLAY TMEMBER command can display the current numbers of tpipes and the DFSOTMA MAXTP value.

Note:

If LITETP=YES, the 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 whether the IMS system reached the maximum tpipe limit.

See the description of the LITETP= parameter in this topic for the calculation of the adjusted tpipe count.

MAXTPBE=YES | NO

Defines the IMS system default for MAXTPBE parameter. The DFSOTMA MAXTPBE value is used by OTMA clients that do not specify MAXTPBE parameter themselves.

MAXTPBE parameter determines whether the number of tpipes in the IMS system must be monitored when this IMS is a shared queues back-end system that processes front-end initiated OTMA input transactions at the application GU time. MAXTPBE parameter applies only when MAXTP parameter is specified. MAXTPBE is ignored if MAXTP value is not specified. The default is YES.

MAXTPRL=

Specifies the relief level for tpipe flood conditions as a percentage of the tpipe count against the DFSOTMA MAXTP value. The DFSOTMA MAXTPRL parameter sets the default for OTMA clients that do not specify a MAXTPRL value themselves.

Valid values are 50 -95. Values specified that are below 50 are set to 50. Values over 95 are set to 95.

The default relief level is 50% of the tpipe MAXTP value.

If LITETP=YES, the relief level is measured as a percentage of the DFSOTMA MAXTP value by using the adjusted tpipe count instead of the regular total tpipe count. See the LITETP= parameter in this topic for the calculation of the adjusted tpipe count.

MAXTPWN=

Specifies the warning level for the tpipe flood conditions as a percentage of the DFSOTMA MAXTP value. The DFSOTMA MAXTPWN parameter sets the default for OTMA clients that do not specify a MAXTP value.

Valid values are 50 - 95. Values specified that are below 50 are set to 50. Values over 95 are set to 95.

The default warning level is 80% of the tpipe MAXTP value.

MDESCMAX

A 3- to 4-digit decimal integer from 255 to 4095 that defines the maximum number of client (type-M) descriptors that can be defined in the DFSYDTx member of the IMS PROCLIB data set.

Any value less than 255 is set to 255. Any 4-digit value greater than 4095 is set to 4095. The default value is 255.

When MDESCMAX parameter is specified, the DFSOTMA descriptor must one of the first 255 type-M descriptors that are defined in the DFSYDTx PROCLIB member.

This parameter is only valid for the DFSOTMA descriptor.

Client descriptors are stored in the extended common storage area (ECSA). The more client descriptors that are defined, the more ECSA storage is used.

MULTIRTP=YES | NO

Specifies the OTMA default for tpipe support of multiple active RESUME TPIPE requests. The DFSOTMA MULTIRTP specification applies only to OTMA clients that do not have a MULTIRTP value specified in their OTMA client descriptor.

When MULTIRTP=YES is specified, by default the tpipes that are created for OTMA clients that connect to this IMS system 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, by default, the tpipes that are created for OTMA clients that connect to this IMS system support only a single 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.

The DFSOTMA MULTIRTP value can be overridden by specifying the MULTIRTP value in the OTMA client descriptors.

TOACEE=NO|YES

Specifies whether OTMA accessor environment element (ACEE) flood control is enabled.

The default value is NO.

If you do not specify this parameter but you specify a value for the ACEEUSR= parameter, IMS automatically sets the value of the TOACEE= parameter to YES.

NO

Specifies that OTMA ACEE flood control is disabled.

YES

Specifies that OTMA ACEE flood control is enabled. If you specify TOACEE=YES, the value that is specified for the ACEEUSR= parameter is used by OTMA to limit the number of RACF user IDs that can have cached ACEEs stored in subpool 249.

After you enable OTMA ACEE flood control, OTMA also checks the expiration values of the least recently used ACEEs every 2 minutes. The ACEEs that expired are cleaned up.

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 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 the TODUMP= parameter is also specified in an OTMA client descriptor, it overrides the value of the DFSOTMA TODUMP= parameter for that OTMA client.

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

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

NO

If NO is specified, the IMS system 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.

WLMLTRM=NO|YES

Specifies whether OTMA needs to pass the input logical terminal (LTERM) override name to IBM Workload Manager to invoke input transactions.

The default value is NO.

NO

Specifies that OTMA passes the input tpipe name to IBM Workload Manager for the input transactions.

YES

Specifies that OTMA passes the input LTERM name to IBM Workload Manager for the input transactions.