ct_debug

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;

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	This ct_debug parameter may be set without devlib libraries. The parameter captures information exchanged with a server in protocol-specific (for example, TDS) format. This information is not human-readable.
CS_DBG_PROTOCOL_ FILE	connection	This ct_debug parameter may be set without devlib libraries. If the parameter is not set on connection, mktemp is called, generating a unique file name to dump the protocol packets into. The prefix string passed to mktemp is capture. The resulting protocol file is decodable by Ribo.
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.

        ...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.....

• 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:

  • On Windows: capXXXX.tmp where XXXX is a unique code.

  • On Unix: captureXXXXXX where XXXXXX is a unique code.

  These files are found 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.

See also

“Error handling”, “Enabling debugging”.

---

Copyright © 2008. Sybase Inc. All rights reserved.

View this document as PDF