REPEAT statement

Begins a block of statements that are processed repeatedly until the block ends in one of several ways. Use an END statement to end a REPEAT block.

Block properties

Iteration, record scoping, frame scoping, transactions by default.

Syntax

[  label : ] 
REPEAT
  [ FOR record[ , record ]...]
  [ preselect-phrase ]
  [ query-tuning-phrase ]
  [ variable = expression1 TO expression2 [ BY k ]]
  [ WHILE expression ]
  [ TRANSACTION ] 
  [ STOP-AFTER expression ]
  [ on-endkey-phrase ]
  [ on-error-phrase ]
  [ on-quit-phrase ]
  [ on-stop-phrase ]
  [ frame-phrase ]
  [ catch-block[ catch-block...]]
  [ finally-block ] :

  repeat-body

FOR record[ , record] . . .

Names a record buffer and scopes the buffer to the block. The scope of a record determines when the buffer is cleared and the record is written back to the database. See OpenEdge Getting Started: ABL Essentials for more information on record scoping and blocks.

To access a record in a table defined for multiple databases, you must qualify the record's table name with the database name. See the Record phrase reference entry for more information.

preselect-phrase

Goes through a table to select the records that meet the criteria you specify in a record-phrase. PRESELECT creates a temporary index that contains pointers to each of the preselected records in the database table. You can then use other statements, such as FIND NEXT, to process those records. Following is the syntax for preselect-phrase:

PRESELECT   [ EACH | FIRST | LAST ]record-phrase     [ , { EACH | FIRST | LAST }record-phrase]...   [[ BREAK ]{ BY expression[ DESCENDING ]}...]

For more information, see the PRESELECT phrase reference entry.

query-tuning-phrase

Allows programmatic control over the execution of a DataServer query. Following is the syntax for the query-tuning-phrase:

QUERY-TUNING   (     [ BIND-WHERE | NO-BIND-WHERE ]     [ CACHE-SIZE integer]     [ DEBUG { SQL | EXTENDED }| NO-DEBUG ]     [ INDEX-HINT | NO-INDEX-HINT ]     [ JOIN-BY-SQLDB | NO-JOIN-BY-SQLDB ]     [ LOOKAHEAD | NO-LOOKAHEAD ]     [ SEPARATE-CONNECTION | NO-SEPARATE-CONNECTION ]   )

For more information, see the OpenEdge DataServer Guides (OpenEdge Data Management: DataServer for Microsoft SQL Server and OpenEdge Data Management: DataServer for Oracle).

variable = expression1 TO expression2[ BY k]

Indicates the name of a field or variable whose value you are incrementing in a loop. The expression1 is the starting value for variable on the first iteration of the loop. The k is the amount to add to variable after each iteration and must be a constant. When variable exceeds expression2 (or is less than expression2 if k is negative), the loop ends. Because expression1 is compared to expression2 at the start of the first iteration of the block, the block can be executed zero times. The expression2 is reevaluated with each iteration of the block.

WHILE expression

Indicates the condition during which the REPEAT block processes the statements within it. The block iterates as long as the condition specified by the expression is TRUE. The expression is any combination of constants, field names, and variable names that yield a logical value.

TRANSACTION

Identifies the REPEAT block as a system transaction block. The AVM starts a system transaction for each iteration of a transaction block if there is no active system transaction. See OpenEdge Getting Started: ABL Essentials for more information on transactions.

STOP-AFTER expression

The STOP-AFTER phrase specifies a time-out value for a DO, FOR, or REPEAT block. The integer expression specifies the number of seconds each iteration of a block has until a time-out occurs. If a time-out occurs, the AVM raises the STOP condition, throws a Progress.Lang.StopAfter object, and default STOP condition handling occurs. Use an ON STOP phrase on the block (or an enclosing block) to alter the default STOP condition handling. If enabled, you can also catch a Progress.Lang.StopAfter object using a CATCH block to provide alternate STOP condition handling. For more information, see the Progress.Lang.StopAfter class description.

If the block iteration completes before the specified time expires, the timer resets to expression for the next iteration. In other words, the timer is limited to the scope of a single block iteration. If a block with a STOP-AFTER phrase encloses another block or calls another block, the timer continues while the inner blocks execute.

If a block with a STOP-AFTER phrase contains a nested block with a STOP-AFTER phrase, then each has a timer in effect. If the outer block timer expires while the inner block is executing, the STOP condition is raised even if the timer for the inner block has not expired.

If the STOP condition is handled and execution resumes within the scope of a block with a STOP-AFTER phrase, no timer is in effect until the next iteration of a block with a STOP-AFTER phrase. In other words, all old timers are dismissed but new timers can now be established.

When the timer expires, the STOP condition is raised on the current statement.

Two important use cases for the STOP-AFTER phrase are to time-limit dynamic queries and to time-limit a procedure call. The following example time-limits a procedure call using a RUN statement:

