Allocates a connection handle.
COPY CTPUBLIC.
01 CONTEXT PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 CONNECTION PIC S9(9) COMP SYNC.
CALL 'CTBCONAL' USING CONTEXT RETCODE CONNECTION.
(I) A context structure. The context structure is defined in the program call CSBCTXALLOC. The context structure corresponds to the IHANDLE in the Open ServerConnect Gateway-Library.
If this value is invalid or nonexistent, CTBCONALLOC fails.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return value,” in this section.
(O) Handle for this connection. All subsequent Client-Library calls using this connection must use this same name in their CONNECTION argument. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
This is the same value used to define the connection to the Open ClientConnect Connection Table.
In case of error, CTBCONALLOC returns LOW-VALUES to this argument.
CTBCONALLOC returns one of the following values listed in Table 3-7.
Value |
Meaning |
|---|---|
CS-SUCCEED (-1) |
The routine completed successfully. |
CS-FAIL (-2) |
The routine failed. The most common reason for a CTBCONALLOC failure is a lack of adequate memory. |
TDS-SOS (-257) |
Memory shortage. The mainframe subsystem was unable to allocate enough memory for the control block that CTBCONALLOC was trying to create. The operation failed. |
TDS-GWLIB-NO-STORAGE (-17) |
Could not get DSA for Gateway-Library. |
The following code fragment demonstrates the use of CTBCONALLOC. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests”.
*========================================================
*== ==
*== Subroutine to process input data ==
*== ==
*========================================================
PROCESS-INPUT.
*********************************
* ALLOCATE A CONNECTION HANDLE. *
*********************************
MOVE ZERO TO CSL-CON-HANDLE.
CALL 'CTBCONAL' USING CSL-CTX-HANDLE
CSL-RC
CSL-CON-HANDLE.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONAL failed' DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*******************
* SET THE USER ID *
*******************
CALL 'CTBCONPR' USING CSL-CON-HANDLE
CSL-RC
CS-SET
CS-USERNAME
PF-USER
PF-USER-SIZE
CS-FALSE
OUTLEN.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONPR for user-id failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
********************
* SET THE PASSWORD *
********************
CALL 'CTBCONPR' USING CSL-CON-HANDLE
CSL-RC
CS-SET
CS-PASSWORD
PF-PWD
PF-PWD-SIZE
CS-FALSE
OUTLEN.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONPR for password failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
********************
* SET THE TRAN NAME *
********************
IF PF-TRAN-SIZE IS NOT EQUAL TO ZEROES THEN
CALL 'CTBCONPR' USING CSL-CON-HANDLE
CSL-RC
CS-SET
CS-TRANSACTION-NAME
PF-TRAN
PF-TRAN-SIZE
CS-FALSE
OUTLEN
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONPR for TRAN name failed'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF
END-IF.
*******************************
* SET THE NET DRIVER PROPERTY *
*******************************
IF PF-NETDRV = SPACES OR PF-NETDRV = 'LU62' X
OR PF-NETDRV = 'lu62'
MOVE CS-LU62 TO NETDRIVER
ELSE
IF PF-NETDRV = 'IBMTCPIP' OR PF-NETDRV = 'ibmtcpip'
MOVE CS-TCPIP TO NETDRIVER
ELSE
IF PF-NETDRV = 'INTERLIN' OR PF-NETDRV = 'interlin'
MOVE CS-INTERLINK TO NETDRIVER
ELSE
IF PF-NETDRV = 'CPIC' OR PF-NETDRV = 'cpic'
MOVE CS-NCPIC TO NETDRIVER
END-IF.
IF PF-DRV-SIZE IS NOT EQUAL TO ZEROES THEN
CALL 'CTBCONPR' USING CSL-CON-HANDLE
CSL-RC
CS-SET
CS-NET-DRIVER
NETDRIVER
CS-UNUSED
CS-FALSE
OUTLEN
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONPR for network driver failed'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF
END-IF.
********************************
* SET FOR MAINFRAME EXTRA INFO *
********************************
CALL 'CTBCONPR' USING CSL-CON-HANDLE
CSL-RC
CS-SET
CS-EXTRA-INF
CS-TRUE
CS-UNUSED
CS-FALSE
CS-UNUSED.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONPR for extra info failed'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
***********************************
* SETUP retrieval of All Messages *
***********************************
CALL 'CTBDIAG' USING CSL-CON-HANDLE,
CSL-RC,
CS-UNUSED,
CS-INIT,
CS-ALLMSG-TYPE,
CS-UNUSED,
CS-UNUSED.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBDIAG CS-INIT failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*********************************************
* set the upper limit of number of messages *
*********************************************
MOVE 5 TO PF-MSGLIMIT.
CALL 'CTBDIAG' USING CSL-CON-HANDLE,
CSL-RC,
CS-UNUSED,
CS-MSGLIMIT,
CS-ALLMSG-TYPE,
CS-UNUSED,
PF-MSGLIMIT.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBDIAG CS-MSGLIMIT failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*************************
* 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.
CTBCONALLOC allocates a connection handle to a Mainframe ClientConnect or another processing region (three-tier processing), or a Adaptive Server if using two-tier (gateway-less) processing.
Before calling CTBCONALLOC, an application must:
Call CSBCTXALLOC to allocate a context structure.
Call CTBINIT to initialize Client-Library.
Connecting to a server is a three-step process. To connect to a server, an application:
Calls CTBCONALLOC to obtain a connection handle.
Calls CTBCONPROPS to set the values of connection-specific properties, if desired.
Calls CTBCONNECT to create the connection and log into the server.
All connections created within a context pick up default property values from the parent context. An application can override these default values by calling CTBCONPROPS to set property values at the connection level.
An application can have multiple connections to one or more servers at the same time.
For example, an application can simultaneously have two connections to the server “mars,” one connection to the server “venus,” and one connection to a separate transaction processing region named CICX3. The context property CS-MAX-CONNECT, set by CTBCONFIG, determines the maximum number of connections allowed per context.
Each server connection requires a separate connection handle.
In order to send requests to a server, one or more command handles must be allocated for a connection. CTBCMDALLOC allocates a command handle.
Related functions
