Errors

This section is divided as follows:

Error Handlers

Error Codes

DB Link API Codes and Messages Table

Function Codes

SQLSTATE

Error Messages

Error Origin

Erroneous IldDbms and IldRequest Objects

Error Handlers

In the process of exchanging information with a database system, there are numerous opportunities for errors. These can be raised by DB Link, by the client API of the RDBMS, or even by the database server.

DB Link implements error handlers to catch errors. All IldDbms and IldRequest objects must have an attached IldErrorReporter object. In fact, when IldDbms and IldRequest objects are created, an error handler is automatically attached. However, you can change the default error handler for an object of a class derived from IldErrorReporter.

Note: It is not possible to access the default reporter. Thus, when no reporter has been set by the application, although the functionIldIldBase::getErrorReporter returns null, a reporter is actually set.

Platforms: When using Sybase, your application must not replace the message or error handlers by the Sybase library routine ct_callback with the parameter CS_CLIENTMSG_CB or CS_SERVERMSG_CB. Such a call made by your application would break the error handling mechanism of DB Link. The same problem occurs with MS SQL Server and the DB Library functions dberrhandle and dbmsghandle. Your application must conform to the protocol defined in Customizing the Error Handling Mechanism.

Error Codes

DB Link defines error codes associated with error messages. Some of these codes correspond to anomalies detected by the library. Additionally, there are error codes and messages corresponding to those raised within an RDBMS itself. DB Link provides the necessary interface for your application to recover gracefully (whenever possible) from these two kinds of errors in the class IldErrorReporter.

Error codes returned by the member function IldIldBase::getErrorCode may originate from DB Link or from the RDBMS. You cannot tell the origin of the error from that number only, because DB Link error codes are negative, just like most RDBMS error codes.

However, you can differentiate between them through the error origin: the function IldIldBase::getErrorOrigin returns IldDblink if the error was trapped by the DB Link API, or IldRDBMServer if the error was trapped by the server. Moreover, Sybase allows you to distinguish the errors raised in the server from those raised in the client API: for the latter, the origin is of type IldClientAPI.

DB Link API Codes and Messages Table

The following table gives you a list of all error messages generated by the DB Link API together with the corresponding error codes. The reasons for the errors are also included.

