ct_debug

Description

Manage debug library operations.

Syntax

CS_RETCODE ct_debug(context, connection, operation,
                  flag, filename, fnamelen)
 
 CS_CONTEXT           *context;
 CS_CONNECTION    *connection;
 CS_INT                      operation;
 CS_INT                      flag;
 CS_CHAR                  *filename;
 CS_INT                      fnamelen;

Parameters

context

A pointer to a CS_CONTEXT structure. A CS_CONTEXT structure defines a Client-Library application context.

When operation is CS_SET_DBG_FILE, context must be supplied and connection must be NULL.

When setting or clearing flags, see Table 3-16 to determine whether or not to supply context.

connection

A pointer to a CS_CONNECTION structure. connection must point to a valid CS_CONNECTION structure, but no actual connection to a server is necessary to enable debug operations.

When operation is CS_SET_PROTOCOL_FILE, connection must be supplied and context must be NULL.

When setting or clearing flags, see Table 3-16 to determine whether or not to supply connection.

operation: The operation to perform. Table 3-17 lists the symbolic values for operation.

flag

A bitmask representing debug subsystems. The following table lists the symbolic values that can make up flag:

**Table 3-16: Values for ct_debug flag parameter**
Value	Required	Resulting Client-Library behavior
CS_DBG_ALL	context and connection	Takes all possible debug actions.
CS_DBG_API_ LOGCALL	context	Prints out information each time the application calls a Client-Library routine, including the routine name and the parameter values.
CS_DBG_API_STATES	context	Prints information relating to Client-Library function-level state transitions.
CS_DBG_ASYNC	context	Prints function trace information each time an asynchronous function starts or completes.
CS_DBG_DIAG	connection	Prints message text whenever a Client-Library or server message is generated.
CS_DBG_ERROR	context	Prints trace information whenever a Client-Library error occurs. This allows a programmer to determine exactly where an error is occurring.
CS_DBG_MEM	context	Prints information relating to memory management.
CS_DBG_NETWORK	context	Prints information relating to Client-Library’s network interactions.
CS_DBG_PROTOCOL	connection	Captures information exchanged with a server in protocol-specific (for example, TDS) format. This information is not human-readable.
CS_DBG_PROTOCOL_ STATES	connection	Prints information relating to Client-Library protocol-level state transitions.

filename: The full path and name of the file to which ct_debug should write the generated debug information.

fnamelen: The length, in bytes, of filename, or CS_NULLTERM if filename is a null-terminated string.

Returns

ct_debug returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

        ...CODE DELETED.....

         #ifdef EX_API_DEBUG

/*

             ** Enable this function right before any call to

             ** Client-Library that is returning failure.

*/

             retcode = ct_debug(*context, NULL, CS_SET_FLAG,

                 CS_DBG_API_STATES, NULL, CS_UNUSED);

             if (retcode != CS_SUCCEED)

                 ex_error("ex_init: ct_debug() failed");

         #endif

         ...CODE DELETED.....

This code excerpt is from the exutils.c example program.

Usage

**Table 3-17: Summary of ct_debug parameters**
Value of operation	flag is	filename is	Result
CS_SET_FLAG	Supplied	NULL	Enables the subsystems specified by flag.
CS_CLEAR_FLAG	Supplied	NULL	Disables the subsystems specified by flag.
CS_SET_DBG_FILE	CS_UNUSED	Supplied	Records the name of the file to which it will write character-format debug information.
CS_SET_PROTOCOL_FILE	CS_UNUSED	Supplied	Records the name of the file to which it will write protocol-format debug information.

ct_debug manages debug library operations, allowing an application to enable and disable specific diagnostic subsystems and send the resultant trace information to files.
ct_debug functionality is available only from within the debug version of Client-Library. When called from within the standard Client-Library, it returns CS_FAIL.
Some debug flags can be enabled only at the connection level, while others can be enabled only at the context level. Table 3-16 indicates the level at which each flag can be enabled.
If an application does not call ct_debug to specify debug files, ct_debug writes character-format debug information to stdout (where available) and protocol-form debug information to connect.dat in the application’s working directory.
When the debug version of Client-Library is linked in with an application, the following behaviors automatically take place:
- Memory reference checks: Client-Library verifies that all memory references, both internal and application-specific, are valid.
- Data structure validation: each time a Client-Library function accesses a data structure, Client-Library first validates the structure.
- Special assertion checking: Client-Library checks that all array references, including strings, are in bounds.
Because the debug version of Client-Library performs extensive internal checking, application performance will decrease when the debug library is in use. The level of performance decrease depends on the type and number of tracing subsystems that are enabled. To minimize performance decrease, an application programmer can selectively enable tracing subsystems, limiting heavy tracing to problem areas of code.
Use of the debug library will change the behavior of asynchronous applications that are experiencing timing problems. In this case, the use of external tracing tools (for example, a network protocol analyzer) is recommended.