STOP statement

Signals the STOP condition in the current block. By default, the STOP condition stops processing a procedure, backs out the active transaction, and unwinds the call stack until it returns to the startup procedure or the Procedure Editor. You can change this behavior by including the ON STOP phrase on a block statement.

In any procedure, the outermost block that updates the database is the system transaction. In this procedure, the first iteration of the FOR EACH block starts a system transaction. The transaction ends when that iteration ends. Another transaction starts at the start of the next iteration. After you update the credit-limit field, the AVM prompts you to STOP. If you enter yes, the STOP statement stops the procedure and undoes any database modifications made in that transaction, as shown:

STOP

r-stop.p
DEFINE VARIABLE ans AS LOGICAL NO-UNDO. FOR EACH Customer: DISPLAY Customer.CustNum Customer.Name. UPDATE Customer.CreditLimit. ans = FALSE. MESSAGE "Stopping now undoes changes to this record.". MESSAGE "Do you want to stop now?" UPDATE ans. IF ans THEN STOP. END.

r-stop.p

DEFINE VARIABLE ans AS LOGICAL NO-UNDO. 
FOR EACH Customer: 
  DISPLAY Customer.CustNum Customer.Name. 
  UPDATE Customer.CreditLimit. 
  ans = FALSE. 
  MESSAGE "Stopping now undoes changes to this record.". 
  MESSAGE "Do you want to stop now?" UPDATE ans. 
  IF ans THEN STOP. 
END.

When you add the ON STOP phrase to the block statement of the previous procedure, it changes the default behavior of the STOP statement. In this procedure, the AVM allows you to re-enter the record when you choose to stop:

r-stop2.p
DEFINE VARIABLE ans AS LOGICAL NO-UNDO. FOR EACH Customer ON STOP UNDO, RETRY: DISPLAY Customer.CustNum Customer.Name. UPDATE Customer.CreditLimit. ans = FALSE. MESSAGE "Stopping now undoes changes to this record." "Do you want to stop now?" VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO UPDATE ans. IF ans THEN STOP. END.

r-stop2.p

DEFINE VARIABLE ans  AS LOGICAL NO-UNDO. 
FOR EACH Customer ON STOP UNDO, RETRY: 
  DISPLAY Customer.CustNum Customer.Name. 
  UPDATE Customer.CreditLimit. 
  ans = FALSE. 
  MESSAGE "Stopping now undoes changes to this record." 
    "Do you want to stop now?"  
    VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO UPDATE ans. 
  IF ans THEN STOP. 
END.

Unless you coded an ON STOP phrase, the STOP statement continues to back out of all blocks on the call stack.

Almost all STOP conditions are trappable with the ON STOP phrase. In two cases, the AVM may ignore ON STOP phrases. First, 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 it encounters an ON STOP before this point it ignores it. If it encounters an ON STOP phrase after this point, then the AVM executes the ON STOP. Similarly, if the AVM encounters an I/O blocking statement inside a user-defined function or a non-void method, the STOP condition is raised, and the AVM unwinds the procedure stack ignoring ON STOP phrases until it gets to a point above the user-defined function or non-void method call.

If you use the Startup Procedure (-p) parameter to start the ABL session, and if the startup procedure is still active, the default STOP action restarts the procedure.

A terminal user can initiate the STOP condition by pressing STOP. This is usually mapped to CTRL+BREAK (Windows) or CTRL+C (UNIX). The actual mapping depends on your terminal and system configuration.