Error Codes and Messages
Error Code (Symbol)	Error Message (String)	Comment
ILD_ALREADY_CONNECTED	Current object is already connected	This error can be raised by the function IldDbms::connect if an active connection is already open.
ILD_BAD_COLUMN_INDEX	Bad column index	This error is raised by the function IldRequest::getColName when the column descriptor has no name or the given index is out of bounds.
ILD_BAD_COLUMN_NAME	Bad column name	This error is raised by the function IldRequest::getColIndex when no column with the given name is found in the results set descriptors.
ILD_BAD_DB_SPEC	Bad format for database specification	This error is raised at connection time when the given connection string does not match the RDBMS-specific format requested.
ILD_BAD_EXECUTE_COUNT	Bad count for execute function	This error is raised when the function IldRequest::execute is called for a prepared query whose second argument is greater than the size of the bind array.
ILD_BAD_FILE	File cannot be opened for write operation	This error is raised by the function IldRequest::getLargeObject when the file indicated by the fileName argument is write-protected.
ILD_BAD_VARIABLE_SIZE	Bad size for variable being bound	This error is raised when binding a column with a byte size that is too small for the data type used.
ILD_CANNOT_RESIZE_TUPLE	Cannot resize tuple	This error is raised while describing a results set or binding a parameter when an internal allocation failed
ILD_CBCK_INIT	Callback initialization failed	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_CON_ALLOC	Connection allocation failed	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_CON_INIT	Connection initialization failed	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_CTXT_ALLOC	Context allocation failed	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_CTXT_INIT	Context initialization failed	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_DATE_CONVERT	Date conversion failed	This error is raised when a conversion fails, either from the RDBMS internal format to a date value or, conversely, from a date value to the RDBMS internal format.
ILD_DBMS_FATAL_ERROR	Fatal Dbms error	This error is raised after an unrecoverable error occurs. After the error is raised, the connection is in an unpredictable state and must not be reused. The IldDbms object must be destroyed.
ILD_DBMS_NOT_CONNECTED	Dbms is not connected	This error is raised each time a function from the class IldDbms is called while the connection is closed.
ILD_IGN_EXT_ROWS	Extra row(s) ignored	WARNING ONLY This is a warning emitted by member functions such as IldRequest::getLargeObject when the given condition is not restrictive enough and several rows are returned.
ILD_INVALID_HANDLE	Invalid handle	This error is raised when the underlying control structure used to communicate with the server is out of order.
ILD_INVALID_PARAMETER	Data exception, invalid parameter value	This error is raised when a function of DB Link is called with an invalid value. For example, the userCallBack parameter (which is the user function called when the event occurs) in the IldDbms::subscribeEvent function can not be null. If it is, the program will crash when the event occurs.
ILD_INVALID_SEQUENCE	Calling this function is not allowed at this time	This error is raised when a function is called when some other function should have been called prior to this one.
ILD_LIB_MSMTCH	Library mismatch	If your application was linked in dynamic mode, this error is raised when the driver manager finds a library with the right name but with no proper entry point.
ILD_LIB_NLNKD	RDBMS library not linked	If your application was linked in static mode, this error is raised when the target RDBMS library has not been linked or the RDBMS name is not recognized.
ILD_LOCK_NAME_MISMATCH	Lock name mismatches	This error can be raised only when an attempt is made to unlock an IldRequest object using the wrong name or an empty name for the lock to be released.
ILD_MAX_CURS_LEN	Cursor name truncated	WARNING ONLY This warning is raised when the name passed for a cursor is too long for the target RDBMS.
ILD_MEMORY_EXHAUSTED	Memory exhausted	This error is raised when an allocation fails.
ILD_NO_DYN_LIB	Dynamic library not found	If your application was linked in dynamic mode, this error is raised when the driver manager cannot find the designated driver library.
ILD_NO_HANDLER	Error handler not called	This error can be raised only within a connection to Sybase. If such an error occurs, contact customer support.
ILD_NO_MORE_TUPLES	No more tuples	This error is raised when an accessor to column data is used and no row has been returned from the server.
ILD_NO_REPORTER	Error reporter cannot be null	This error is raised by the functions IldDbms::setErrorReporter and IldRequest::setErrorReporter when the argument passed is null.
ILD_NOT_IMPLEMENTED	Not implemented for current RDBMS	This error is raised when an attempt is made to use a functionality that cannot be implemented for the target RDBMS.
ILD_NOT_SCROLL_MODE	Scrollable cursor mode must be activated	This error is raised when an attempt is made to use the function IldRequest::fetchScroll in the following context: A value of the fetchOrientation parameter is different from IldFetchDirectionNext. Scrollable cursor mode is not activated (see member function IldRequest::setScrollable).
ILD_NUM_CONVERT	Numeric conversion failed	This error is raised when a conversion fails, either from the RDBMS internal format to a numeric value or, conversely, from a numeric value to the RDBMS internal format.
ILD_OFFSET	Offset	INFORMATION ONLY This is not an error but merely part of an error message.
ILD_OUT_OF_RANGE	Index out of range	This error is raised when an attempt is made to bind an output column using an index greater than the actual number of columns in the results set.
ILD_RDBMS_CONN	Must give RDBMS name and connection string	This error is raised when trying to create an IldDbms object and either the RDBMS name or the connection string was null or started with a null character.
ILD_REQUEST_REQUIRED	IldRequest object missing	This error can be raised only when connected to Sybase, or MS SQL Server. With these RDBMSs, the transaction-handling IldDbms functions require that a valid IldRequest object be passed.
ILD_TYPE_MISMATCH	Value accessor mismatch	This error is raised if an output or input column is bound to a type, in the DB Link sense, that is not possible or not allowed by the configuration settings (for example, binding a column to IldDateType while the IldRequest object is set to use the “date as object” feature).
ILD_UNCHGEABLE	Cannot modify a server initialization parameter	This error can be raised only within a connection to Oracle, when an attempt is made to modify the request time-out.
ILD_UNDEF_LINK_MODE	Unknown DB Link driver linkage mode	The application must be linked with either the dblnkdyn or dblnkot library. If none is used, this error is raised when trying to allocate a connection.
ILD_UNKN_ERRMSG	Unknown error message	REPLACEMENT MESSAGE This is a replacement message, not an error. It is raised when the RDBMS API fails to give the proper message for an error.
ILD_UNKNOWN_CODE	Unknown error code	This error is raised when a function call to the underlying RDBMS API returns an unexpected value. If such an error occurs, contact customer support.
ILD_UNKNOWN_ENTITY	Unknown relation	This error is raised when a schema entity description is not available because it does not exist in the database.
ILD_UNKNOWN_RDBMS	Unknown RDBMS	This error is raised when an IldDbms object is created and the given RDBMS name is not recognized by the driver manager. It can be raised only if the application is linked in dynamic mode.
ILD_UNKNOWN_TYPE	Unknown column type	This error is raised if an attempt is made to bind an output column or an input parameter to a type that is not supported for the target RDBMS.
ILD_USING_ERROR_DBMS	Using Error Dbms object	This error is raised by any function of the class IldDbms when this function is used against an object that was not properly built. This occurs when an error is raised because an error occurred when the IldDbms object is created or when the initial connection is processed.
ILD_USING_ERROR_REQUEST	Using Error Request object	This error is raised by any function of the class IldRequest when the object has not been allocated properly, usually because the attached IldDbms object has not been connected to the server.

