Try OpenEdge Now
skip to main content
New and Revised Features
What's New in 11.7 : OpenEdge ABL enhancements : Handling STOP conditions using stop objects
 

Handling STOP conditions using stop objects

OpenEdge Release 11.7 adds the ability in ABL to handle STOP conditions by catching and throwing certain class-based objects (stop objects). This feature is thus analogous to the support in previous releases to handle ERROR conditions by catching and throwing error objects. As with handling error objects using CATCH blocks and handling ERROR conditions using the ON ERROR phrase, you can combine the handling of stop objects using CATCH blocks with the handling of STOP conditions using the ON STOP phrase.
In addition, using CATCH blocks to handle STOP conditions, you can now identify different types of STOP conditions depending on the type of stop object that is caught, and you can trap any error messages associated with the STOP condition, which was not possible in previous releases.
Note: In OpenEdge Release 11.7, support for handling STOP conditions as stop objects is a available as a "Technology Preview" only. For more information, see Technology Preview for STOP condition handling using stop objects.
In order to use this stop object feature in an OpenEdge session, you must explicitly enable it by setting the Catch STOP (-catchStop) startup parameter to 1 (see Startup parameters). By default, the feature is disabled and any use of stop objects in the session are ignored by the AVM.
You must recompile any existing source code that contains a CATCH block for Progress.Lang.Error, Progress.Lang.SysError, or Progress.Lang.ProError, and of course, you must compile any code that references any of the new stop objects. The compilation will succeed regardless of the value of the -catchStop startup parameter. However, without -catchStop 1 on at run time, the new stop handling behavior will not take effect.
Following are descriptions of the ABL elements that have been added and updated to support stop object handling.
These are the new ABL built-in classes that implement stop objects. When enabled, the AVM throws an appropriate stop object for every STOP condition that it raises:
*Progress.Lang.Stop — The AVM throws an instance of this class when the STOP statement executes. This class inherits from Progress.Lang.Object and also provides a single public CallStack property that works similar to the CallStack property provided for error objects. This is also the immediate super class for the following built-in objects that the AVM throws in response to the associated STOP conditions:
*Progress.Lang.LockConflict — The AVM throws an instance of this class when a time-out occurs while waiting for a record lock or when the user presses Cancel in the dialog box displayed during the record lock waiting period. This class also provides public Device, TableName, and User properties to identify the device, database table, and user that holds the record lock.
*Progress.Lang.StopAfter — The AVM throws an instance of this class when a time-out occurs in response to the STOP-AFTER setting on a DO, FOR, or REPEAT block.
*Progress.Lang.UserInterrupt — The AVM throws an instance of this class when the user interrupts the AVM by pressing the STOP key, which is usually mapped to CTRLC on Unix/Linux or CTRLBreak on Windows.
*Progress.Lang.StopError — The AVM throws an instance of this class when the AVM encounters certain unexpected error conditions. Although thrown for a STOP condition, objects of this class inherit from Progress.Lang.SysError and therefore implement the Progress.Lang.Error interface, allowing them to return error messages and a call stack associated with the error that raised the STOP condition.
The following ABL syntax has been updated to work with stop objects when enabled:
*CATCH statement — Updated to catch any specified stop object, as well as any error object, including any stop object thrown from an OpenEdge application server to an OpenEdge client.
Note: For any Progress.Lang.StopError object thrown on an OpenEdge application server, the associated error messages are written to the server log file regardless if the object is caught and handled on the server or the client. This differs from STOP condition handling without stop objects enabled, as in previous releases, where any associated error messages for STOP conditions raised on the server are always written to the server log file and never reach the client.
*DO, FOR, and REPEAT statements — Updated to throw a Progress.Lang.StopAfter object when a STOP-AFTER time-out setting is satisfied and raises the STOP condition.
*ON STOP phrase — Updated to work with any CATCH block for a stop object that is coded in the associated block on which the ON STOP phrase is specified. Note that a CATCH block for a stop object takes precedence over any ON STOP phrase that applies to the same associated block.
*STOP statement — Updated to throw a Progress.Lang.Stop object when it raises the STOP condition.
*UNDO, THROW statement — Updated to allow a stop object, as well as an error object, to be thrown.
The following new attributes of the asynchronous request object handle, when enabled, return any associated stop object thrown from the asynchronous request:
*ERROR-OBJECT — This attribute returns an object reference to any instance of the Progress.Lang.StopError class that is thrown from an asynchronous request.
*STOP-OBJECT — This attribute returns an object reference to any instance of the Progress.Lang.Stop class, or one of its built-in subclasses, that is thrown from an asynchronous request.
For more information on these attributes, see Asynchronous request improvements.
For more information on STOP condition handling using stop objects, see:
Manual:
OpenEdge Development: ABL Reference
Note: Although OpenEdge Development: Error Handling describes both ERROR and STOP condition handling in OpenEdge, this manual has not been updated to describe the stop object feature. For a more detailed overview of the feature in this release, see the description of the CATCH statement in OpenEdge Development: ABL Reference.