Initializes Client-Library.
CS_RETCODE ct_init (connection, version); CS_CONTEXT *context; CS_INT version;
(I) A context structure. The context structure is defined in the program call cs_ctx_alloc. If this value is invalid or nonexistent, ct_init fails.
(I) Version of Client-Library behavior that the application expects. The following table lists the symbolic values that are legal for version.
Value |
Meaning |
Supported features |
|---|---|---|
CS_VERSION_46 |
Application communicates with a version 4.6 SQL Server. |
RPCs. |
CS_VERSION_50 |
Application communicates with a version 10.0 SQL Server and above. |
RPCs. |
ct_init returns one of the following values listed in Table 3-9.
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_MEM_ERROR (-3) |
The routine failed due to a memory allocation error. |
CS_FAIL (-2) |
The routine failed for other reasons.
|
TDS_INVALID_PARAMETER (-4) |
A parameter contains an illegal value. The most likely cause is an erroneous version number. |
TDS_WRONG_STATE (-6) |
Program is in the wrong communication state to issue this call. The most likely cause is that this context was already initiated. |
The following code fragment demonstrates how ct_init is used with other functions to initialize a program. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
ct_init returns CS_FAIL
if Client-Library cannot provide version-level behavior.
/*------------------------------------------------------------------*/
/* 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 */
ct_init initializes Client-Library. It sets up internal control structures and defines the version of Client-Library behavior that an application expects. Client-Library provides the requested behavior, regardless of the actual version of Client-Library in use.
ct_init must be the first Client-Library routine call after cs_ctx_alloc. Other Client-Library routines fail if they are called before ct_init.
Because an application calls ct_init before it sets up error handling, an application must check the ct_init return code to detect failure.
It is not an error for an application to call ct_init multiple times. Some applications cannot guarantee which of several modules executes first. In such a case, each module should contain a call to ct_init.
Related functions
