Allocates a command handle.
%INCLUDE CTPUBLIC;
DCL 01 CONNECTION FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31); 01 COMMAND FIXED BIN(31) INIT(0); CALL CTBCMDAL (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 “Returns,” 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 zeroes 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 how CTBCMDALLOC is used during program initialization. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/ /* */ /* Subroutine to allocate, send, and process commands */ /* */ /*------------------------------------------------------------------*/ SEND_COMMAND: PROC ; /*------------------------------------------------------------*/ /* find out what the maximum number of connections is */ /*------------------------------------------------------------*/ CALL CTBCONFI( CSL_CTX_HANDLE, CSL_RC, CS_GET, CS_MAX_CONNECT, CF_MAXCONNECT, STG(CF_MAXCONNECT), CS_FALSE, CF_OUTLEN ) ; IF CSL_RC ^= CS_SUCCEED THEN DO ; MSGSTR = 'CTBCONFIG failed' ; NO_ERRORS_SW = FALSE ; CALL ERROR_OUT; CALL ALL_DONE ; END ; /*------------------------------------------------------------*/ /* display number of connections */ /*------------------------------------------------------------*/ OR2_MAXCONNECT = CF_MAXCONNECT; /*------------------------------------------------------------*/ /* allocate a command handle */ /*------------------------------------------------------------*/ CALL CTBCMDAL( CSL_CON_HANDLE, CSL_RC, CSL_CMD_HANDLE ) ; IF CSL_RC ^= CS_SUCCEED THEN DO ; MSGSTR = 'CTBCMDALLOC failed' ; NO_ERRORS_SW = FALSE ; CALL ERROR_OUT; CALL ALL_DONE ; END ; /*------------------------------------------------------------*/ /* prepare the language request */ /*------------------------------------------------------------*/ PF_STRLEN = STG(CF_LANG2 ) ; CALL CTBCOMMA( CSL_CMD_HANDLE, CSL_RC, CS_LANG_CMD, CF_LANG2, PF_STRLEN, CS_UNUSED ) ; IF CSL_RC ^= CS_SUCCEED THEN DO ; MSGSTR = 'CTBCOMMAND failed' ; NO_ERRORS_SW = FALSE ; CALL ERROR_OUT; CALL ALL_DONE ; END ;
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: