UciConnect

Open UCM Connection (Client)

UciConnect(L)

Name Environment Synopsis Description Diagnostics Notes See also Examples

Name

UciConnect

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciConnect" USING UCI-PAR
UCI-ADDR.

Description

UciConnect creates a socket connection to the server process identified by the UCI-SERVICE and UCI-HOST fields of the UCI-ADDR parameter structure. The UCI-HOST argument represents the TCP/IP address or host name on which the server process providing the UCI-SERVICE is located. When using the symbolic host name, it must be defined in /etc/hosts or the Windows hosts file. The UCI-SERVICE field identifies the service that the socket will be assigned to. It may be given as symbolic TCP/IP service name or as numeric port number. When using the symbolic service name, it must be defined in /etc/services or the Windows services file with type ftp. Normally, the next UCI function used after UciConnect is UciWrite. There is no need to call UciOpen on the new socket, since UciConnect performs all nescessary initialization tasks. Upon successful execution, UciConnect stores the resulting socket number in the UCI-SOCKET field of the UCI-PAR structure. The same UCI-PAR structure should be used in all subsequent function calls that address the new socket.

The UciClose function closes the socket that has been opened by UciConnect. In order to allow correct socket housekeeping, this call is mandatory.

UciConnect will fail if one or more of the following is true:

UE_NOTINIT	The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).
UE_INVALID	Invalid argument (2).
UE_HOST	The value UCI-HOST does not identify a known host (6).
UE_SERVICE	The value UCI-SERVICE does not identify a known service (7).
UE_BADSOCK	The operating system returned a bad status while creating a new socket (3).
UE_CONNECT	The given UCI-HOST does not provide the requested UCI-SERVICE (8).
UE_NOMEM	The new socket could not be entered into the internal database, due to low memory (99).
UE_NOMSG	The initialization handshaking with the server failed (5).
UE_ULMEXP	The UCM license has expired. This error may occur in demo versions only (21).
UE_ULMBUSY	Too many users. The UCM license does not allow additional users at this time. Please consult Unitec for details on how to increase your license (22).

Diagnostics

Upon successful completion UciConnect returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

Notes

As described under UciOpen, a program may use the system(3) function (CreateProcess on Win32 platforms) to spawn another task that itself uses the same socket number. Each of these tasks should use their own UciInit, UciOpen, UciClose and UciTerm sequence.

It is possible for a client process, to maintain connections to several different servers at any time. Each of these connections shoult then be identified by an unique UCI-PAR structure, which must be passed to the send, receive and close functions of the socket in question.