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.

See also

“Error handling”.