Chapter 12
Error Handling for LiveWire
This chapter describes the types of errors you can encounter when working with relational databases.
This chapter contains the following sections:
Checking for Error Conditions
When writing a JavaScript application, you should be aware of the various error conditions that can occur. In particular, when you use the LiveWire Database Service to interact with a relational database, errors can occur for a variety of reasons. For example, SQL statements can fail because of referential integrity constraints, lack of user privileges, record or table locking in a multiuser database, and so on. When an action fails, the database server returns an error message indicating the reason for failure.
Your code should check for error conditions and handle them appropriately.
Return Values
The return value of the methods of the LiveWire objects may indicate whether or not an error occurred. Methods can return values of various types. Depending on the type, you can infer different information about possible errors.
Number
When a method returns a number, the return value can either represent an actual numeric value or a status code. For example, Cursor.columns returns the number of columns in a cursor, but Cursor.updateRow returns a number indicating whether or not an error occurred.
The Cursor.columns and Resultset.columns methods return an actual numeric value. The following methods return a numeric value that indicates a status code:
|
Connection.beginTransaction
Connection.commitTransaction
Connection.execute
Connection.majorErrorCode
Connection.minorErrorCode
Connection.release
Connection.rollbackTransaction
Connection.SQLTable
Cursor.close
Cursor.deleteRow
Cursor.insertRow
Cursor.updateRow
DbPool.connect
DbPool.disconnect
DbPool.majorErrorCode
DbPool.minorErrorCode
DbPool.storedProcArgs
Resultset.close
Stproc.close
|
|
If the numeric return value of a method indicates a status code, 0 indicates successful completion and a nonzero number indicates an error. If the status code is nonzero, you can use the majorErrorCode and majorErrorMessage methods of the associated Connection or DbPool object to find out information about the error. In some cases, the minorErrorCode and minorErrorMessage methods provide additional information about the error. For information on the return values of these error methods, see "Error Methods."
Object
When a method returns an object, it can either be a real object or it can be null. If the method returns null, a JavaScript error probably occurred. In most cases, if an error occurred in the database, the method returns a valid object, but the software sets an error code.
The blob global function returns an object. In addition, the following methods return an object:
|
Connection.cursor
Connection.storedProc
DbPool (constructor)
DbPool.connection
Stproc.resultSet
|
|
Whenever you create a cursor, result set, or stored procedure, you should check for both the existence of the created object and for a possible return code. You can use the majorErrorCode and majorErrorMessage methods to examine an error.
For example, you might create a cursor and verify its correctness with code similar to the following:
|
// Create the Cursor object.
custs = connobj.cursor ("select id, name, city
from customer order by id");
// Before continuing, make sure a real cursor was returned
// and there was no database error.
if ( custs && (connobj.majorErrorCode() == 0) ) {
// Get the first row
custs.next();
// ... process the cursor rows ...
//Close the cursor
custs.close();
}
else
// ... handle the error condition ...
|
|
Boolean
The following methods return Boolean values:
|
Connection.connected
Cursor.next
DbPool.connected
Resultset.next
|
|
When a method returns a Boolean value, true usually indicates successful completion, whereas false indicates some other condition. A return value of false does not indicate an actual error; it may indicate a successful termination condition.
For example, Connection.connected returns false to indicate the Connection object is not currently connected. This can mean that an error occurred when the Connection object was created, or it can indicate that a previously used connection was intentionally disconnected. Neither of these is an error of the connected method. If an error occurred when the connection was created, your code should catch the error with that method. If the connection was terminated, you can reconnect.
As a second example, Cursor.next returns false when you get to the end of the rows in the cursor. If the SELECT statement used to create the Cursor object finds the table but no rows match the conditions of the SELECT statement, then an empty cursor is created. The first time you call the next method for that cursor, it returns false. Your code should anticipate this possibility.
String
When a method returns a string, you usually do not get any error information. If, however, the method returns null, check the associated error method.
The following methods return a string:
|
Connection.majorErrorMessage
Connection.minorErrorMessage
Cursor.columnName
DbPool.majorErrorMessage
DbPool.minorErrorMessage
Resultset.columnName
|
|
Void
Some methods do not return a value. You cannot tell anything about possible errors from such methods. The following methods do not return a value:
|
Connection.release
Cursor.close
DbPool.disconnect
Resulset.close
|
|
Error Methods
As discussed earlier, many methods return a numeric status code. When a method returns a status code, there may be a corresponding error code and message from the database server. LiveWire provides four methods for the Connection and DbPool objects to access database error codes and messages. The methods are:
majorErrorMessage: major error message returned by the database.
minorErrorMessage: secondary message returned by the database.
majorErrorCode: major error code returned by the database. This typically corresponds to the server's SQLCODE.
minorErrorCode: secondary error code returned by the database.
The results returned by these methods depend on the database server being used and the database status code. Most of the time you need to consider only the major error code or error message to understand a particular error. The minor error code and minor error message are used in only a small number of situations.
|
Note
|
Calling another method of Connection or DbPool can reset the error codes and messages. To avoid losing error information, be sure to check these methods before proceeding.
|
After receiving an error message, your application may want to display a message to the user. Your message may include the string returned by majorErrorMessage or minorErrorMessage or the number returned by majorErrorCode or minorErrorCode. Additionally, you may want to process the string or number before displaying it.
In computing the string returned by majorErrorMessage and minorErrorMessage, LiveWire returns the database vendor string, with additional text prepended. For details on the returned text, see the descriptions of these methods in the Server-Side JavaScript Reference.
Status Codes
The following table lists the status codes returned by various methods. iPlanet recommends that you do not use these values directly. Instead, if a method returns a nonzero value, use the associated majorErrorCode and majorErrorMessage methods to determine the particular error.
Table 12-1 Status codes for LiveWire methods
|
Status Code
|
Explanation
|
Status Code
|
Explanation
|
|
0
|
No error
|
14
|
Null reference parameter
|
|
1
|
Out of memory
|
15
|
database object not found (for backward compatibility with older applications)
|
|
2
|
Object never initialized
|
16
|
Required information is missing
|
|
3
|
Type conversion error
|
17
|
Object cannot support multiple readers
|
|
4
|
Database not registered
|
18
|
Object cannot support deletions
|
|
5
|
Error reported by server
|
19
|
Object cannot support insertions
|
|
6
|
Message from server
|
20
|
Object cannot support updates
|
|
7
|
Error from vendor's library
|
21
|
Object cannot support updates
|
|
8
|
Lost connection
|
22
|
Object cannot support indices
|
|
9
|
End of fetch
|
23
|
Object cannot be dropped
|
|
10
|
Invalid use of object
|
24
|
Incorrect connection supplied
|
|
11
|
Column does not exist
|
25
|
Object cannot support privileges
|
|
12
|
Invalid positioning within object (bounds error)
|
26
|
Object cannot support cursors
|
|
13
|
Unsupported feature
|
27
|
Unable to open
|