Chapter 2: Functions

CTBCMDALLOC

Description

Allocates a command handle.

Syntax

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.

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.

COMMAND

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

Returns

CTBCMDALLOC returns one of the following values listed in Table 2-5.

**Table 2-5: CTBCMDALLOC return values**
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.

Examples

Example 1

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.

Usage

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.