ON STOP phrase

Describes processing that occurs when the STOP condition is raised during execution of a block on which this phrase is specified. The STOP condition is raised when:

• The user presses the STOP key. (The STOP key is usually mapped to CTRL+BREAK on Windows and CTRL+C on Unix/Linux.)
• The time-out is exceeded for a STOP-AFTER directive on a DO, FOR, or REPEAT statement.
• The time-out set using the Lock Timeout (-lkwtmo) startup parameter is exceeded when waiting for release of a record lock.
• A STOP statement executes.
• For certain system errors where the AVM raises the STOP (instead of the ERROR) condition.

By default, the STOP condition undoes active transactions, block by block, until it reaches the outer-most block or a block that traps the STOP condition. Control then returns to the point where the outer-most procedure was executed, be that the command line or a development tool such as Progress Developer Studio for OpenEdge or the OpenEdge AppBuilder.

Syntax

ON STOP UNDO
  [label1]
  [     , LEAVE [ label2 ]
     |  , NEXT [ label2 ]
     |  , RETRY [ label1 ]
     |  , RETURN [ return-value |
                  ERROR [ return-value | error-object-expression ] |
                  NO-APPLY ]
  ]

label1

The name of the block whose processing you want to undo. If you do not name a block with label1, ON STOP UNDO undoes the processing of the block started by the statement that contains the ON STOP phrase.

LEAVE [label2]

Indicates that after undoing the processing of a block, the AVM leaves the block labeled label2. If you do not name a block, the AVM leaves the block labeled with label1.

NEXT [label2]

Indicates that after undoing the processing of a block, the AVM executes the next iteration of the block you name with the label2 option. If you do not name a block with the NEXT option, the AVM executes the next iteration of the block labeled with label1.

RETRY [label1]

Indicates that after undoing the processing of a block, the AVM repeats the same iteration of the block you name with the label1 option.

RETRY is the default processing if you do not use LEAVE, NEXT, RETRY, or RETURN.

RETURN ...

Returns to the calling routine, or if there is no calling routine, returns to the OpenEdge Editor. The following table describes various RETURN cases:

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.

Example

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. In this example, a CATCH block also catches and handles the stop object thrown (Progress.Lang.LockConflict) if the time-out period is exceeded while waiting for release of a record lock or if the user cancels out of this waiting period.

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.
    CATCH eStop AS Progress.Lang.LockConflict:
      /* Handle a stop object thrown for lock conflict time-out, 
         perhaps by logging the values of the CallStack, TableName, 
         User, and Device properties of the object */
    END.
  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.

Notes

• For STOP conditions that you can trap, instead of (or in addition to) using the ON STOP phrase, you can use a CATCH block (a stop CATCH block) to trap a stop object of a particular type depending on how the STOP condition was raised. Unlike using the ON STOP phrase, which traps every STOP condition not otherwise handled, by catching a stop object of a given type, you can trap any error message associated with the STOP condition and identify why the associated STOP condition was raised along with additional information, depending on the object type. For more information on using CATCH blocks with stop objects, see the CATCH statement description.
• When both a local ON STOP phrase and one or more local stop CATCH blocks are specified on the current block, if any of the local stop CATCH blocks catch a matching stop object type, the local ON STOP phrase is ignored and you can otherwise handle the STOP condition in the CATCH block according to the caught object type. If no local stop CATCH blocks catch a matching object type, the specified directive in the local ON STOP phrase executes for any raised STOP condition.
• When both an ON STOP phrase and one or more stop CATCH blocks are specified somewhere up the call stack from where a STOP condition is raised, if the ON STOP phrase traps this STOP condition before any stop CATCH blocks execute above it on the call stack, none of these stop CATCH blocks will ever execute. Conversely, if stop CATCH blocks execute below this ON STOP phrase on the call stack, the behavior in this ON STOP phrase will execute only for STOP conditions not otherwise handled by the CATCH blocks that execute below it.
• Almost all STOP conditions are trappable with the ON STOP phrase or a stop CATCH block. In some cases, the AVM might ignore STOP conditions 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 the ON STOP phrase or a compatible stop CATCH block before this point, the AVM ignores the phrase or CATCH block. If the AVM encounters the ON STOP phrase or a compatible stop CATCH block after this point, the AVM executes the directive specified in the phrase or the CATCH block, with the CATCH block taking precedence if the ON STOP phrase is on the same associated block.
• Stop CATCH block support is available as a Technology Preview only in OpenEdge Release 11.7.

See also

CATCH statement, ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, Progress.Lang.Stop class, Progress.Lang.StopError class, RETURN statement, RETURN-VALUE function, STOP statement