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.

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

See also:

Error class, ERRORBLOCK(), RETURN