Error Handling for LiveWire

Table of Contents | Previous | Next | Index

Chapter 19
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:

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

database.beginTransaction
database.connect
database.commitTransaction
database.disconnect
database.execute
database.majorErrorCode
database.minorErrorCode
database.rollbackTransaction
database.SQLTable
database.storedProcArgs

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, database, 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" on page 381.

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
database.cursor
database.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
database.connected
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
database.majorErrorMessage
database.minorErrorMessage
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
database.disconnect
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, DbPool, and database 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, DbPool, or database 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. Netscape 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.

Status Code	Explanation	Status Code	Explanation
0	No error	14	Null reference parameter
1	Out of memory	15	`database` object not found
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

Table of Contents | Previous | Next | Index

Last Updated: 11/12/98 15:29:47

Chapter 19 Error Handling for LiveWire

Chapter 19
Error Handling for LiveWire