Click above to get retro games delivered to your door ever month!

 BEGIN SEQUENCE 
 Define a sequence of statements for a BREAK
------------------------------------------------------------------------------
 Syntax

     BEGIN SEQUENCE
        <statements>...
     [BREAK [<exp>]]
        <statements>...
     [RECOVER [USING <idVar>]]
        <statements>...
     END [SEQUENCE]

 Arguments

     BREAK <exp> branches execution to the statement immediately
     following the nearest RECOVER statement if one is specified or the
     nearest END SEQUENCE statement.  <exp> is the value returned into the
     <idVar> specified in the USING clause of the RECOVER statement.

     RECOVER USING <idVar> defines a recover point in the SEQUENCE
     construct where control branches after a BREAK statement.  If USING
     <idVar> clause is specified, <idVar> receives the value returned by the
     BREAK statement.  In general, this is an error object.

     END defines the end point of the SEQUENCE control structure.  If no
     RECOVER statement is specified, control branches to the first statement
     following the END statement after a BREAK.

 Description

     BEGIN SEQUENCE...END is a control structure used for exception and
     runtime error handling.  It delimits a block of statements, including
     invoked procedures and user-defined functions.  When a BREAK is
     encountered anywhere in a block of statements following the BEGIN
     SEQUENCE statement up to the corresponding RECOVER statement, control
     branches to the program statement immediately following the RECOVER
     statement.  If a RECOVER statement is not specified, control branches to
     the statement following the END statement, terminating the SEQUENCE.  If
     control reaches a RECOVER statement without encountering a BREAK, it
     branches to the statement following the corresponding END.

     The RECOVER statement optionally receives a parameter passed by a BREAK
     statement that is specified with a return value.  This is usually an
     error object, generated and returned by the current error handling block
     defined by ERRORBLOCK().  If an error object is returned, it can be sent
     messages to query information about the error.  With this information, a
     runtime error can be handled within the context of the operation rather
     than in the current runtime error handler.  See the example below.

     Within a SEQUENCE construct there are some restrictions on what
     statements are allowed between the BEGIN SEQUENCE and RECOVER
     statements.  You cannot RETURN, LOOP, or EXIT between a BEGIN SEQUENCE
     and RECOVER statement.  From within the RECOVER statement block,
     however, you can LOOP, EXIT, BREAK, or RETURN since the SEQUENCE is
     essentially completed at that point.  Using LOOP from within the RECOVER
     statement block is useful for re-executing the SEQUENCE statement block.
     See the example below.

     SEQUENCE constructs are quite flexible.  They can be nested and more
     than one can be defined in the same procedure or user-defined function.
     If more than one SEQUENCE construct is specified, each SEQUENCE should
     delimit one discrete operation.

     For more information on error objects, refer to the Error class in this
     chapter.

 Examples

     .  This code fragment demonstrates a SEQUENCE construct in which
        the BREAK occurs within the current procedure:

        BEGIN SEQUENCE
           <statements>...
           IF lBreakCond
              BREAK
           ENDIF
        RECOVER
           <recovery statements>...
        END

        <recovery statements>...

     .  This example demonstrates an error handler returning an error
        object to the variable specified in the USING clause of the RECOVER
        statement:

            LOCAL objLocal, bLastHandler
            //
            // Save current and set new error handler
            bLastHandler := ERRORBLOCK({ |objErr| ;
                  MyHandler(objErr, .T.) })
            //
            BEGIN SEQUENCE
               .
               . <operation that might fail>
               .
            RECOVER USING objLocal
               //
               // Send messages to objLocal and handle the error
               ? "Error: "
               IF objLocal:genCode != 0
                  ?? objLocal:description
               ENDIF
               .
               .
               .
            END
            //
            // Restore previous error handler
            ERRORBLOCK( bLastHandler )

            FUNCTION MyHandler( objError, lLocalHandler )
               //
               // Handle locally returning the error object
               IF lLocalHandler
                  BREAK objError
               ENDIF
               .
               . <other statements to handle the error>
               .
               RETURN NIL

     .  This example re-executes a SEQUENCE statement block by LOOPing
        from within the RECOVER statement block:

        DO WHILE .T.
           BEGIN SEQUENCE
              .
              . <operation that may fail>
              .
           RECOVER
              IF PrintRecover()
                 LOOP      // Repeat the SEQUENCE statement block
              ENDIF
           END
           EXIT            // Escape from the operation
        ENDDO