DEFINE VARIABLE cnt as INTEGER INITIAL 0. PROCEDURE bumpCnt:     cnt = cnt + 1. END. DO STOP-AFTER 5:     RUN bumpCnt. END.

Use this technique to also make timed calls to class methods and user-defined functions.

The following example is simplified code that lets you try different STOP-AFTER cases.

DEFINE VARIABLE EndlessCount AS INTEGER INITIAL 0. DO STOP-AFTER 5 ON STOP UNDO, LEAVE:       FOR EACH Customer STOP-AFTER 1:      ASSIGN EndlessCount = EndlessCount + 1.      /* Try a complex operation on a Customer record to use up the         timer in a single iteration and raise the STOP condition in the         inner block */  END.    MESSAGE "Procedure half complete. Endlesscount = " EndlessCount ".".    REPEAT STOP-AFTER 1:      ASSIGN EndlessCount = EndlessCount + 1.      /*IF EndlessCount > 2000 THEN LEAVE. */  END.      MESSAGE "Procedure nearly complete. Endlesscount = " EndlessCount "." .    END. MESSAGE "Procedure complete. Endlesscount = " EndlessCount "." .

If you run this code as is, the outer DO block establishes a 5 second time limit for the work of the DO block and all inner blocks. When the inner FOR EACH block starts, another timer is established for the first iteration of this block. When the first FOR EACH iteration completes, its timer is reset to 1 second for the next iteration. Meanwhile, the outer timer on the DO block continues without interruption.

The FOR EACH block completes and execution continues forward to the REPEAT block, which is an endless loop. The REPEAT block also has a 1 second timer for each iteration of the block. At some point, the outer 5 second timer elapses and the AVM raises the STOP condition. The STOP condition is raised on the statement the AVM was executing when the timer elapsed. Normal STOP handling proceeds from that point.

As the stack unwinds during STOP processing, the AVM encounters the ON STOP phrase on the DO block. The ON STOP phrase dismisses the STOP condition and resumes normal execution with the next statement following the DO block, as directed by the LEAVE option.

If you remove the comments from the IF statement in the REPEAT block, the block will complete within the outer time limit and the STOP condition is not raised.

If you want to experiment with elapsed timers on an inner block, insert a complex operation inside the FOR EACH block.

In the following example, the STOP-AFTER expression is modified during program execution:

DEFINE VARIABLE ix       AS INTEGER NO-UNDO. DEFINE VARIABLE stopTime AS INTEGER NO-UNDO INITIAL 30. DO WHILE TRUE STOP-AFTER stopTime ON STOP UNDO, LEAVE:   RUN spinHere (10000).   stopTime = stopTime / 2. END. MESSAGE "program finished". PROCEDURE spinHere:   DEFINE INPUT PARAMETER spinLimit AS INT64 NO-UNDO.   DEFINE VARIABLE endTime  AS INT64   NO-UNDO.   DEFINE VARIABLE loopFlag AS LOGICAL NO-UNDO.   ASSIGN     loopFlag = TRUE     endTime  = ETIME(FALSE) + spinLimit.   DO WHILE loopFlag:     IF (ETIME(FALSE) > endTime) THEN       loopFlag = FALSE.   END. END PROCEDURE.

Because the STOP-AFTER expression is re-evaluated for each iteration of a looping block, any changes made to the expression during the iteration effect the timer for the block. In the example, the STOP-AFTER time limit is specified by the variable stopTime, which is initially set to 30 seconds. The procedure contains an iterating block which runs a procedure that executes for 10 seconds.

On the first iteration of the DO WHILE TRUE loop, stopTime is 30 seconds. The loop executes for 10 seconds, and then divides stopTime by 2. On the second iteration, the stopTime is 15 seconds; again the loop executes for 10 seconds, and then divides stopTime by 2. On the third iteration, the stopTime is 8 seconds. This time, the procedure spinHere runs for 8 seconds and then raises STOP. The STOP condition is handled by the DO block, and then the program displays the message program finished.

If a code block is called with a time limit of zero, the block is executed as if the STOP-AFTER phrase was omitted from the block declaration.

Consider the following example:

DEFINE VARIABLE barLimit AS INTEGER NO-UNDO. DEFINE VARIABLE ix       AS INTEGER NO-UNDO INITIAL 1. DO STOP-AFTER 10 ON STOP UNDO, LEAVE:   RUN foo. END. PROCEDURE foo:   RUN bar. END PROCEDURE. PROCEDURE bar:   DO WHILE ix > 0 STOP-AFTER barLimit:     ix = ix + 1.   END. END PROCEDURE.

