Describes the processing that occurs when the STOP condition occurs during a block. This condition occurs when a user presses STOP, when a STOP statement is executed, or when certain internal conditions occur within the AVM. The STOP key is usually mapped to CTRL+BREAK (Windows) or CTRL+C (UNIX). By default, the STOP condition undoes active transactions, block by block, until it reaches the outermost block or a block that traps the STOP condition. Control then returns to the point where the outmost procedures was executed, be that the command line or a development tool such as Progress Developer Studio for OpenEdge or AppBuilder.
Almost all STOP conditions are trap-able with the ON STOP phrase. In some cases, the AVM might ignore ON STOP phrases at certain levels of the call stack. For example, if the AVM executes a procedure that relies on a lost database connection, the AVM raises the STOP condition and unwinds the call stack until it gets to a level above all references to the lost database. If the AVM encounters an ON STOP before this point, the AVM ignores the phrase. If the AVM encounters an ON STOP phrase after this point, the AVM executes the ON STOP.
ON STOP UNDO [label1] [ , LEAVE [ label2 ] | , NEXT [ label2 ] | , RETRY [ label1 ] | , RETURN [ return-value | ERROR [ return-value | error-object-expression ] | NO-APPLY ] ] |
RETRY is the default processing if you do not use LEAVE, NEXT, RETRY, or RETURN.
| Option | Description |
|---|---|
| return-value | The CHARACTER string you provide is passed to the caller. The caller can use the RETURN-VALUE function to read the returned value. |
| ERROR | Raises ERROR in the caller and undoes the current subtransaction. |
| ERROR return-value | Raises ERROR in the caller and undoes the current
subtransaction. The CHARACTER string you provide is passed to the
caller. The caller can use the RETURN-VALUE function to read the returned
value. The AVM also creates an Progress.Lang.AppError object and stores the return-value in the ReturnValue property. Note: User-defined functions have different behavior
since they must return the data type specified in the definition.
See the FUNCTION statement for
more information.
|
| ERROR error-object-expression | Raises ERROR in the caller and undoes the current
subtransaction. The specified error object is created and populated according to your code. If this is an Progress.Lang.AppError object, the caller can use the RETURN-VALUE function to read the setting of the ReturnValue property. |
| NO-APPLY | In a user-interface trigger, prevents the AVM from performing the default behavior for that event. |
You cannot specify ERROR within a user-interface trigger block or a destructor. You can specify the NO-APPLY option only within a user-interface trigger block.
This procedure lets you update the CreditLimit field for each Customer. If you enter a value greater than 100,000, the program raises the STOP condition. Since you specified an UNDO, RETRY for a STOP, the procedure starts the iteration over and allows you to enter another value.
r-ostop.p
FOR EACH Customer ON STOP UNDO, RETRY: DISPLAY Customer.CustNum Customer.Name Customer.CreditLimit. UPDATE Customer.CreditLimit. IF Customer.CreditLimit > 100000 THEN STOP. END. |
The ON STOP phrase is especially useful to trap the STOP condition that results when a user cancels out of a record lock conflict in an application. The r-ostop2.p procedure is a simple record navigation and update utility that finds Salesrep records with the SHARE-LOCK condition. The user can update the values of a Salesrep record in the frame and choose the Assign button to assign the new values to the database. If the user attempts to update a Salesrep record that another user already has in the SHARE-LOCK condition, the r-ostop2.p procedure freezes as a result of the record locking conflict. The AVM displays a message asking the user to wait for the other user to relinquish the lock on the record or to press the STOP key to abort the operation.
By default, the STOP key aborts the procedure. The ON STOP phrase on the DO TRANSACTION block in the r-ostop2.p procedure captures the STOP condition and returns control to the procedure.
r-ostop2.p
DEFINE VARIABLE methRtn AS LOGICAL NO-UNDO.
DEFINE BUTTON buta LABEL "Find Next".
DEFINE BUTTON butb LABEL "Assign".
DEFINE BUTTON butc LABEL "Done".
DEFINE FRAME a
Salesrep.SalesRep SKIP Salesrep.RepName SKIP Salesrep.Region SKIP
Salesrep.MonthQuota[1] Salesrep.MonthQuota[7] SKIP
Salesrep.MonthQuota[2] Salesrep.MonthQuota[8] SKIP
Salesrep.MonthQuota[3] Salesrep.MonthQuota[9] SKIP
Salesrep.MonthQuota[4] Salesrep.MonthQuota[10] SKIP
Salesrep.MonthQuota[5] Salesrep.MonthQuota[11] SKIP
Salesrep.MonthQuota[6] Salesrep.MonthQuota[12] SKIP(1)
buta butb Butc
WITH 1 DOWN NO-BOX SIDE-LABELS.
/*******TRIGGERS*******/
ON CHOOSE OF buta DO:
FIND NEXT SalesRep SHARE-LOCK.
IF NOT AVAILABLE SalesRep THEN
MESSAGE "No Next SalesRep".
DISPLAY SalesRep WITH FRAME a.
END.
ON CHOOSE OF butb DO:
DO TRANSACTION ON STOP UNDO, LEAVE:
ASSIGN SalesRep.SalesRep Salesrep.RepName SalesRep.Region.
END.
END.
ON CHOOSE OF butc DO:
APPLY "ENDKEY" TO FRAME a.
END.
/*******MAIN BLOCK*******/
FIND FIRST SalesRep SHARE-LOCK.
DISPLAY SalesRep WITH FRAME a.
ENABLE ALL WITH FRAME a.
WAIT-FOR ENDKEY OF FRAME a FOCUS buta.
|