Chapter 2: Functions

CTBCONNECT

Description

Connects to a server.

Syntax

COPY CTPUBLIC.

01 CONNECTION              PIC S9(9) COMP SYNC.
01 RETCODE                 PIC S9(9) COMP SYNC.
01 SERVERNAME              PIC X(30). 
01 SERVERNAME-LEN          PIC S9(9) COMP SYNC.
01 BUFBLANKSTRIP           PIC S9(9) COMP SYNC.

CALL 'CTBCONNE' USING CONNECTION RETCODE SERVERNAME SERVERNAME-LEN BUFBLANKSTRIP.

Parameters

CONNECTION: (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.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return value,” in this section.

SERVERNAME

(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.

SERVERNAME-LEN: (I) Length, in bytes, of SERVERNAME. If the server name ends at the last non-blank character, assign CS-TRUE to BUFBLANKSTRIP.

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.

Returns

CTBCONNECT returns one of the following values listed in Table 2-8.

**Table 2-8: CTBCONNECT return values**
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.
TDS-INVALID-NAMELENGTH	The length specified for the server name is invalid.
TDS-EXCEED-MAX-CONN (-39)	The maximum number of connections is already open.
TDS-ROUTE-NOT-AVAILABLE (-34)	All paths are in use; no more paths are available.
TDS-ROUTE-NOT-FOUND (-33)	No such route is defined to the Connection Router.
TDS-NOT-INITIALIZED (-32)	The Connection Router has not initialized.
TDS-SERVER-NOT-FOUND (-30)	The specified server name could not be found in the Name Server.
TDS-WRONG-STATE (-6)	Program is in the wrong communication state to issue this call.

Examples

Example 1

The following code fragment demonstrates the use of CTBCONNECT. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”

	 *************************
	 * CONNECT TO THE SERVER *
	 *************************
	CALL 'CTBCONNE' USING CSL-CON-HANDLE
                                  CSL-RC
                                  PF-SERVER
                                  PF-SERVER-SIZE
                                  CS-FALSE.
            IF CSL-RC NOT EQUAL CS-SUCCEED
              THEN
                 MOVE SPACES TO MSGSTR
                 STRING 'CTBCONNE failed' DELIMITED BY SIZE INTO MSGSTR
                 PERFORM PRINT-MSG
                 PERFORM ALL-DONE
            END-IF.
            IF NO-ERRORS
              THEN
                PERFORM SEND-COMMAND
            END-IF.

Usage

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 either 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.
You can find more information about defining servers and connections in the Mainframe Connect Client Option Installation and Administration Guide.