In this example, procedure foo is run from within a timed block with a 10 second time limit; procedure bar is called from within the timed block, and contains an iterating block that specifies the STOP-AFTER phrase. Because the value of the STOP-AFTER expression evaluates to zero (that is, the current value of the barLimit variable), the block within bar is executed as an untimed block. However, the rules for execution of an untimed block within a timed block apply, so the untimed block in bar is executed with an implicit iteration time limit of 10 seconds.

Other points to consider are:

• If the expression evaluates to zero or less, then this is the equivalent of not specifying a STOP-AFTER phrase.
• STOP-AFTER phrases are not intended to interact with user interfaces.
• Blocking calls to third party software components, where the AVM has transferred execution control, cannot be timed out. This category includes operating system calls, MS Windows system calls, and calls to any third party DLLs and Unix shared objects.

on-endkey-phrase

Describes the processing that takes place when the ENDKEY condition occurs during a block. Following is the syntax for the ON ENDKEY phrase:

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

For more information, see the ON ENDKEY phrase reference entry.

on-error-phrase

Describes the processing that takes place when there is an error during a block. This is the syntax for the ON ERROR phrase:

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

For more information, see the ON ERROR phrase reference entry.

on-quit-phrase

Describes the processing that takes place when a QUIT statement is executed during a block. This is the syntax for the ON QUIT phrase:

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

For more information, see the ON QUIT phrase reference entry.

on-stop-phrase

Describes the processing that takes place when the STOP conditions occurs during a block. This is the syntax for the ON STOP phrase:

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

For more information, see the ON STOP phrase reference entry.

frame-phrase

Specifies the overall layout and processing properties of a frame. For more information, see the Frame phrase reference entry.

repeat-body

The body of the REPEAT block. Define repeat-body using the following syntax:

repeat-logic       .       .       .     [catch-block[catch-block...]]     [finally-block] END.

repeat-logic

The logic of the REPEAT block. This logic can contain the ABL statements allowed within the routine-level block (e.g., procedure, user-defined, or method) where the REPEAT statement is defined.

Each logic statement must end with a period.

catch-block

Specifies a CATCH statement that defines error handling code for one or more error types. For more information on catch-block, see the CATCH statement reference entry.

finally-block

Specifies a FINALLY statement that defines the processing that must occur after all other processing in the block occurs. For more information on finally-block, see the FINALLY statement reference entry.

END

Specifies the end of the REPEAT block definition. You must end the REPEAT block definition with the END statement.

Example

In this menu procedure, if you press END-ERROR or ENDKEY when the procedure prompts you for your menu selection, any data you have entered as a selection is undone and the procedure continues to prompt you for a menu selection:

r-rpt.p

DEFINE VARIABLE Selection AS INTEGER NO-UNDO FORMAT "9".

FORM SKIP(3)
  "0 - Exit" at 32
  "1 - Edit Customer File" at 32
  "2 - List Customer File" at 32
  "3 - Edit Item File" at 32
  "4 - List Item File" at 32
  "Enter Choice" TO 30 Selection AUTO-RETURN
  HEADER "Application Name"  "Master Menu" AT 34  "Company" TO 79
  WITH NO-BOX NO-LABELS CENTERED FRAME menu.

/* Create the procedures that are called from the following block. */
REPEAT ON ENDKEY UNDO, RETRY:
  UPDATE Selection WITH FRAME menu.
  HIDE FRAME menu.

  CASE(Selection):
    WHEN 0 THEN LEAVE.
    WHEN 1 THEN RUN custedit.p.
    WHEN 2 THEN RUN custrpt.p.
    WHEN 3 THEN RUN itemedit.p.
    WHEN 4 THEN RUN itemrpt.p.
    OTHERWISE DO:
      BELL.
      MESSAGE "Not a valid choice. Try again.".
    END.
  END CASE.
END. /* REPEAT */

Notes

• Within a REPEAT block, if you are using the FIND NEXT or FIND PREV statement and you change the value of an index field, the AVM makes that change in the index table at the end of the UPDATE or SET statement. Therefore, if you change the value so that the record appears later in the index table, you will see the record again if you FIND NEXT. If you change the value so that the record appears earlier in the index table, you see the record again if you FIND PREV.

  REPEAT:   FIND NEXT Customer.   UPDATE Customer.CustNum. END.

  In this example, if you change Customer 1 to Customer 300, you see that Customer record again at the end of the procedure.

  When you use the PRESELECT option, the AVM builds a special index table that is not updated when index values change. For example, add the PRESELECT option to the previous example:

  REPEAT PRESELECT EACH Customer:   FIND NEXT Customer.   UPDATE Customer.CustNum. END.

  In this example, if you change Customer 2 to Customer 200, you do not see that Customer record until you look it up with a new procedure.

• For SpeedScript, the invalid options are: on-endkey-phrase and on-quit-phrase.

See also

CATCH statement, DO statement, END statement, FINALLY statement, Frame phrase, ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, ON STOP phrase