Function Codes

Each documented function has a unique identifier whose symbolic name mimics its name. For example, the identifier for the function IldDbms::disconnect is ILD_D_DISCONNECT. These identifiers are defined by the enumeration type IldFuncId in the file ild.h, under the section “Db Link Function Ids.”

SQLSTATE

Whenever the RDBMS gives access to the SQLSTATE value, DB Link registers that value. The text of the SQLSTATE message can be retrieved using the member function IldIldBase::getErrorSqlstate. The content of the text is volatile —that is, it may be overwritten by other data. Therefore, you must copy it if you want to keep a trace of the error.

Error Messages

The text of an error message can be retrieved using the member function IldIldBase::getErrorMessage. The content of the text is volatile, that is, it may be overwritten by other data. Therefore, you must copy it if you want to keep a trace of the error.

For error message strings, see Error Codes and Messages.

Error Origin

The enumeration type IldErrorOrigin indicates the various sources of errors: DB Link itself, the client API of the RDBMS, or the database server.

Depending on the layer in which the error was raised, DB Link sets the error origin to a different value of IldErrorOrigin.

enum IldErrorOrigin {

IldUnknownOrigin,

IldDbLink,

IldClientAPI,

IldRDBMServer

};

When the error is raised by an DB Link function, the origin is set to IldDbLink.

Platforms: When connected to a Sybase server, the origin will be set to IldClientAPI if the CLIENT callback has been activated. Otherwise, it is set to IldRDBMServer.

Erroneous IldDbms and IldRequest Objects

If a very serious error is raised when an object is created, the return value you receive may be of the class IldErrorDbms or IldErrorRequest (instead of the object you expect).

Instances of these classes will never process any SQL statement. They always raise an error, either ILD_USING_ERROR_DBMS or ILD_USING_ERROR_REQUEST.

ILD_USING_ERROR_DBMS: An erroneous connection object is returned only when an IldDbms object cannot be allocated.

ILD_USING_ERROR_REQUEST: An erroneous request object is returned only when you try to get a new IldRequest object even though the related IldDbms object is not connected.

Caution: You must explicitly delete these erroneous objects.