DO statement

Groups statements into a single block, optionally specifying processing services or block properties. Use an END statement to end a DO block.

Syntax

This is the syntax for a DO block:

[ label : ]
DO
  { [ FOR record [ , record ] ... ] }
  [ preselect-phrase ]
  [ query-tuning-phrase ]
  [ variable = expression1 TO expression2 [ BY k ] ]
  [ WHILE expression ]
  [ TRANSACTION ] 
  [ stop-after-phrase ]
  [ on-endkey-phrase ]
  [ on-error-phrase ]
  [ on-quit-phrase ]
  [ on-stop-phrase ]
  { [ frame-phrase ] } :

  <block of statements>

END.

FOR record[ , record]...

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

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

preselect-phrase

The PRESELECT phrase finds selected records from one or more tables. You can access those preselected records with statements such as FIND NEXT.

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

For more information, see the PRESELECT phrase.

query-tuning-phrase

Allows programmatic control over the execution of a DataServer query.

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 ]

The name of a field or variable whose value is incremented in a loop. expression1 is the starting value for variable on the first iteration of the loop. k is the amount to add to variableafter each iteration; it must be a constant. k defaults to 1 if not specified. variable, expression1 and expression2 must be integers.

When variable exceeds expression2 (or is less than expression2 if kis negative) the loop ends. Since expression1 is compared to expression2 at the start of the first iteration of the block, the block can be executed zero times. expression2 is re-evaluated on each iteration of the block.

WHILE expression

Indicates that the DO block continues processing the statements within it. Using the WHILE option turns a DO block into an iterating block. The block iterates as long as the condition specified by the expression is TRUE. The expression is any combination of constants, operators, field names, and variable names that yield a logical value.

TRANSACTION

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

stop-after-phrase

Specifies a time-out value (in seconds) for the block. This is the syntax for the STOP-AFTER phrase:

STOP-AFTER time-limit

For more information see STOP-AFTER phrase.

on-endkey-phrase

Describes the processing that takes place when the ENDKEY condition occurs during a block. This 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.

on-error-phrase

Describes the processing that takes place when there is an error during a block. This is the syntax for 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.

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.

on-stop-phrase

Describes the processing that takes place when the STOP condition 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.

frame-phrase

Specifies the overall layout and processing properties of a frame. This is the syntax for the frame phrase:

WITH [ ACCUM [ max-length ]]      [ at-phrase ][ ATTR-SPACE | NO-ATTR-SPACE ]      [ CANCEL-BUTTON button-name][ CENTERED ]      [ color-specification]      [ COLUMN expression][n COLUMNS ]      [ CONTEXT-HELP ][ CONTEXT-HELP-FILE help-file-name]      [ DEFAULT-BUTTON button-name]      [ DROP-TARGET ]      [[expression] DOWN ][ EXPORT ]      [ WIDGET-ID id-number][ FONT expression]      [ FRAME frame]      [ INHERIT-BGCOLOR | NO-INHERIT-BGCOLOR ]      [ INHERIT-FGCOLOR | NO-INHERIT-FGCOLOR ]      [ KEEP-TAB-ORDER ][ NO-BOX ]      [ NO-HIDE ][ NO-LABELS ][ USE-DICT-EXPS ]      [ NO-VALIDATE ][ NO-AUTO-VALIDATE ]      [ NO-HELP ][ NO-UNDERLINE ]      [ OVERLAY ][ PAGE-BOTTOM | PAGE-TOP ][ RETAIN n]      [ ROW expression][ SCREEN-IO | STREAM-IO ]      [ SCROLL n][ SCROLLABLE ][ SIDE-LABELS ]      [ size-phrase][ STREAM stream| STREAM-HANDLE handle][ THREE-D ]      [ title-phrase][ TOP-ONLY ][ USE-TEXT ]      [ V6FRAME [ USE-REVVIDEO | USE-UNDERLINE ]]      [ VIEW-AS DIALOG-BOX ][ WIDTH n][ IN WINDOW window]

For more information, see the Frame phrase.

Example

This procedure goes through the Customer table and reduces the CreditLimit to 80000 for those Customers that exceed this amount. The procedure uses a simple DO block to process two statements if the CreditLimit is over 80000. Simple DO blocks are most useful for grouping statements together for conditional situations, such as IF...THEN...ELSE.

r-do.p

FOR EACH Customer NO-LOCK:
  DISPLAY Customer.Name Customer.CreditLimit.
  PAUSE 3.
  IF Customer.CreditLimit > 80000 THEN DO:
    Customer.CreditLimit = 80000.
    DISPLAY Customer.Name Customer.CreditLimit.
  END.
END.

Notes

• Use a DO statement rather than a REPEAT statement when you loop through elements of an array. This is more efficient since the AVM does not create separate subtransactions within the transaction.

  The first example, which uses DO, is more efficient than the second:

  DO ix = 1 TO 12: SalesRep.MonthQuota[ix] = 0. END.

  REPEAT ix = 1 TO 12: SalesRep.MonthQuota[ix] = 0. END.

• For SpeedScript, the on-endkey-phrase and the on-quit-phrase do not apply.

See also

FIND statement, FOR statement, Frame phrase, ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, ON STOP phrase, Record phrase, REPEAT statement, STOP-AFTER phrase