Functions and Directives Functions and Directives

Function Break() Foundation

Interrupts execution of the current thread.

Syntax
Break( [<Expression>] ) --> NIL
Parameters
<Expression>
<Expression> is an expression with any value. When the optional RECOVER statement is included as part of the BEGIN SEQUENCE..END control structure, the value of <Expression> is passed to RECOVER.
Return

The return value of Break() is always NIL.

Description

The function Break() is generally used only as part of error handling during run time of a program. It is normally called within the BEGIN SEQUENCE..END control structure and is identical in functionality to the BREAK statement. The function Break() (contrary to the BREAK statement) can be called from within a code block. Because of this, Break() is frequently used in user-defined error handling code blocks assigned to the Xbase++ error handling system with the function ErrorBlock().

Break() interrupts the execution of the thread that calls this function. If it is embedded in BEGIN SEQUENCE .. END the thread resumes after the RECOVER or END statement, otherwise the thread will be terminated. When Break() is called in the very first thread outside BEGIN SEQUENCE .. END the program is canceled.

Examples
Break() 
// In the example the UDF DbfNtxUse() is illustrated. It opens 
// a DBF file along with its index files. The data for the 
// index files is passed as an array. When an index file 
// does not exist, a runtime error is generated and the function 
// Break() branches out of the error code block to the code 
// following the RECOVER statement. The missing index file is 
// created there. 

#include "Error.ch" 

PROCEDURE Main 
   LOCAL aIndexFiles 

   aIndexFiles := ; 
      { ; 
         { "custa", "custno" }, ; 
         { "custb", "Upper( lastname + firstname )" },; 
         { "custc", "zip" } ; 
      } 

   DbfNtxUse( "CUSTOMER", aIndexFiles ) 

RETURN 

PROCEDURE DbfNtxUse( cDbfFile, aIndexFiles ) 
   LOCAL nIndexFile, nIndexFiles, bSaveErrorBlock, oError 
   LOCAL cIndexFile, cIndexKey 

   USE (cDbfFile) NEW                // Open a DBF-file 
   nIndexFile := 1 
   nIndexFiles := Len( aIndexFiles ) 

   DO WHILE nIndexFile <= nIndexFiles 

      cIndexFile := aIndexFiles[nIndexFile,1] 
      cIndexKey  := aIndexFiles[nIndexFile,2] 

      oError := NIL 
      bSaveErrorBlock := ErrorBlock( {|e| Break(e)} ) 
      BEGIN SEQUENCE 

         // A missing index file will raise an error. 
         OrdListAdd( cIndexFile ) 

         nIndexFile++ 

      RECOVER USING oError 
         ErrorBlock(bSaveErrorBlock) 

         // Handle the case of non existing files only. 
         IF .NOT. 2 == oError:OsCode 
            Break( oError ) 
         ENDIF 

         // Create the index file and restart with first index file 
         CreateIndexAndReopen( cDbfFile, ; 
                               cIndexKey, ; 
                               cIndexFile ) 

         nIndexFile := 1 

      END SEQUENCE 
      ErrorBlock(bSaveErrorBlock) 

   ENDDO 

RETURN 

PROCEDURE CreateIndexAndReopen( cDbfFile, cIndexKey, cIndexFile ) 

   USE (cDbfFile) EXCLUSIVE 

   INDEX ON &cIndexKey ; 
         TO &cIndexFile 

   // Reopen SHARED without index files 
   USE (cDbfFile) 
RETURN
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.