Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Error handling

Extended error data

Extended error data

Some server messages have extended error data associated with them. Extended error data is simply additional information about the error.

For Adaptive Server messages, the additional information is usually which column or columns provoked the error.

Client-Library makes extended error data available to an application in the form of a parameter result set, where each result item is a piece of extended error data. A piece of extended error data may be named and can be of any datatype.

An application can retrieve extended error data but is not required to do so.

Applications that allow end users to enter or edit data often need to report errors to their users at the column level. The standard server message mechanism, however, makes column-level information available only within the text of the server message. Extended error data provides a means for applications to conveniently access column-level information.

For example, imagine an application that allows end users to enter and edit data in the titleauthor table in the pubs2 database. titleauthor uses a key composed of two columns, au_id and title_id. Any attempt to enter a row with an au_id and title_id that match an existing row will cause a "duplicate key" message to be sent to the application.

On receiving this message, the application needs to identify the problem column or columns to the end user, so that the user can correct them. This information is not available in the duplicate key message, except in the message text. The information is available, however, as extended error data.

Not all server messages provide extended error data. When Client-Library returns standard server message information to an application in a CS_SERVERMSG structure, it sets the CS_HASEED bit of the status field of the CS_SERVERMSG structure if extended error data is available for the message.

Extended error data is returned to an application in the form of a parameter result set that is available on a special CS_COMMAND structure that Client-Library provides.

To retrieve extended error data, an application processes the parameter result set.

Within a server message callback routine, an application retrieves the CS_COMMAND with the extended error data by calling ct_con_props with property as CS_EED_CMD:

CS_RETCODE      ret;

 CS_COMMAND      *eed_cmd;

 CS_INT          outlen;

ret = ct_con_props(connection, CS_GET, CS_EED_CMD,

     &eed_cmd, CS_UNUSED, &outlen);

ct_con_props sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.

Once it has the CS_COMMAND, the callback routine processes the extended error data as a normal parameter result set, calling ct_res_info, ct_describe, ct_bind, ct_fetch, and ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the callback routine to call ct_results.

An application that is handling server messages inline retrieves the CS_COMMAND with the extended error data by calling ct_diag with operation as CS_EED_CMD:

CS_RETCODE      ret;

 CS_COMMAND      *eed_cmd;

 CS_INT          index;

ret = ct_diag (connection, CS_EED_CMD,

     CS_SERVERMSG_TYPE, index, &eed_cmd);

In this call, type must be CS_SERVERMSG_TYPE and index must be the index of the message for which extended error data is available. ct_diag sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.

Once it has the CS_COMMAND, the application processes the extended error data as a normal parameter result set, calling ct_res_info, ct_describe, ct_bind, ct_fetch, and ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the application to call ct_results.