CTBCMDALLOC

Description

Allocates a command handle.

Syntax

%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);

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 “Returns,” 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 zeroes to this argument.

Returns

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

Table 3-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 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 ;

Usage

See also

Related functions: