Error Handling |

< > Table of Contents

All InstantSQL statements return a value in sql-Return (defined in the copy file lisqldef.cpy) indicating the status of the statement execution. This return code value would normally be set to 0 (Sql-OK) or, after an SQL FETCH ROW statement detects the end of the result set, 1 (Sql-EndOfData). Any other return code value indicates an error has occurred. The return code value gives an indication of the type of error. The copy file lisqldef.cpy associates a set of condition-names with sql-Return for the various return code values.

To retrieve further information, the SQL DESCRIBE ERROR statement can be used. Where the error was raised internally within InstantSQL, the type of error will be set to "I" and the message will contain a description of the error. Where the error was raised from an ODBC call, the type of error will be set to "O" and the full contents of the error returned from ODBC will be returned. It is possible that an InstantSQL statement will cause multiple error messages. Therefore, if the full information is required, SQL DESCRIBE ERROR should be repeatedly performed until the return code value sets Sql-EndOfData to true.

Return code values are generally ordered with less severe errors having lower values than more severe errors. During development of an application that uses InstantSQL, it can be helpful to configure DisplayErrorMessageLevel to a low number. This will cause InstantSQL to display an message box for each error that occurs where the return code value of the error is greater than or equal to the configured value. (See the topic InstantSQL Configuration for more information on configuring InstantSQL.)

Return code values are as follows:

#### Condition-Name | Value | Description
sql-OK | 0 | The statement completed successfully. However, there can be ODBC informational messages available to SQL DESCRIBE ERROR.
sql-EndOfData | 1 | An SQL FETCH ROW statement has detected the end of the query result set; or, an SQL DESCRIBE ERROR statement has reached the end of the stored errors for the preceding statement. This return value is informative and no error entry is added to the error array for retrieval by the SQL DESCRIBE ERROR statement. ODBC 3 drivers may also return end of data when an SQL START QUERY statement executes an SQL searched UPDATE or DELETE statement that affects no rows in the data source.
sqe-ODBCInfo | 1001 | The statement completed successully, but there are ODBC informational messages available. This return code value only occurs when the configuration option ReturnInfoErrorCode is set to true.
sqe-DataTruncation | 2001 | The statement resulted in data being truncated when transferring data between the COBOL program and the data source.
sqe-DataConvError | 2002 | The statement caused a data conversion error when transferring data between the COBOL program and the data source. In some cases, data conversion errors are caused by data truncation errors.
sqe-LenIndConvError | 2003 | The statement caused a data conversion error when transferring the length indicator value between the COBOL program and the data source.
sqe-ConnectionFailed | 2004 | The SQL CONNECT DATASOURCE statement failed to connect to the data source because the ODBC connection request failed. This is usually the result of an incorrect data source name or incorrect login information. The specific cause should be explained by the ODBC errors in the error array for the statement.
sqe-QueryFailed | 2005 | An SQL PREPARE QUERY statement failed (probably because of an error in the supplied SQL statement text string) or one of the browse queries failed (probably because the ODBC driver does not support the catalog function necessary to do the browse query).
sqe-BadHandleValue | 2101 | The supplied input connection or query handle value does not correspond to a valid connection or query. For connection handles, this probably means the connection was not successfully completed or has been subsequently disconnected. For query handles, this probably means the query was not successful or has been dropped.
sqe-BadColumnNumberValue | 2102 | The supplied column number value does not correspond to a column in the query result set. Result columns are numbered left to right starting from 1. The maximum column number is the number of columns in the query result set.
sqe-BadColumnNameValue | 2103 | The supplied column name value does not match any column name in the query result set. If the configuration option MatchNameCase is set to true, column names must match in case as well as spelling.
sqe-BadParamNumberValue | 2104 | The supplied parameter number value does not correspond to a parameter in the query. Parameters are numbered from left to right starting with 1. The maximum parameter number is the number of parameter markers in the SQL statement text string.
sqe-BadSQLTypeValue | 2106 | The supplied SQL data type value is not supported by the data source.
sqe-BadParamIOTypeValue | 2107 | The supplied parameter input-output type value is not sql-Input, sql-Output or sql-Input-Output.
sqe-BadDateValue | 2108 | The supplied date value does not correspond to a date in the Gregorian calendar, contains characters other than decimal digits, or is not an integer.
sqe-BadTimeValue | 2109 | The supplied time value does not correspond to a valid time, contains characters other than decimal digits, or is not an integer.
sqe-BadTimestampValue | 2110 | The supplied timestamp value does not correspond to a valid timestamp. The date portion or the time portion of the timestamp is incorrect, as described for the date (2108)and time (2109) errors.
sqe-ConnectionLimitHit | 2111 | The program has tried to connect to a data source when the maximum number of connections has been reached.
sqe-QueryLimitHit | 2112 | The program has tried to create a query when the maximum number of queries has been reached.
sqe-QueryNotStarted | 2120 | An SQL FETCH ROW statement has been executed for a query that has not yet been started. This error will also occur if the query has been started, but has subsequently been ended with an SQL END QUERY statement that specifies the sql-Close option and has not been re-started yet.
sqe-NoRowFetched | 2121 | An SQL GET DATA statement has been executed when a row from the query result set has not been successfully fetched with an SQL FETCH ROW statement.
sqe-ParamNotBound | 2122 | An SQL START QUERY statement has been executed when one or more parameters have not yet been bound with the SQL BIND PARAMETER statement.
sqe-SQLStringTooLarge | 2125 | An SQL CONSTRUCT QUERY statement has resulted in an SQL statement text string longer than the COBOL data item supplied to receive the string.
sqe-BadTxnIsolationValue | 2126 | The supplied transaction isolation value does not correspond to a valid transaction isolation level. Valid transaction isolation level values are sql-TXN-Read-Uncommitted, sql-TXN-Read-Committed, sql-TXN-Repeatable-Read, and sql-TXN-Serializable.
sqe-BadConcurrencyValue | 2127 | The supplied cursor concurrency value does not correspond to a valid concurrency value. Valid cursor concurrency values are sql-Concur-Read-Only, sql-Concur-Lock, sql-Concur-RowVer, and sql-Concur-Values.
sqe-BadEndQueryOptionValue | 2128 | The supplied end query option value does not correspond to a valid value. Valid end query option values are sql-Close and sql-Drop for the SQL END QUERY and SQL PREPARE QUERY statements. The SQL PREPARE QUERY statement also allows the sql-None value to indicate taking no action on the query after fetching the row.
sqe-WrongNumberOfArgs | 2201 | The number of arguments provided for the statement does not agree with the number of arguments expected for the statement.
sqe-BadDataSourceArg | 2202 | The data source name argument in an SQL CONNECT DATASOURCE statement is numeric (a nonnumeric value is required) or could not be converted to a valid data source name, possibly because of data truncation.
sqe-BadUserNameArg | 2203 | The user name argument in an SQL CONNECT DATASOURCE or SQL SET USER statement is numeric (a nonnumeric data item is required) or could not be converted to a valid user name, possibly because of data truncation.
sqe-BadUserPasswordArg | 2204 | The user password argument in an SQL CONNECT DATASOURCE or SQL SET USER statement is numeric (a nonnumeric data item is required) or could not be converted to a valid user password, possibly because of data truncation.
sqe-BadConnectionHandleArg | 2205 | The connection handle argument in the statement is not a valid data item for specifying a connection handle. The argument data item is nonnumeric, has a nonzero scale, or has a precision of less than six digits.
sqe-BadQueryHandleArg | 2206 | The query handle argument in the statement is not a valid data item for specifying a query handle. The argument data item is nonnumeric, has a nonzero scale, or has a precision of less than six digits.
sqe-BadSQLStatementArg | 2207 | The SQL statement text string argument in an SQL CONSTRUCT QUERY or SQL PREPARE QUERY statement is numeric (a nonnumeric data item is required).
sqe-BadColumnNumberArg | 2208 | A column name or number argument is numeric, but could not be converted to an integer column number value.
sqe-BadColumnNameArg | 2209 | A column name or number argument is nonnumeric, but could not be converted to a column name string
sqe-BadParamNumberArg | 2210 | A parameter number argument is nonnumeric (a numeric integer is required) or could not be converted to a parameter number value.
sqe-BadLengthIndicatorArg | 2211 | A length indicator argument is not a signed numeric integer data item with at least nine digits of precision as required
sqe-BadParamSQLTypeArg | 2212 | An SQL data type argument in an SQL BIND PARAMETER statement is not a numeric value, as required, or a conversion error occurred while obtaining the data type value.
sqe-BadParamIOTypeArg | 2213 | A parameter input-output type argument in an SQL BIND PARAMETER statement is not a numeric value, as required, or a conversion error occurred while obtaining the data type value.
sqe-BadTableNameArg | 2214 | The table name argument in an SQL QUERY COLUMNS or SQL QUERY INDEXES statement is numeric (a nonnumeric value is required) or could not be converted to a table name string, possibly because of data truncation.
sqe-BadProcedureNameArg | 2215 | The procedure name argument in an SQL QUERY PROCEDURES statement is numeric (a nonnumeric value is required) or could not be converted to a procedure name string, possibly because of data truncation.
sqe-BadDescGroupArg | 2218 | The output description group argument in one of the status inquiry statements is not the correct length, or one of the correct lengths, for the statement in which it is specified.
sqe-BadConQryDirArg | 2219 | A directive in the SQL CONSTRUCT QUERY statement could not be interpreted. This error indicates an implementation error in InstantSQL.
sqe-BadDateArg | 2220 | An argument following the sql-DirDate directive in the SQL CONSTRUCT QUERY statement is not a valid date value. A valid date value must have either 8 digits for a YYYYMMDD date or 7 digits for a YYYYDDD date.
sqe-BadTimeArg | 2221 | An argument following the sql-DirTime directive in the SQL CONSTRUCT QUERY statement is not a valid time value. A valid time value must have 2, 4, 6 or 8 digits, representing time formats HH, HHmm, HHmmSS, HHmmSScc, respectively.
sqe-BadTimeStampArg | 2222 | An argument following the sql-DirTimestamp directive in the SQL CONSTRUCT QUERY statement is not a valid timestamp value. A valid timestamp value must be, at a minimum, a valid date value as described in error 2220. Optionally, it may include an appended valid time value as described in error 2221.
sqe-BadTxnIsolationArg | 2223 | The transaction isolation argument in an SQL START TRANSACTION statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadConcurrencyArg | 2224 | The cursor concurrency argument in an SQL PREPARE QUERY statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadLoginTimeoutArg | 2225 | The login timeout argument in an SQL CONNECT DATASOURCE statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadQueryTimeoutArg | 2226 | The query timeout argument in an SQL START QUERY statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadEndQueryOptionArg | 2227 | The supplied end query option argument in an SQL END QUERY or SQL PREPARE QUERY statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadSeqNoArg | 2228 | The supplied sequence number argument in an SQL DESCRIBE ERROR statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-BadCatalogNameArg | 2229 | The supplied catalog name argument in a browse query statement is numeric (a nonnumeric value is required) or is longer than the maximum length of a catalog name.
sqe-BadSchemaNameArg | 2230 | The supplied schema name argument in a browse query statement is numeric (a nonnumeric value is required) or is longer than the maximum length of a schema name.
sqe-BadTableTypeArg | 2231 | The supplied table type argument in an SQL QUERY TABLES statement is numeric (a nonnumeric value is required) or is longer than the maximum length of a table type value list.
sqe-BadDataTypeArg | 2232 | The supplied data type argument in an SQL QUERY TYPES statement is nonnumeric (a numeric value is required) or could not be converted to an integer, possibly because of data truncation.
sqe-InternalError | 2301 | This error indicates a problem in the implementation of InstantSQL.
sqe-COBOLAreaError | 2302 | This error indicates a problem in the implementation of InstantSQL and is a special case of sqe-InternalError.
sqe-LostErrors | 2304 | The statement generated more errors than InstantSQL supports for a single statement. The SQL DESCRIBE ERROR statement will return descriptions of all the errors up to the limit and then return this error description.
sqe-CannotAllocateMemory | 2401 | InstantSQL was unable to allocate necessary memory while executing a statement.
sqe-UnexpectedODBCError | 2501 | An ODBC function used to implement the InstantSQL statement has returned an unexpected error.

Copyright Š2000 Liant Software Corp. All rights reserved.