$FUNCNAME$
  ERRORBLOCK()
$CATEGORY$
  CODEBLOCK,SYSTEM,INFO,MISCELLANEOUS
$SUMMARY$
   Post a code block to execute when a runtime error occurs
$LANG_RU$
           
$SYNTAX$
     ERRORBLOCK([<bErrorHandler>]) --> bCurrentErrorHandler
$LANG_RU$
     ERRORBLOCK([<  >]) -->    
$ARGUMENTS$
     <bErrorHandler> is the code block to execute whenever a runtime
     error occurs.  When evaluated, the <bErrorHandler> is passed an error
     object as an argument by the system.
$LANG_RU$
     <  > -   ,   
        .   < 
     >       ERROR-.
$RETURNS$
     ERRORBLOCK() returns the current error handling code block.  If no error
     handling block has been posted since the program was invoked,
     ERRORBLOCK() returns the default error handling block.
$LANG_RU$
     ERRORBLOCK()      .  
              ,
     ERRORBLOCK()      ,  
     .
$DESCRIPTION$
     ERRORBLOCK() is an error function that defines an error handler to
     execute whenever a runtime error occurs.  Specify the error handler as a
     code block with the following form,

     { |<oError>| <expression list>,... }

     where <oError> is an error object containing information about the
     error.  Within the code block, messages can be sent to the error object
     to obtain information about the error.  Returning true (.T.) from the
     error handling block retries the failed operation and false (.F.)
     resumes processing.

     The error handling code block can be specified either as a list of
     expressions or as a call to a user-defined function.  A call to a user-
     defined function is more useful since you can use xClipper control
     statements instead of expressions.  This is particularly the case if
     there is a BEGIN SEQUENCE pending and you want to BREAK to the nearest
     RECOVER statement.

     As this implies, error handling blocks can be used in combination with
     BEGIN SEQUENCE...END control structures.  Within an error handling
     block, you handle device, low-level, and common errors that have a
     general recovery mechanism.  If the operation needs specific error
     handling, define a BEGIN SEQUENCE then BREAK to the RECOVER statement,
     returning the error object for local processing.  See the example below.

     If no <bErrorHandler> has been specified using ERRORBLOCK() and a
     runtime error occurs, the default error handling block is evaluated.
     This error handler displays a descriptive message to the screen, sets
     the ERRORLEVEL() to 1, then QUITs the program.

     Since ERRORBLOCK() returns the current error handling block, it is
     possible to specify an error handling block for an operation saving the
     current error handling block, then restore it after the operation has
     completed.  Also, error handlers specified as code blocks, can be passed
     to procedures and user-defined functions, and RETURNed as values.

     For more information on the structure and operations of error objects,
     refer to the Error class entry in this chapter and the "Error Handling
     Strategies" chapter in the Programming and Utilities Guide.
$LANG_RU$
     ERRORBLOCK() -    ,  
     ,      
     .         
      :

     { | <ERROR-> | < >, ... }

       <ERROR-> -  ERROR-,  
      .         
      ERROR      .
       "" (.T.),    
       ,   ,  
       "" (.F.).

      ,  ,     
          .    
        ,     
            xClipper 
      .

        ,   
       BEGIN SEQUENCE,     
         BREAK   
      RECOVER.  ,     
         BEGIN SEQUENCE...END. 
            ,
          ,    - 
      .

           , 
      BEGIN SEQUENCE    BREAK  
         RECOVER,  ERROR- 
       (    ).

        ERRORBLOCK()       
     <  >     ,
        ,   .   
          , ERRORLEVEL()  
     1,     QUIT.

      ,  ERRORBLOCK()     ,
            
        ,   .  ,
        ,    ,
       ,        
           .

             ERROR-
        "Error "   "  ".
$EXAMPLES$
       This code fragment posts, and then calls an error handling
	block when there is an error within a BEGIN SEQUENCE construct:

	LOCAL bErrorHandler, bLastHandler, objErr
	bErrorHandler := { |oError| ;
	      MyErrorHandler(oError) }
	//
	// Save current handler
	bLastHandler := ERRORBLOCK(bErrorHandler)
	//
	BEGIN SEQUENCE
	   .
	   . <operation statements>
	   .
	// Receive error object from BREAK
	RECOVER USING oErrorInfo
	   .
	   . <recovery statements>
	   .
	END
	ERRORBLOCK(bLastHandler)      // Restore handler
	RETURN

	FUNCTION MyErrorHandler( oError )
	   //
	   BREAK oError      // Return error object to RECOVER
	   RETURN NIL
$LANG_RU$
         ,    
               
        BEGIN SEQUENCE:

       LOCAL bErrorHandler, bLastHandler, objError
       bErrorHandler := { | objError | MyErrorHandler( objError ) }
       //
       bLastHandler := ERRORBLOCK( bErrorHandler )
       //   
       BEGIN SEQUENCE
	  ...
	  ...<>
	  ...
       RECOVER USING objErrorInfo //  -  BREAK
	  ...
	  ...< >
	  ...
       END
       ERRORBLOCK(bLastHandler) //  
       RETURN

     FUNCTION MyErrorHandler( objError )
       //
       BREAK objError //  -  RECOVER
       RETURN NIL
$SEEALSO$

$END$
