APPC/MVS uses the VTAM APPCCMD macro to communicate with partner applications. Sometimes a VTAM APPCCMD request does not complete, for example because of a network delay or a delay at the partner LU. If this happens, the APPC/MVS transaction program can hang while waiting for control to be returned by APPC/MVS. By setting a time limit for VTAM APPCCMD requests, you can avoid such hangs and regain control of the conversation.

If the time limit is reached before the VTAM APPCCMD request completes and returns control to APPC/MVS, the conversation will be terminated by APPC/MVS and the caller of the conversation callable service will regain control. If the conversation call was issued with a Notify_Type=ECB (asynchronous processing), the specified ECB will be posted when the time limit is reached.

To set a time limit, use the Set_TimeOut_Value service or either the Timeout_Value_Minutes or Timeout_Value_Seconds parameter on the new version of the Allocate service (ATBALC6).

You can invoke the Set_Timeout_Value service any time after the conversation is successfully established. You can also invoke the Set_Timeout_Value service to alter a previously set timeout value. All subsequent APPC/MVS or CPIC callable services will be limited to the timeout values specified on the Set_Timeout_Value or allocate call.

At any time your program wishes to query the timeout value that is currently set for a conversation, use the Get_Attributes service (ATBGTA6). The combined values, in the form of seconds, of the Timeout_Value_Minutes and Timeout_Value_Seconds will be returned.

You can use the Version_Service to determine whether Set_Timeout_Value or the new version of the Allocate service is available on the current system. An application can invoke Set_Timeout_Value or a version of Allocate which supports specifying the timeout value when the Callable_service_version_number returned from the Version_Service is 5 or higher. With a version number of 5, the application specifies the value in minutes. If the value is 6 or higher, the application specifies the timeout value at the minute and/or second level, providing greater granularity in the timeout value specified.

If a conversation is terminated during time-out processing, any subsequent APPC/MVS or CPIC callable service will fail with a Program_Parameter_Check return code.

If an error occurs, invoke the Error_Extract service to get a detailed description of the error. If API trace was started for the application, then a detailed error message will also be captured in the trace data set.

When a distributed transaction calls the Commit or Backout service, it enters a syncpoint processing phase. During this time, APPC effectively takes over the existing conversations which connect the nodes of the distributed transaction. APPC uses those conversations to exchange various syncpoint messages. Time-out processing is disabled for all message exchanges during syncpoint processing. A hang at one of the nodes during syncpoint processing will therefore hang the entire distributed transaction. For more information, see ATBST05 - Set_TimeOut_Value (For OS/390 Release 8 through z/OS V1R6).