Connects to a server.
%INCLUDE CTPUBLIC;
DCL 01 CONNECTION FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 SERVERNAMECHAR(10) INIT(‘yourserver ’) 01 SERVERNAME_LEN FIXED BIN(31); 01 BUFBLANKSTRIP FIXED BIN(31); CALL CTBCONNE (CONNECTION, RETCODE, SERVERNAME, SERVERNAME_LEN, BUFBLANKSTRIP);
(I) Handle for this connection. This connection handle must already be allocated with CTBCONALLOC. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(I) Name of the connected server. For clients running SNA, this is the name by which the server is known to the Open ClientConnect Server Path Definition Table. For clients running TCP/IP without a gateway, this is the actual name of the Adaptive Server in the LAN interfaces file.
You must assign a value to this argument. If a server name is not specified, CTBCONNECT fails.
(I) Length, in bytes, of SERVERNAME. If the server name ends at the last non-blank character, assign CS_TRUE to BUFBLANKSTRIP.
(I) Blank stripping indicator. Indicates whether trailing blanks are stripped.
Assign this argument one of the following symbolic values:
Value |
Meaning |
|---|---|
CS_TRUE (1) |
Trailing blanks are stripped. The value in the buffer ends at the last non-blank character. |
CS_FALSE (0) |
Trailing blanks are not stripped. They are included in the value. |
CTBCONNECT returns one of the following values listed in Table 3-8.
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS_CRTABLE_UNAVAILABLE (-31) |
The Connection Router table cannot be loaded. |
The following code fragment demonstrates how to use CTBCONNECT. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------*/
/* open connection to the server or CICS region */
/*------------------------------------------------------------*/
CALL CTBCONNE( CSL_CON_HANDLE,
CSL_RC,
PF_SERVER,
PF_SERVER_SIZE,
CS_FALSE ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONNECT failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* invokes SEND_COMMAND routine */
/*------------------------------------------------------------*/
IF NO_ERRORS_SW
THEN
CALL SEND_COMMAND ;
CTBCONNECT establishes a connection between a mainframe transaction processing region and a remote server. Information about the connection is stored in a connection handle, which uniquely identifies the connection.
The remote server can be another transaction processing region or server (Adaptive Server, Open Server, and so on). For clients running SNA, the name in the Server Path Definition Table is the name of the remote region or server. For clients running TCP/IP, SYGWHOST (server name and IP address) is used in conjunction with the MVS-side information file for the specific drive or the CICS partner table.
When it establishes a connection, CTBCONNECT sets up communication with the server, forwards login information, and communicates any connection-specific property information to the server.
Because creating a connection involves sending login information, an application must define login parameters (server user ID and password) before calling CTBCONNECT. An application calls CTBCONPROPS to define login parameters.
The maximum number of open connections per context is determined by the CS_MAX_CONNECT property (set by CTBCONFIG). The default maximum is 25 connections.
There are two ways that an attempt to establish a connection can fail (assuming that the system is correctly configured):
If the specified server machine (the machine on which the server resides) is running correctly and the network is running correctly, but no server is listening on the specified port, the specified server machine signals the client, through a network error, that the connection cannot be formed. Regardless of the login time-out value, the connection fails.
If the machine on which the server resides is down, the server does not respond. Because “no response” is not considered to be an error, the network does not signal the client that an error occurred. However, if a login time-out period is set, a time-out error occurs when the client fails to receive a response within the set period.
To close a connection, an application calls CTBCLOSE.
Related functions:
Related topics:
