Obtaining a connection handle is an issue specific to Client-Library applications.
When the TM opens a connection to Adaptive Server, the XA Interface allocates a CS_CONNECTION structure for its own use. Once control passes to the application, that application must use the connection handle contained in this structure.
To get the connection handle, specify CS_GET for the cs_object routine’s action parameter with an object type of CS_CONNECTION. cs_object’s objdata parameter returns a structure containing a connection field. This field contains the handle to the CS_CONNECTION structure.
WARNING! The XA Interface also allocates a CS_COMMAND structure whose handle is returned in the command field of the structure to which the objdata parameter points. An application cannot use this command handle, as the XA Interface continues to use this handle, itself.
The following code fragment demonstrates how to retrieve the handle to the CS_CONNECTION structure:
/*
** Arguments:
**connection null-terminated name of the connection
**(ESQL) or LRM connHloaded with the CS_CONNECTION
** handle if the lookup is successful
**
** Returns:
** CS_SUCCEED connection handle found successfully
** CS_FAIL unable to find connection handle for given
** connection /#include <stdio.h> #include <strings.h>
** #include <cspublic.h>CS_RETCODE getConn(connection,
** connH)CS_CHAR connection[128];CS_CONNECTION connH;
{
CS_INT retcode;
CS_CONTEXT *ctx;
CS_OBJNAME name;
CS_OBJDATA data;
CS_THREAD thread_functions;
CS_INT outlen;
#define THREADID_SIZE 8
CS_BYTE thread_id[THREADID_SIZE];
/* Check arguments */
if (strlen(connection) >= 128)
{
/* Connection name is too long */
return(CS_FAIL);
}
/* Get the global context handle */
retcode = cs_ctx_global(CS_VERSION_100, &ctx);
if (retcode != CS_SUCCEED)
{
/* Major environment problems! */
return(CS_FAIL)
}
/*
** Initialize the CS_OBJNAME structure to look
** for the specified connection name.
*/
name.thinkexists = CS_FALSE;
name.object_type = CS_CONNECTNAME;
strcpy(name.last_name, connection);
name.fnlen = CS_UNUSED;
name.lnlen = CS_NULLTERM;
name.scopelen = CS_UNUSED;
/*
** Set the current thread-id so we get the instance of
** this connection that this thread should be using.
*/
retcode = cs_config(ctx, CS_GET,
CS_THREAD_RESOURCE, &thread_functions,
CS_UNUSED, &outlen);
if (retcode != CS_SUCCEED)
{
/*
** Even in an non-threaded environment,this should be
** successful.
*/
return(CS_FAIL);
}
name.thread = (CS_VOID *) thread_id;
retcode = (*thread_functions.thread_id_fn)(
name.thread, THREADID_SIZE,
&name.threadlen);
if (retcode != CS_SUCCEED)
{
return(CS_FAIL);
}
/*
** Initialize the CS_OBJDATA structure to receive the
** connection handle for this connection name
*/
data.actuallyexists = CS_FALSE;
data.connection = (CS_CONNECTION *) NULL;
data.command = (CS_COMMAND *) NULL;
data.buffer = (CS_VOID *) NULL;
data.buflen = CS_UNUSED;
/* Retrieve the connection information */
retcode = cs_objects(ctx, CS_GET, &name,
&data);
if (retcode == CS_SUCCEED)
{
if (data.actuallyexists == CS_TRUE)
{
*connH = data.connection;
return(CS_SUCCEED);
}
else
{
/* No connection by that name exists */
return(CS_FAIL);
}
}
else
{
/*
** The global CS_CONTEXT handle is probably not
** initialized with connection information yet
*/
return(CS_FAIL);
}
}
