|
|
Synopsis Environment
Description Diagnostics
Notes See also
Examples |
Synopsis |
#include "ucm.h" int UcmCntl(sock, cmd,
[arg...]);
T_SOCKET sock;
int cmd; |
Environment |
Unix, Win32
|
Description |
UcmCntl allows to get or change control variables of
an open socket sock. Data type and value of argument arg are dependent on
the command cmd. The symbolic names for all possible commands are defined in the
header ucm.h. The following values for cmd and the operations they specify
are available:
| UC_IFLUSH |
Discard all messages currently available through socket sock (input
flush). The argument arg has no significance and may be omitted. |
| UC_TIMEOUT |
Sets the timeout for subsequent UcmRecv
calls with the UF_TIMEOUT flag on the given sock to (int) arg1 seconds and
(int) arg2 milliseconds. Both arguments must be specified.
The default timeout values value after UcmConnect are zero.
The return value of this command is the timeout value setting in seconds for the socket
before the call. |
| UC_KEEPALIVE |
Causes the process to send heart beat messages to
clients. This command
should only be used in server processes. A server typically spends most of its time in the
UcmRecv function, waiting for client
requests.
If the client crashes or a network error occurs the server has no way of knowing
this. In
several TCP/IP implementations even a send operation will not return a bad status in such
situations. Since Unitec has found the standard SO_KEEPALIVE socket
option not to work correctly on many systems, the UC_KEEPALIVE command has been
implemented in the UCM transport layer of Release 2.0. After (int)
arg1 seconds without receiving any client requests, the internal logic of UcmRecv
will post a transparent probe packet. Event driven clients (i.e. clients built with the UCM
Active-X control) will automatically respond to such messages. After (int) arg2
unsuccessful retries, the server considers the client to have crashed and returns an
UE_CONNECT error to the caller of the receive function. Non event driven clients need to
call their own UcmRecv function in order to catch probe
packets. Since
such programs typically spend most of their time waiting for user input, we discourage the
use of UC_KEEPALIVE, to prevent the server process to wrongly assume that the connection
has broken. You may want to set the standard SO_KEEPALIVE socket option in these
environments:
T_SOCKET sock;
int one = 1;
...
UcmOpen(sock);
setsockopt(sock, SOL_SOCKET, SO_KEEPALIVE, (char *) &one, sizeof(one));
... |
Normally a server process reading from a broken communication link does not impact
system performance. The UC_KEEPALIVE settings should therefore be chosen
conservatively, e.g. 120 seconds, 15 retries. |
UcmCntl will fail if one or more of the following is true:
| UE_NOTINIT |
The UCM software has not been initialize (see UcmInit) |
| UE_INVALID |
Invalid argument. |
| UE_BADSOCK |
The value sock does not identify an open socket. |
|
Diagnostics |
Upon successful completion UcmCntl returns
UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the
error (see exception below).
| UC_TIMEOUT |
previous timeout value (seconds) |
|
Notes |
The UC_KEEPALIVE feature should only used with UCM
client software of release 2.0 or higher. The UcmClientVersion
function may be used to obtain client version information.
|
See also |
UcmInitComm
|
Examples |
#include
"ucm.h"
T_SOCKET sock;
...
UcmInit();
UcmOpen(sock);
UcmCntl(sock, UC_KEEPALIVE, 120, 10);
...
UcmCntl(sock, UC_IFLUSH);
UcmClose(sock);
UcmTerm(); |
|
|
|
