Obtaining a Client-Library connection handle

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.

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);
}
}