Diagnostic Messages

A diagnostic message is returned with each SQLSTATE. The same SQLSTATE is often returned with a number of different messages. For example, SQLSTATE 42000 (Syntax error or access violation) is returned for most errors in SQL syntax. However, each syntax error is likely to be described by a different message.

Sample diagnostic messages are listed in the Error column in the table of SQLSTATEs in Appendix A and in each function. Although drivers can return these messages, they are more likely to return whatever message is passed to them by the data source.

Applications generally display diagnostic messages to the user, along with the SQLSTATE and native error code. This helps the user and support personnel determine the cause of any problems. The component information embedded in the message is particularly helpful in doing this.

Diagnostic messages come from data sources and components in an ODBC connection, such as drivers, gateways, and the Driver Manager. Typically, data sources do not directly support ODBC. Consequently, if a component in an ODBC connection receives a message from a data source, it must identify the data source as the source of the message. It must also identify itself as the component that received the message.

If the source of an error or warning is a component itself, the diagnostic message must explain this. Therefore, the text of messages has two different formats. For errors and warnings that do not occur in a data source, the diagnostic message must use the format:

[vendor-identifier][ODBC-component-identifier]component-supplied-text

For errors and warnings that occur in a data source, the diagnostic message must use the format:

[vendor-identifier][ODBC-component-identifier][data-source-identifier]data-source-supplied-text

The following table shows the meaning of each element.

Element

Meaning

vendor-identifier	Identifies the vendor of the component in which the error or warning occurred or that received the error or warning directly from the data source.
ODBC-component- identifier	Identifies the component in which the error or warning occurred or that received the error or warning directly from the data source.
data-source-identifier	Identifies the data source. For file-based drivers, this is typically a file format, such as Xbase. [1] For DBMS-based drivers, this is the DBMS product.
component-supplied-text	Generated by the ODBC component.
data-source-supplied- text	Generated by the data source.

[1] In this case, the driver is acting as both the driver and the data source.

Brackets ([ ]) must be included in the message and do not indicate optional items.