ct_cmd_alloc

Description

Allocates a command handle.

Syntax

CS_RETCODE ct_cmd_alloc(connection, command);
CS_CONNECTION *connection;
CS_COMMAND    **command;
CS_INT        type;

Parameters

connection: (I) Handle for this SNA connection. This connection handle must already be allocated with ct_con_alloc. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.

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, ct_cmd_alloc returns zeroes to this argument.

Returns

ct_cmd_alloc returns one of the following values:

Value	Meaning
CS_SUCCEED (-1)	The routine completed successfully.
CS_FAIL (-2)	The routine failed. The most common reason for act_cmd_alloc 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 ct_cmd_alloc was trying to create. The operation failed.

Value

Meaning

CS_SUCCEED (-1)

The routine completed successfully.

CS_FAIL (-2)

The routine failed.

The most common reason for act_cmd_alloc 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 ct_cmd_alloc was trying to create. The operation failed.

Examples

Example 1

The following code fragment demonstrates how ct_cmd_alloc is used during program initialization. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”

/*-------------------------------------------------------------*/
/* Open connection to the server or CICS region                */
/*-------------------------------------------------------------*/
  
         rc = ct_connect (connection, servname, server_size);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_CONNECT failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  
  /*------------------------------------------------------------*/
  /* Invokes SEND_COMMAND routine                               */
  /*------------------------------------------------------------*/
         if (no_errors_sw)
            send_command ();
  
  /*------------------------------------------------------------*/
  /* Process the results of the command                         */
  /*------------------------------------------------------------*/
  
         if (no_errors_sw)
         {
            while (no_more_results == FALSE)
               proces_results ();
         }
  }   /* end proces_input */
  
  /********************************************************************/
  /*                                                                  */
  /* Subroutine to allocate, send, and process commands               */
  /*                                                                  */
  /********************************************************************/
  void send_command ()
   {
   CS_INT        rc;
   CS_INT        *outlen;
   CS_INT        buf_len;
   CS_CHAR       sql_cmd[45];

	/*------------------------------------------------------------*/
	/* Find out what the maximum number of connections is         */
	/*------------------------------------------------------------*/
          rc = ct_config (context, CS_GET, CS_MAX_CONNECT,
                         &maxconnect, CS_FALSE, outlen);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_CONFIG failed", msg_size);
            strncpy (msgtext2, "Please press return to 
            continue!", text_size);
            error_out(rc);
  
            /* reset program flags to move on with the task */
            print_once = TRUE;
            diag_msgs_initialized = TRUE;
            strncpy(msgtext2, "Press Clear To Exit", text_size);
         }
  /*------------------------------------------------------------*/
  /* Allocate a command handle                                  */
  /*------------------------------------------------------------*/
           rc = ct_cmd_alloc (connection, &cmd);
           if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_CMDALLOC failed", msg_size);
            no_errors_sw = FALSE ;
            error_out(rc);
         }
  /*------------------------------------------------------------*/
  /* Prepare the language request                               */
  /*------------------------------------------------------------*/
         strcpy(sql_cmd,
                 "SELECT FIRSTNME, EDUCLVL FROM SYBASE.SAMPLETB");
         buf_len = sizeof(sql_cmd);
         rc = ct_command(cmd, (long) CS_LANG_CMD, sql_cmd,
                         buf_len, (long) CS_UNUSED);
          if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_COMMAND failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }

	/*-------------------------------------------------------------*/
	/* Send the language request                                   */
	/*-------------------------------------------------------------*/
         rc = ct_send (cmd);
  
         if (rc != CS_SUCCEED)
         {
            strcpy (msgstr, "CT_SEND failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }
  }   /* end send_command */

Usage

ct_cmd_alloc 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 ct_cmd_alloc, an application must allocate a connection structure via the Client-Library routine ct_con_alloc.
An application must call ct_cmd_alloc once for each logical command it issues. Each SQL statement is considered a separate logical command. For batched SQL, call ct_cmd_alloc once for each batch.