Allocates a context structure.
CS_RETCODE cs_ctx_alloc(version, context); CS_INT version; CS_CONTEXT **context;
(I) Version of Client-Library behavior that the application expects. Table 3-21 lists the symbolic values that are legal for version.
Value |
Indicates |
Supported features |
|---|---|---|
CS_VERSION_46 |
Communicates with SQL Server release 4.6. |
RPCs.
|
CS_VERSION_50 |
Communicates with SQL Server release 10.0 and above. |
RPCs. |
(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.
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. |
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.”
This is the initial version of Client-Library.
/*------------------------------------------------------------------*/
/* 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 */
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.
Related functions
