Errors and Warnings > Errors
 
Errors
This section is divided as follows:
*Error Handlers
*Error Codes
*Rogue Wave 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 Rogue Wave® DB Link, by the client API of the RDBMS, or even by the database server.
Rogue Wave 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 function IldIldBase::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 Rogue Wave 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 Rogue Wave DB Link or from the RDBMS. You cannot tell the origin of the error from that number only, because Rogue Wave 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 Rogue Wave 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.
Rogue Wave DB Link API Codes and Messages Table
The following table gives you a list of all error messages generated by the Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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 Rogue Wave 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, Rogue Wave 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 Table 6.1.
Error Origin
The enumeration type IldErrorOrigin indicates the various sources of errors: Rogue Wave DB Link itself, the client API of the RDBMS, or the database server.
Depending on the layer in which the error was raised, Rogue Wave 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 Rogue Wave 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.
Warning:  You must explicitly delete these erroneous objects.
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.