Before Release 6.4, the loss of a network connection (because of a problem in the network, the WSH, or the server) caused another problem from which it was hard to recover. The application would hang indefinitely, while the client waited for a response from the WSH. This problem was not limited to API calls that received data, such as tpgetreply or tprecv. It occurred in all API calls to the WSH except tpbegin and function calls for buffer allocation.
Release 6.4 provides a solution to this problem. It allows you to:
With these features, you can ensure that the WSH client no longer hangs indefinitely when a network connection is lost.
This chapter describes these features and provides instructions for using them.
Keep-alive is a networking operation that periodically checks the viability of a network connection between WSH and a /WS client if no traffic has occurred over that connection within an operating system specified time period.
Keep-alive works through a new administrative option to the WSL: -K. This option requests periodic checking of the viability of a connection on which no traffic has occurred within a specified amount of time. (This amount of time is specified in the operating system.) This option improves the speed and reliability of network failure detection, by actively testing an idle connections's state at the protocol stack level. The -K option can be set to client, handler, or both.
If the -K client option is used, keep-alive messages are generated from the client machines. If the keep-alive is not acknowledged, the network is considered down by the client machine. Subsequent ATMI calls fail with a tperrno of TPESYSTEM.
If the -K handler option is used, keep-alive messages are generated from the handler machine. If the keep-alive is not acknowledged, the network is considered down by the handler machine. The handler can then clean up the entry associated with that client. This reduces the possibility that the handler will exhaust its mpx-factor (as specified by -x) with stale clients.
If the -K both option is used, keep-alive messages are generated from both the client and handler machines.The availability and timeout thresholds for this feature are determined by tunable parameters in the operating system.
The keep-alive operation is supported only on platforms on which the BEA TUXEDO System uses sockets:
The Keep-alive Operation
How Keep-alive Works
Limitations
You cannot use this option on any other platform. BEA TUXEDO lets you specify the -K option for any server machine, but it will not execute it properly on any platform other than those previously listed. If you try to perform a keep-alive operation on any other platform, your attempt fails and a message is written to the userlog (once per process for the WSH). Processing continues normally:
To use the keep-alive operation in your BEA TUXEDO application, edit the UBBCONFIG file as follows.
How to Use Keep-alive
The /WS client
client
The WSH
handler
Both /WS client and WSH
both
Neither the /WS client nor the WSH
none (the default)
To Activate Keep-alive For
Select
Your entry should look like the following.
WSL SRVGRP="WSLGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-A -- -n 0x0002ffffaaaaaaaa -d /dev/tcp -K both"
-K turns on the KEEPALIVE checking on both the /WS client and the server side.
Note:
For details about the format of a WSL entry, see WSL(5) in the BEA TUXEDO Reference Manual.
Note: Any time-out period that you specify applies to the entire system. Remember that if, with one application in mind, you later change the amount of time specified, any other application that uses keep-alive is also affected.
Network time-out is an option that lets you decide how long you are willing to wait for an operation in a /WS client before your request for that operation is cancelled (times out) on a network.
The -N option uses a network time-out to receive data in the /WS client.
The network time-out option establishes a wait period (in seconds) for any BEA TUXEDO operation in the /WS client that receives data from the network. If the period is exceeded, the operation fails and the client is disconnected from the application. A value of 0 (the default) indicates no time-out.
Note: Setting this value too low may cause too many disconnects.
For a network time-out to receive data in the /WS client, a new administrative option is added to the WSL: -N. Each ATMI call returns an error if the time-out occurs. When the link times out, the application is notified. An existing error code is used and the new error detail indicates the specific error. Once a network time-out occurs, the status of any outstanding operations is in doubt. Transactions cannot be completed; incoming replies can be lost, and so on. The only safe action is to terminate the connection to the application by doing the equivalent of a tpterm but without communicating with the WSH. By the time the operation returns, the client is no longer part of the BEA TUXEDO application. The application needs to join the application again in one of two ways:
tpinit()
To use the network time-out function in your BEA TUXEDO application, edit the UBBCONFIG file as follows.
How to Use Network Time-out
This section provides additions to the T_WSL Class Definition section of the WS_MIB(5) entry in the BEA TUXEDO Reference Manual.
Here you can turn on the network keep-alive operation for the client, the handler, or both. You may also turn off this option for both the client and handler by specifying none.
Changes to the value of this attribute affect only newly established connections.
The value of TA_NETTIMEOUT is the minimum number of seconds that should be allowed for a workstation client to wait to receive a response from the WSL/WSH. A value of 0 indicates no network time-out.
Changes to the value of this attribute affect only newly established connections.
The -K and -N options are ignored by clients configured with releases of BEA TUXEDO earlier than Release 6.4. To use the /WS time-out feature, a /WS client must be upgraded to Release 6.4 or later.
The -K (keep-alive) option is supported only on platforms on which the BEA TUXEDO System uses sockets:
You cannot use this option on any other platform. BEA TUXEDO lets you specify the -K option for any server machine, but it will not execute it properly on any platform other than those previously listed. If you try to perform a keep-alive operation on any other platform, your attempt fails and a message is written to the userlog (once per process for the WSH). Processing continues normally.
The -N option for /WS client network time-out is supported on all platforms except Mac. Mac /WS clients are disconnected if this feature is enabled. To support both non-Mac clients with this option and Mac clients without this option, it is necessary to configure more than one WSL.
Updates to the ATMI Manual Pages
For the Errors Section
[TPESYSTEM]: tperrordetail is set to TPED_TERM.