Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 3 Routines

ct_diag

Usage

Usage

• A Client-Library application can handle Client-Library and server messages in two ways:

  • The application can call ct_callback to install client message and server message callbacks to handle Client-Library and server messages.

  • The application can handle Client-Library and server messages inline, using ct_diag.

  An application can switch back and forth between the two methods. For information about how to do this, see "Error handling".

• ct_diag manages inline message handling for a specific connection. If an application has more than one connection, it must make separate ct_diag calls for each connection.

• An application cannot use ct_diag at the context level. That is, an application cannot use ct_diag to retrieve messages generated by routines that take a CS_CONTEXT (and no CS_CONNECTION) as a parameter. These messages are unavailable to an application that is using inline error handling.

• An application can perform operations on either Client-Library messages, server messages, or both.

  For example, an application can clear Client-Library messages without affecting server messages by using:

  ct_diag(connection, CS_CLEAR, CS_CLIENTMSG,

           CS_UNUSED, NULL);

• ct_diag allows an application to retrieve message information into standard Client-Library structures (CS_CLIENTMSG and CS_SERVERMSG) or a SQLCA, SQLCODE, or SQLSTATE. When retrieving messages, ct_diag assumes that buffer points to a structure of the type indicated by type.

  An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE must set the Client-Library property CS_EXTRA_INF to CS_TRUE. This is because the SQL structures require information that is not ordinarily returned by Client-Library's error handling mechanism.

  An application that is not using the SQL structures can also set CS_EXTRA_INF to CS_TRUE. In this case, the extra information is returned as standard Client-Library messages.

• If ct_diag does not have sufficient internal storage space in which to save a new message, it throws away all unread messages and stops saving messages. The next time it is called with operation as CS_GET, it returns a special message to indicate the space problem. After returning this message, ct_diag starts saving messages again.

• To initialize inline error handling, an application calls ct_diag with operation as CS_INIT.

• Generally, if a connection will use inline error handling, the application should call ct_diag to initialize inline error handling for a connection immediately after allocating it.

• To clear message information for a connection, an application calls ct_diag with operation as CS_CLEAR.

  • To clear Client-Library messages only, an application passes type as CS_CLIENTMSG_TYPE.

  • To clear server messages only, an application passes type as CS_SERVERMSG.

  • To clear both Client-Library and server messages, pass type as SQLCA_TYPE, SQLCODE_TYPE, SQLSTATE_TYPE, or CS_ALLMSG_TYPE.

• If type is not CS_ALLMSG_TYPE:

  • ct_diag assumes that buffer points to a structure whose type corresponds the value of type.

  • ct_diag clears the *buffer structure by setting it to blanks and/or NULLs, as appropriate.

• Message information is not cleared until an application explicitly calls ct_diag with operation as CS_CLEAR. Retrieving a message does not remove it from the message queue.

• To retrieve message information, an application calls ct_diag with operation as CS_GET, type as the type of structure in which to retrieve the message, index as the one-based index of the message of interest, and *buffer as a structure of the appropriate type.

• If type is CS_CLIENTMSG_TYPE, then index refers only to Client-Library messages. If type is CS_SERVERMSG_TYPE, index refers only to server messages. If type has any other value, index refers to the collective "queue" of both types of messages combined.

• ct_diag fills in the *buffer structure with the message information.

• If an application attempts to retrieve a message whose index is higher than the highest valid index, ct_diag returns CS_NOMSG to indicate that no message is available.

• For information about these structure, see:

  • "SQLCA structure"

  • "SQLCODE structure"

  • "SQLSTATE structure"

  • "CS_CLIENTMSG structure "

  • "CS_SERVERMSG structure"

• Applications running on platforms with limited memory may want to limit the number of messages that Client-Library saves.

• An application can limit the number of saved Client-Library messages, the number of saved server messages, and the total number of saved messages.

• To limit the number of saved messages, an application calls ct_diag with operation as CS_MSGLIMIT and type as CS_CLIENTMSG_TYPE, CS_SERVERMSG_TYPE, or CS_ALLMSG_TYPE:

  • If type is CS_CLIENTMSG_TYPE, then the number of Client-Library messages is limited.

  • If type is CS_SERVERMSG_TYPE, then the number of server messages is limited.

  • If type is CS_ALLMSG_TYPE, then the total number of Client-Library and server messages combined is limited.

  • When a specific message limit is reached, Client-Library discards any new messages of that type. When a combined message limit is reached, Client-Library discards any new messages. If Client-Library discards messages, it saves a message to this effect.

  • An application cannot set a message limit that is less than the number of messages currently saved.

  • Client-Library's default behavior is to save an unlimited number of messages. An application can restore this default behavior by setting a message limit of CS_NO_LIMIT.

• To retrieve the number of current messages, an application calls ct_diag with operation as CS_STATUS and type as the type of message of interest.

• To retrieve a pointer to the CS_COMMAND structure containing extended error data (if any), call ct_diag with operation as CS_EED_CMD and type as CS_SERVERMSG_TYPE. ct_diag sets *buffer to the address of the CS_COMMAND structure containing the extended error data.

• When an application retrieves a server message into a CS_SERVERMSG structure, Client-Library indicates that extended error data is available for the message by setting the CS_HASEED bit in the status field in the CS_SERVERMSG structure.

• It is an error to call ct_diag with operation as CS_EED_CMD when extended error data is not available.

• For more information about extended error data, see "Extended error data".

• If an application is using sequenced error messages, ct_diag acts on message chunks instead of messages. This has the following effects:

  • A ct_diag(CS_GET, index) call returns the message chunk with number index.

  • A ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library stores.

  • A ct_diag(CS_STATUS) call returns the number of currently stored chunks, not the number of currently stored messages.

• For more information about sequenced messages, see "Sequencing long messages ".