BEGIN SEQUENCE

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

ErrorSys()

ERRORSYS()

Install default error handler

Syntax

      ERRORSYS() --> NIL

Arguments

None.

Returns

ERRORSYS() always return NIL.

Description

ERRORSYS() is called upon startup by Harbour and installs the default error handler. Normally you should not call this function directly, instead use ERRORBLOCK() to install your own error handler.

Compliance

Clipper

Files

Library is rtl

Seealso

ERRORBLOCK(), Error class

C5 Error Class

Error Class Overview

     Provides objects containing information about runtime errors

Description

     An Error object is a simple object that contains information pertaining
     to a runtime error.  Error objects have no methods, only exported
     instance variables.  When a runtime error occurs, CA-Clipper creates a
     new Error object and passes it as an argument to the error handler block
     specified with the ERRORBLOCK() function.  Within the error handler, the
     Error object can then be queried to determine the nature of the error
     condition.

     Error objects can also be returned to the RECOVER statement of a BEGIN
     SEQUENCE construct with a BREAK statement.  Here, the error object can
     be queried for local error handling.  For more detailed information and
     examples refer to the Error Handling Strategies chapter in the
     Programming and Utilities guide.

 Examples

     .  This example demonstrates how a file open operation might be
        handled in an error handler replicating the default CA-Clipper
        behavior.  When, for example, an attempt to open a database file with
        a USE command fails, control returns to the statement following the
        offending command:

        #include "Error.ch"
        #command RETRY      => RETURN (.T.)    // Retry operation
        #command RESUME     => RETURN (.F.)    // Default recovery
        //

        FUNCTION MyError( objError )
           //
           // Handle file open error
           IF objError:genCode == EG_OPEN .AND.;
              objError:canDefault .AND.;
              NETERR()
              //
              RESUME
           ENDIF
           .
           . <other error statements>
           .
           RETURN NIL

     .  This example retries an operation within an error handler a
        specified number of times:

        #include "Error.ch"
        #command RETRY      => RETURN (.T.)    // Retry operation
        #command RESUME     => RETURN (.F.)    // Default recovery
        //

        FUNCTION MyError( objError )
           //
           // Handle printer not ready error
           IF objError:genCode == EG_PRINT .AND.;
              objError:canRetry .AND.;
              objError:tries < 25
              //
              RETRY
           ENDIF
           .
           . <other error statements>
           .
           RETURN NIL

     .  This code fragment returns an error object from an error
        handler to the RECOVER statement for further processing:

        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>
           .
        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

 Files:  Header file is Error.ch, default error handler is in Errorsys.prg.

 
Class Function 

     ErrorNew()    Create a new error object
        ErrorNew() --> objError

        Returns a new Error object.


Exported Instance Variables

args                  An array of function or operator arguments (Assignable)

Contains an array of the arguments supplied to an operator or function when an  argument error occurs. For other types of errors, Error:args contains a NIL value.

canDefault   Indicates whether or not default recovery is available (Assignable)

Contains a logical value indicating whether the subsystem can perform default error recovery for the error condition. A value of true (.T.) indicates that default recovery  is available. Availability of default handling and the actual default recovery strategy  depends on the subsystem and the error condition. The minimum action is simply to  ignore the error condition.

Default recovery is requested by returning false (.F.) from the error block invoked to handle the error. Note that Error:canDefault is never true (.T.) if Error:canSubstitute is true (.T.).

canRetry       Indicates whether or not a retry is possible after an error (Assignable)

Contains a logical value indicating whether the subsystem can retry the operation that caused the error condition. A value of true (.T.) indicates that a retry is possible. Retry may or may not be available, depending on the subsystem and the error condition.

Retry is requested by returning true (.T.) from the error block invoked to handle the error. Note that Error:canRetry never contains true (.T.) if Error:canSubstitute contains true (.T.).

canSubstitute Indicates if a new result can be substituted after an error (Assignable)

Contains a logical value indicating whether a new result can be substituted for the operation that produced the error condition. Argument errors and certain other simple errors allow the error handler to substitute a new result value for the failed operation. A value of true (.T.) means that substitution is possible.

The substitution is performed by returning the new result value from the code block invoked to handle the error. Note that Error:canSubstitute is never true (.T.) if either Error:canDefault or Error:canRetry is true (.T.).

description  Character description of the error condition (Assignable)

Contains a character string that describes the error condition.  A zero-length string indicates that the subsystem does not provide a printable description for the error. If Error:genCode is not zero, a printable description is always available.

filename        Name of the file associated with the error (Assignable)

Contains a character value representing the name originally used to open the file associated with the error condition. A zero-length string indicates either that the error condition is not associated with a particular file or that the subsystem does not retain filename information.

genCode        Clipper error code number (Assignable)

Contains an integer numeric value representing a Clipper generic error code. Generic error codes allow default handling of similar errors from different subsystems. A value of zero indicates that the error condition is specific to the subsystem and does not correspond to any of the generic error codes. The header file, Error.ch, provides a set of manifest constants for generic error codes.

operation     Character description of the failed operation (Assignable)

Contains a character string that describes the operation being attempted when the error occurred. For operators and functions, Error:operation contains the name of the operator or function. For undefined variables or functions, it contains the name of the variable or function. A zero-length string indicates that the subsystem does not provide a printable description of the operation.

osCode            Operating system error code number (Assignable)

Contains an integer numeric value representing the operating system error code associated with the error condition. A value of zero indicates that the error condition was not caused by an error from the operating system. When Error:osCode is set to a value other than zero DOSERROR() is updated with the same value.

Error:osCode properly reflects the DOS extended error code for file errors. This allows proper distinction between errors which result from sharing violations (e.g., opening EXCLUSIVE when another process has already opened the file) and access violations (e.g., opening read/write when the file is marked read-only).

For a list of DOS error codes refer to the Error Messages and Appendices guide.

severity          Indicates error severity (Assignable)

Contains a numeric value indicating the severity of the error condition. Four standard values are defined in Error.ch:

Error:severity Values
———————————————————————
Error.ch               Meaning
———————————————————————
ES_WHOCARES The condition does not represent a failure; the
error is informational.
ES_WARNING  The condition does not prevent further operations,
but may result in a more serious error later.
ES_ERROR         The condition prevents further operations without
corrective action of some kind.
ES_CATASTROPHIC The condition requires immediate termination of
the application.
———————————————————————

Note that the Clipper runtime support code only generates errors with severities of ES_WARNING or ES_ERROR.

subCode         Subsystem-specific error code number (Assignable)

Contains an integer numeric value representing a subsystem-specific error code. A value of zero indicates that the subsystem does not assign any particular number to the error condition.

subSystem   Character description of the subsystem generating the error (Assignable)

Contains a character string representing the name of the subsystem generating the error. For errors with basic Clipper operators and functions, the subsystem name “BASE” is given. For errors generated by a database driver, Error:subSystem contains the name of the database driver.

tries                   Number of times the failed operation has been attempted (Assignable)

Contains an integer numeric value representing the number of times the failed operation has been attempted. When Error:canRetry is true (.T.), Error:tries can be used to limit the number of retry attempts. A value of zero indicates that the subsystem does not track the number of times the operation has been tried.

See Also: BEGIN SEQUENCE DOSERROR() ERRORBLOCK() NETERR()