Allocates a command handle.
COPY CTPUBLIC.
01 CONNECTION PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 COMMAND PIC S9(9) COMP SYNC.
CALL 'CTBCMDAL' USING CONNECTION RETCODE COMMAND.
(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 “Return value,” in this section.
(O) Variable where this newly-allocated command handle is returned. All subsequent client requests using this connection must use this same name in the COMMAND argument. The command handle also corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
In case of error, CTBCMDALLOC returns LOW-VALUES to this argument.
CTBCMDALLOC returns one of the following values listed in Table 3-5.
Value |
Meaning |
|---|---|
CS-SUCCEED (-1) |
The routine completed successfully. |
CS-FAIL (-2) |
The routine failed. The most common reason for a CTBCMDALLOC 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 CTBCMDALLOC was trying to create. The operation failed. |
The following code fragment demonstrates the use of CTBCMDALLOC. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”
*========================================================
*== ==
*== Subroutine to allocate, send, and process commands ==
*== ==
*========================================================
SEND-COMMAND.
*--------------------------------------------------------------
* find out what the maximum number of connections is
*--------------------------------------------------------------
CALL 'CTBCONFI' USING CSL-CTX-HANDLE,
CSL-RC,
CS-GET,
CS-MAX-CONNECT,
CF-MAXCONNECT,
CF-FOUR,
CS-FALSE,
CF-OUTLEN.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCONFI CS-GET failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*--------------------------------------------------------------
* allocate a command handle
*--------------------------------------------------------------
CALL 'CTBCMDAL' USING CSL-CON-HANDLE,
CSL-RC,
CSL-CMD-HANDLE.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCMDAL failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*--------------------------------------------------------------
* prepare the language request
*--------------------------------------------------------------
MOVE CF-LANG2-SIZE TO PF-STRLEN.
CALL 'CTBCOMMA' USING CSL-CMD-HANDLE,
CSL-RC,
CS-LANG-CMD,
CF-LANG2,
PF-STRLEN,
CS-UNUSED.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBCOMMA CS-LANG-CMD failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
*-------------------------------------------------------------
* send the language request
*-------------------------------------------------------------
CALL 'CTBSEND' USING CSL-CMD-HANDLE,
CSL-RC.
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CTBSEND failed' DELIMITED BY SIZE
INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF.
SEND-COMMAND-EXIT.
EXIT.
CTBCMDALLOC allocates a command handle on a specified connection. A command handle is a control structure that a Client-Library application uses to send requests to a server and process the results. Together, command and connection handles perform the functions of the Open ServerConnect TDPROC structure.
Before calling CTBCMDALLOC, an application must allocate a connection structure via the Client-Library routine CTBCONALLOC.
An application must call CTBCMDALLOC once for each logical command it issues. Each SQL statement is considered a separate logical command. For batched SQL, call CTBCMDALLOC once for each batch.
Related functions
Related documentation
Mainframe Connect Client Option and Server Option Messages and Codes
