Error

Syntax 1: for Connection, DataWindow, DataStore, OLE, OLEObject, OLETxnObject

Description

Occurs when an error is found in a data or property expression for an external object or a DataWindow object.

Improved error-handling capability in PowerBuilder

The Error event is maintained for backward compatibility. If you do not script the Error event or change its action argument, information from this event is passed to RuntimeError objects, such as DWRuntimeError or OLERuntimeError. You can handle these errors in a try-catch block.

Event ID

Event ID

Objects

None

Connection, DataWindow, DataStore, OLE, OLEObject, OLETxnObject


Arguments

Argument

Description

errornumber

Unsigned integer by value (PowerBuilder's error number)

errortext

String, read-only (PowerBuilder's error message)

errorwindowmenu

String, read-only (the name of the window or menu that is the parent of the object whose script caused the error)

errorobject

String, read-only (the name of the object whose script caused the error)

errorscript

String, read-only (the full text of the script in which the error occurred)

errorline

Unsigned integer by value (the line in the script where the error occurred)

action

ExceptionAction by reference.

A value you specify to control the application's course of action as a result of the error. Values are:

  • ExceptionFail! -- fail as if this script were not implemented. The error condition triggers any active event handlers, or if none, the SystemError event.

  • ExceptionIgnore! -- ignore this error and return as if no error occurred (use this option with caution because the conditions that caused the error can cause another error).

  • ExceptionRetry! -- execute the function or evaluate the expression again in case the OLE server was not ready. This option is not valid for DataWindows.

  • ExceptionSubstituteReturnValue! -- use the value specified in the returnvalue argument instead of the value returned by the OLE server or DataWindow, and cancel the error condition.

returnvalue

Any by reference (a value whose datatype matches the expected value that the OLE server or DataWindow would have returned).

This value is used when the value of action is ExceptionSubstituteReturnValue!.


Return Values

None. Do not use a RETURN statement.

Usage

DataWindow and OLE objects are dynamic. Expressions that use dot notation to refer to data and properties of these objects might be valid under some runtime conditions but not others. The Error event allows you to respond to this dynamic situation with error recovery logic.

The Error event also allows you to respond to communications errors in the client component of a distributed application. In the Error event for a custom connection object, you can tell PowerBuilder what action to take when an error occurs during communications between the client and the server.

The Error event gives you an opportunity to substitute a default value when the error is not critical to your application. Its arguments also provide information that is helpful in debugging. For example, the arguments can help you debug DataWindow data expressions that cannot be checked by the compiler -- such expressions can only be evaluated at runtime.

When to substitute a return value

The ExceptionSubstituteReturnValue! action allows you to substitute a return value when the last element of an expression causes an error. Do not use it to substitute a return value when an element in the middle of an expression causes an error. The substituted return value does not match the datatype of the unresolved object reference and causes a system error.

The ExceptionSubstituteReturnValue! action can be useful for handling errors in data expressions.

For DataWindows, when an error occurs while evaluating a data or property expression, error processing occurs like this:

  1. The Error event occurs.

  2. If the Error event has no script or its action argument is set to ExceptionFail!, any active exception handler for a DWRuntimeError or its RuntimeError ancestor is invoked.

  3. If no exception handler exists, or if the existing exception handlers do not handle the exception, the SystemError event is triggered.

  4. If the SystemError event has no script, an application error occurs and the application is terminated.

The error processing in the client component of a distributed application is the same as for DataWindows.

For information about error processing in OLE controls, see the ExternalException event. For information about data and property expressions for DataWindow objects, see the section called “PowerBuilder: DataWindow property expressions” in DataWindow Reference.

For information about handling communications errors in a multitier application, see Developing Distributed Applications in Application Techniques.

Examples

This example displays information about the error that occurred and allows the script to continue:

MessageBox("Error Number " + string(errornumber)&
   + " Occurred", "Errortext: " + String(errortext))
action = ExceptionIgnore! 

See also

DBError in the section called “DBError” in DataWindow Reference

ExternalException

SystemError

Syntax 2: for CompressorObject objects

Description

Occurs when an error is found in the file compression operation.

Event ID

Event ID

Objects

None

CompressorObject


Arguments

Argument

Description

ErrorNumber

Unsigned integer by value (PowerBuilder's error number)

1 -- Success

-1 -- A general error occurred. If the CompressorObject object is used in asynchronous mode, this function will return the general error.

-2 -- The password entered is illegal.

-3 -- The operation is not supported for the source file format.

-4 -- The task thread is aborted.

-5 -- A task thread is currently running.

-6 -- The folder to be compressed does not exist.

-7 -- The folder to be compressed is empty.

-8 -- The compression format does not support multi-file compression.

-9 -- Failed to read file from the folder for compression.

-10 -- The target path does not exist.

-11 -- More than one source file has the same file name.

-12 -- Invalid compressed file name or no compressed file name is specified in the "dest" argument.

-13 -- Failed to compress.

ErrorText

String, read-only (PowerBuilder's error message)


Return Values

None

See also

Finished

ProcessingFile

SizeCompleted

Start

Syntax 3: for ExtractorObject objects

Description

Occurs when an error is found in the archive extraction operation.

Event ID

Event ID

Objects

None

ExtractorObject


Arguments

Argument

Description

ErrorNumber

Unsigned integer by value (PowerBuilder's error number)

1 -- Success

-1 -- A general error occurred. If the ExtractorObject object is used in asynchronous mode, this function will return the general error.

-2 -- The password entered is illegal.

-3 -- The operation is not supported for the source file format.

-4 -- The task thread is aborted.

-5 -- A task thread is currently running.

-6 -- No password is entered. You must enter the password.

-7 -- The password is incorrect.

-8 -- Failed to get new memory when saving the decompressed file.

-9 -- Failed to read the compressed file.

-10 -- Unrecognized format or the encrypted file name option is used when compressing the document.

-11 -- Access denied when extracting the archive.

-12 -- The compressed file does not exist.

-13 -- The directory where the decompressed file will be saved does not exist.

-14 -- Failed to extract the compressed file.

ErrorText

String, read-only (PowerBuilder's error message)


Return Values

None

See also

Finished

ProcessingFile

SizeCompleted

Start