Executes a statement or group of statements once for each record in a
 record stream formed by a record selection expression (RSE).  Rdb/VMS
 evaluates all variables when the RSE is compiled, not when the
 statements within the FOR loop execute.  For detailed information on
 the RSE, request HELP on RSE.

 Example:

      RDO>   FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = "00164"
      cont>    MODIFY E USING E.MIDDLE_INITIAL = "M"
      cont>    END_MODIFY
      cont>  END_FOR

Additional information available:

FormatMoreExamplessegmented string FOR

 FOR ────┬─────────────>────────┬───> rse ─────┬───────>───────┬──────┐
         └───> handle-options ──┘              └──> on-error ──┘      │
 ┌─────────────────────────────<──────────────────────────────────────┘
 └───────┬───> statement ────┬───────────>───────────────> 
E
N
D
F
O
R
         └──────────<────────┘

Additional information available:

rseon-errorstatementhandle-options

 Any valid record selection expression.  Request HELP on RSE for a
 complete discussion of record selection expressions.

 ON ERROR ─┬─> statement ─┬─> 
E
N
D
E
R
R
O
R
           └────────<─────┘

 The ON ERROR clause.  This clause specifies the action to be taken if
 an error occurs while Rdb/VMS is compiling the RSE.  Request HELP for
 ON_ERROR for more information.

 Any valid Rdb/VMS data manipulation statement or host language
 statement except INVOKE, COMMIT, or ROLLBACK.

 No statement within the FOR loop can redefine the context variable
 that was defined by the RSE in the FOR statement.

 handle-options =

 ──> ( ─┬─> 
R
E
Q
U
E
S
T
H
A
N
D
L
E ───> var ───────────────────────────┬─> ) ──>
        ├─> 
T
R
A
N
S
A
C
T
I
O
N
H
A
N
D
L
E ───> var ───────────────────────┤
        └─> 
R
E
Q
U
E
S
T
H
A
N
D
L
E ─> var , TRANSACTIONHANDLE ─> var ─┘

Additional information available:

REQUEST_HANDLETRANSACTION_HANDLE

 A keyword followed by a host language variable.  A request handle
 points to the location of a compiled Rdb/VMS request.  If you do not
 supply a request handle explicitly, Rdb/VMS associates a default
 request handle with the compiled request.  Your must use a request
 handle when you want to make an identical query to two different
 databases.

 In Callable RDO, use !VAL as a marker for host language variables.

 You can put parentheses around the host language variable name.

 A keyword followed by a host language variable.  A transaction handle
 identifies each instance of a database attach.  If you do not declare
 the transaction handle explicitly, Rdb/VMS attaches an internal
 identifier to the transaction.

 In Callable RDO, use !VAL as a marker for host language variables.

 You can put parentheses around the host language variable name.

 Normally, you do not need to use this argument.  The ability to
 declare a transaction handle is provided for compatibility with other
 database products and future releases of Rdb/VMS.

 You need the Rdb/VMS READ privilege to the records in a record stream
 to use the FOR statement.

 You can nest FOR loops as an alternative to the CROSS clause to
 perform a join operation.  However, the performance of the CROSS
 clause is usually faster.

 In RDO, each FOR loop has a stream associated with it.  When you use
 nested FOR loops, the actions of one stream may affect how the other
 streams work.  The first RDO statement below shows a query that
 causes concurrent read and write activity to occur in relation
 RELATION3.  Queries that cause concurrent read and write activity
 SHOULD BE AVOIDED because they can return incorrect results.

 RDO> START_TRANSACTION READ_WRITE
 cont> FOR R IN RELATION3 WITH R.FIELD2=1
 cont>     PRINT R.*, R.RDB$DB_KEY
 cont>         FOR T IN RELATION3 WITH T.FIELD1=R.FIELD1 AND T.FIELD2=0
 cont>             ERASE T
 cont>         END_FOR
 cont> END_FOR

 The same problem can be created in an application by opening two
 streams on the same relation with one stream reading data and the
 other modifying it.  You can avoid a problem with concurrent read and
 write activity in a single relation by using query syntax carefully
 or performing the actions in the query serially.

 You can fix the previous query by replacing it with the following two
 queries, which perform the actions in the previous query serially:

 RDO> FOR R IN RELATION3 WITH R.FIELD2=1
 cont>    PRINT R.*, R.RDB$DB_KEY
 cont> END_FOR
 RDO> FOR T IN RELATION3 WITH T.FIELD2=0 AND
 cont>    (ANY R IN RELATION3 WITH R.FIELD1=T.FIELD1 AND R.FIELD2=1)
 cont>    ERASE T
 cont> END_FOR

 If you are interested in printing the records that will be erased,
 the following query works:

 RDO> FOR T IN RELATION3 WITH T.FIELD2=0 AND
 cont>    (ANY R IN RELATION3 WITH R.FIELD1=T.FIELD1 AND R.FIELD2=1)
 cont>    PRINT T.*, T.RDB$DB_KEY
 cont>    ERASE T
 cont> END_FOR

 Example 1

 Create a record stream with a FOR statement in RDO:

 RDO> START_TRANSACTION READ_ONLY
 RDO>
 RDO> FOR D IN DEPARTMENTS WITH D.DEPARTMENT_CODE = "SEUR"
 cont>  PRINT D.DEPARTMENT_CODE,
 cont>        D.DEPARTMENT_NAME,
 cont>        D.MANAGER_ID
 cont>  END_FOR
 RDO>
 RDO> COMMIT

 These statements:

  o  Create a record stream defined by a record selection expression

  o  Retrieve three field values from each record in that stream


 Example 2

 Create a record stream with the FOR statement in BASIC:

 &RDB&  START_TRANSACTION READ_ONLY

 &RDB&  FOR E IN EMPLOYEES CROSS
 &RDB&  S IN SALARY_HISTORY OVER EMPLOYEE_ID
 &RDB&       WITH E.EMPLOYEE_ID = EMPLOYEE_ID
 &RDB&       AND S.SALARY_END MISSING
 &RDB&    ON ERROR
               GOTO 3000
 &RDB&    END_ERROR
 &RDB&    GET
 &RDB&       LAST_NAME = E.LAST_NAME;
 &RDB&       FIRST_NAME = E.FIRST_NAME;
 &RDB&       SALARY = S.SALARY_AMOUNT
 &RDB&    END_GET
 &RDB&  END_FOR

 &RDB&  COMMIT

 This program fragment retrieves the current salary for an employee
 specified by the value of the EMPLOYEE_ID variable.  The example:

  o  Establishes a record stream consisting of the record in the
     EMPLOYEES relation with the ID number that the user supplies in
     the host language variable EMPLOYEE_ID, joined with the
     corresponding current SALARY_HISTORY record

  o  Points to an error-handling subroutine, in case of errors from
     Rdb/VMS

  o  Assigns the values from the FIRST_NAME and LAST_NAME fields of
     EMPLOYEES and the SALARY_AMOUNT field of SALARY_HISTORY to host
     variables

 A special form of the FOR statement sets up a record stream
 consisting of segments from a segmented string field.  Because a
 single segmented string field value is made up of multiple segments,
 a record stream that includes a segmented string field is "nested."
 The outer loop retrieves records that include the field and the inner
 loop retrieves the segments of each field value one at a time.
 Therefore, a FOR statement that retrieves segmented strings looks
 like a set of nested FOR statements.

 Example:

      RDO>  FOR R IN RESUMES
      cont>    FOR S IN R.RES_SEG
      cont>    PRINT S.RDB$LENGTH, S.RDB$VALUE
      cont>    END_FOR
      cont>  END_FOR

