Timeout Considerations for EntireX Broker

This document describes the timeout settings for EntireX Broker and covers the following topics:

Timeout Units

The timeout duration can be specified in seconds (S), minutes (M) or hours (H), for example 100M. If no unit is specified, the default is seconds.

Timeout Settings

Timeout Setting Description
Client Non-activity Timeout

Any broker stub application that issues a LOGON but does not issue a REGISTER is a client. During logon, broker allocates resources to each client and keeps them available to the client until the client application issues a LOGOFF. A client is considered inactive when it is not issuing a broker request. A typical example of a broker request by a client is the SEND function.

The CLIENT-NONACT value defines the maximum period of time a client can remain inactive. See CLIENT-NONACT under Broker Attributes. If the client continues to be inactive beyond this period of time, Broker releases all the resources allocated to this client. This time is a global attribute, applicable to all clients of the Broker.

Server Non-activity Timeout

Any broker stub application that issues a LOGON and also issues a REGISTER is a server. During logon and registration, broker allocates resources to each server, and keeps them available to the server until the server issues a DEREGISTER and LOGOFF. A server is considered inactive when it is not issuing a broker request. A typical example of a Broker request by a server is the RECEIVE function.

The SERVER-NONACT value defines the maximum period of time a server can remain inactive. See SERVER-NONACT under Broker Attributes. If the server continues to be inactive beyond this period of time, Broker releases all the resources allocated to this server. This time is a per-service attribute, and can vary from one service definition to another. All servers, registered to the same service, inherit the same SERVER-NONACT time. If a server registers to more than one service, the highest SERVER-NONACT value is taken as the non-activity time period.

Conversation Non-activity Timeout

A conversation begins when a client successfully sends a message addressed to a server. The Broker allocates a unique conversation, even before the server receives this message. Broker also allocates resources to manage each conversation. A conversation remains active as long as messages are being exchanged with this conversation ID. The conversation remains inactive as long as neither a client nor a server makes a Broker request, referencing this conversation ID. The resources allocated to a conversation are freed when either a client or a server issues EOC.

The CONV-NONACT value defines the maximum period of time a conversation can remain inactive. If the conversation continues to be inactive beyond this period of time, Broker releases all the resources allocated to this conversation.

UOW Lifetime (UWTIME)

Each UOW has a lifetime value associated with it. This is the time that a UOW is allowed to exist without being completed. A UOW is completed when it is successfully

  • either cancelled or backed out by its sender

  • or cancelled or committed by its receiver.

If a UOW is in ACCEPTED status when this lifetime expires, the UOW is placed into a timeout status. Lifetime timeouts will not occur when the UOW is in either RECEIVED or DELIVERED status. See CONV-NONACT description in Relationship between Timeout Values.

Transport Timeouts

If Entire Net-Work is used to transmit a Broker request, the setting of the Entire Net-Work NODE statement parameter REPLYTIM may influence the behavior of the application (see your Entire Net-Work documentation for details). All non-activity timeouts in the Broker configuration should be considered when determining the maximum time. This maximum time should be less than the value defined for REPLYTIM in the Entire Net-Work configuration.

Relationship between Timeout Values

The interdependency between different timeouts is described as follows:

UOW Messages

  • A server or a client engaged in a conversation will not be timed out until the UOW that they are handling times out. CLIENT-NONACT (or SERV-NONACT) has no effect if it is shorter than UWTIME.

  • A conversation may time out earlier than either the client or the server. When an existing conversation times out, the participating server and client can start a new conversation. We recommend you set the CONV-NONACT shorter than CLIENT-NONACT (or SERV-NONACT).

  • If either the client or server times out before the conversation does, the conversation does not continue, that is, it reaches end of conversation (EOC). Nevertheless, the surviving participant (client or server) can continue and receive any unread messages.

  • When a conversation times out, Broker checks for the status of all UOWs in this conversation. Any UOW with status RECEIVED or DELIVERED is backed out and enters into ACCEPTED status. "Accepted" means that the UOW can be received by anyone (with CONV-ID=NEW), and that the conversation has lost the link to the consumer of the UOW.

    Note:
    The link to the consumer is lost only for the first UOW in a conversation when the status changes to ACCEPTED; with subsequent UOWs, the link is not lost.

  • A common relationship between these three timeout values is as follows, although this may not be the optimum combination in all situations:

    UWTIME > SERV-NONACT > CLIENT-NONACT > CONV-NONACT

    In common situations, this combination will achieve optimal resource consumption without recourse to repeatedly restarting applications.

Non-UOW Messages

Timeout behavior remains the same as in UOW messages, except that UWTIME (UOW lifetime attribute) is not applicable here. The optimal hierarchy between the three timeout values is shown below:

SERV-NONACT > CLIENT-NONACT > CONV-NONACT

Timeout-related Error Messages

When any client or server or conversation times out, the Broker does not immediately notify the application. The application receives notification when it makes its next Broker request. The following are the error messages commonly associated with the respective timeouts. The errors listed below can occur in the case of blocked and non-blocked ACI calls. A blocked call is one in which the ACI field WAIT is set to either "YES" or a non-zero numeric value.

See message 00740074.

CLIENT-NONACT

In the following errors, it is assumed that client only has timed out, while the server and conversation are active.

Error Number Error Text Explanation
00020002 User does not exist When the timed out client tries to make a Broker request.
00030012 EOC due to LOGOFF of partner The surviving partner (server) receives this error when attempting to receive on a conversation which is closed because the client has timed out. If there are any unread messages, the server successfully receives them.

SERV-NONACT

In the following errors, it is assumed that only the server has timed out, while the client and conversation are active.

Error Number Error Text Explanation
00020002 User does not exist When the timed out client tries to make a Broker request.
00030067 Partner timeout occurred The surviving partner (client) receives this error when attempting to send on a conversation which is closed because the server timed out.

CONV-NONACT

It is assumed that server and client are active.

Error Number Error Text Explanation
00030003 No matching conversation found When either a server or a client attempts a new Broker request affecting this timed out conversation.
00030073 Conversation timeout occurred When both client and server are already engaged in a conversation, and the conversation time out without the partner issuing any Broker request.

Special Case for UOW Messages

UOWs involved in a conversation, and which are in DELIVERED state, revert to ACCEPTED state when the conversation times out. UOWs in ACCEPTED state are no longer bound to a server nor to an existing conversation. Therefore, UOW in ACCEPTED state is part of a new conversation that is available to any server.