Chapter 3: Functions

cs_ctx_alloc

Description

Allocates a context structure.

Syntax

CS_RETCODE cs_ctx_alloc(version, context);
CS_INT     version;
CS_CONTEXT **context;

Parameters

version

(I) Version of Client-Library behavior that the application expects. Table 3-21 lists the symbolic values that are legal for version.

**Table 3-21: Values of *version* with cs_ctx_alloc**
Value	Indicates	Supported features
CS_VERSION_46	Communicates with SQL Server release 4.6.	RPCs. This is the initial version of Client-Library.
CS_VERSION_50	Communicates with SQL Server release 10.0 and above.	RPCs.

context: (O) Variable where a pointer to this newly-allocated context structure is returned. This is the name used by ct_init when it initializes Client-Library.

Returns

cs_ctx_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 cause for a cs_ctx_alloc failure is a lack of available memory.

Value

Meaning

CS_SUCCEED (-1)

The routine completed successfully.

CS_FAIL (-2)

The routine failed.

The most common cause for a cs_ctx_alloc failure is a lack of available memory.

Examples

Example 1

The following code fragment demonstrates how cs_ctx_alloc works with other functions to initialize a program. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”

  	/*------------------------------------------------------------------*/
  	/* program initialization                                           */
  	/*------------------------------------------------------------------*/
         memset (msgtext1, ' ', text_size);
         strncpy (msgtext2, "Press Clear To Exit", text_size);
         page_cnt  = page_cnt + 1;
         memset(servname, ' ', 30);
         memset(username, ' ', 8);
         memset(tran, ' ', 8);
         memset(pwd, ' ', 8);
         memset(driver, ' ', 9);
  
         for (i = 0; i < 14; ++i)
            memset (RS[i].rsltno, ' ', text_size); /* init output
 lines  */
  
         /*  get system time   */
         EXEC CICS ASKTIME ABSTIME(UTIME);
  
         EXEC CICS FORMATTIME
                   ABSTIME(UTIME)
                   DATESEP('/')
                   MMDDYY(TMP_DATE)
                   TIME(TMP_TIME)
                   TIMESEP ;
  
         display_initial_screen ();
         get_input_data ();
  
  /*------------------------------------------------------------------*/
  /* Allocate a context structure                                     */
  /*------------------------------------------------------------------*/
  
      if (no_input == FALSE)
      {
         version = CS_VERSION_50;
  
         rc = cs_ctx_alloc (version, &context);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CSCTXALLOC failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
            EXEC CICS RETURN ;
         }

  /*------------------------------------------------------------------*/
  /* Initialize the Client-Library                                    */
  /*------------------------------------------------------------------*/
  
         /* context allocated, it's now OK to use ct_diag for message
            retrieving                                                */
         diag_msgs_initialized = 1;
		rc = ct_init (context, version);
  
         if (rc == CS_SUCCEED)
         {
            proces_input ();
         }
         else
         {
            strncpy (msgstr, "CT_INIT failed", msg_size);
            no_errors_sw = FALSE ;
            error_out (rc);
         }
         close_connection ();
         quit_client_library ();
      }  /* process input data entered */
  
      else  /* no input data received */
         EXEC CICS RETURN ;
  
  }   /* end main */

Usage

cs_ctx_alloc allocates a context structure.
A context structure contains information that describes an application context. For example, a context structure defines the version of Client-Library that is in use.
Allocating a context structure is the first step in any Client-Library application.
After allocating a context structure, a Client-Library application typically customizes the context by calling cs_config and/or ct_config, then sets up one or more connections within the context.
To deallocate a context structure, an application calls cs_ctx_drop.