Retrieve and Update errors and the DBError event

Retrieve and update testing

When using the Retrieve or Update method in a DataWindow control, you should test the method's return code to see whether the activity succeeded.

Table 9-4: Return codes for the Retrieve and Update methods

Method

Return code

Meaning

Retrieve

>=1

Retrieval succeeded; returns the number of rows retrieved

-1

Retrieval failed; DBError event triggered

0

No data retrieved

Update

1

Update succeeded

-1

Update failed; DBError event triggered

NoteDo not test the SQLCode attribute After issuing a SQL statement (such as CONNECT, COMMIT, or DISCONNECT) or the equivalent method of the transaction object, you should always test the success/failure code (the SQLCode attribute in the transaction object). However, you should not use this type of error checking following a retrieval or update made in a DataWindow.

For more information about error handling after a SQL statement, see Chapter 16, “Using Transaction Objects.”

Example

If you want to commit changes to the database only if an update succeeds, you can code:

IF dw_emp.Update() > 0 THEN
		COMMIT USING EmpSQL;
ELSE
		ROLLBACK USING EmpSQL;
END IF

Using the DBError event

The DataWindow control triggers its DBError event whenever there is an error following a retrieval or update; that is, if the Retrieve or Update methods return –1. For example, if you try to insert a row that does not have values for all columns that have been defined as not allowing null, the DBMS rejects the row and the DBError event is triggered.

By default, the DataWindow control displays a message box describing the error message from the DBMS.

Figure 9-4: Sample error message displayed from DBError event

A scrollable message area in the Data Window Error message box displays the following sample message: sequel state equals 23000. (Sybase) (O D B C Driver ) Integrity constraint violation: column ’ l name ’ in table ’ customer ’ cannot be NULL. No changes made to database. An OK command button displays under the message area.

In many cases you may want to code your own processing in the DBError event and suppress the default message box. Here are some tips for doing this:

Table 9-5: Tips for processing messages from DBError event

To

Do this

Get the DBMS's error code

Use the SQLDBCode argument of the DBError event

Get the DBMS's message text

Use the SQLErrText argument of the DBError event

Suppress the default message box

Specify an action/return code of 1

NoteAbout DataWindow action/return codes Some events for DataWindow controls have codes that you can set to override the default action that occurs when the event is triggered. The codes and their meaning depend on the event. You set the code with a RETURN statement.

Example

Here is a sample script for the DBError event:

// Database error -195 means that some of the
// required values are missing
IF sqldbcode = -195 THEN
		MessageBox("Missing Information",  &	
			"You have not supplied values for all " &
			+"the required fields.")
END IF
// Return code suppresses default message box
RETURN 1

At runtime, the user would see the message box after the error.

Figure 9-5: Example of a user-defined message for the DBError event

A sample Missing Information message box displays an eye icon to identify an informational message, along with the following text: You have not supplied values for all the required fields. Under the message is a command button labeled OK.