Additional information available:

FormatMoreExample

 FOR ──> context-var ───> typebox (I)typebox (N) ──> ss-field ──┬───────>──────┬─┐
                                            └─> on-error ──┘ │
       ┌────────────────────────<────────────────────────────┘
       └─┬─> get-statement ─┬───> 
E
N
D
F
O
R
         └────────<─────────┘

Additional information available:

context-varss-fieldon-errorget-statement

 A context variable.

 A qualified field name that refers to a field defined with the
 SEGMENTED STRING data type.  Note that this field name, like all
 field names in a FOR statement, must be qualified by its own context
 variable.  This second context variable must match the variable
 declared in the outer FOR statement.  See the Examples topic.

 The ON ERROR clause.  This clause specifies the action to be taken if
 an Rdb/VMS error occurs while Rdb/VMS is trying to set up retrieval
 of the next segmented string.  For more details, request HELP on
 ON_ERROR.

 Any valid Rdb/VMS data manipulation language or host language
 statement except INVOKE, COMMIT, or ROLLBACK.  The GET statement can
 reference only the RDB$VALUE and RDB$LENGTH fields.

 If you have invoked a database, you have the necessary privileges to
 use the FOR Statement with Segmented Strings.

 Rdb/VMS defines a special name to refer to the segments of a
 segmented string.  This value expression is equivalent to a field
 name; it names the "fields" or segments of the string.  Furthermore,
 because segments can vary in length, Rdb/VMS also defines a name for
 the length of a segment.  The statement inside the segmented string
 FOR loop must use these names to refer to the segments of the string.
 These names are:

 RDB$VALUE          The value stored in a segment of a segmented
                    string

 RDB$LENGTH         The length in bytes of a segment

 Create a stream whose records contain segmented string fields:

 RDO>  FOR R IN RECORD
 cont>    FOR S IN R.SS_FIELD
 cont>    PRINT S.RDB$LENGTH, S.RDB$VALUE
 cont>    END_FOR
 cont>  END_FOR

 This statement looks like a nested FOR loop.

  o  The outer loop sets up a record stream using the context variable
     R.  The same context variable qualifies the field name, SS_FIELD,
     as in every FOR statement.

  o  The inner loop retrieves the segments of the string field one at
     a time.

  o  The context variable S identifies the segments.

  o  The special segmented string value expressions, RDB$VALUE and
     RDB$LENGTH are qualified by S, the context variable associated
     with the field.