xHarbour Reference Documentation > Class Reference (textmode)

Error()

Creates a new Error object.

Syntax

Error( [<cSubSystem>]  , ;
       [<nGenCode>]    , ;
       [<nSubCode>]    , ;
       [<cOperation>]  , ;
       [<cDescription>], ;
       [<aArgs>]       , ;
       [<cModuleName>] , ;
       [<cProcName>]   , ;
       [<nProcLine> ]    ) --> oError

Arguments

<cSubSystem>

This is a character string holding the name of the subsystem where the error occurred. It is assigned to oError:subSystem.

<nGenCode>

This is a numeric value indicating a generic error code. It is assigned to oError:genCode. The file Error.ch contains #define constants used for this parameter. They begin with the prefix EG_.

<nSubCode>

This is a numeric value indicating an error code specific for the subsystem where the error occurred. It is assigned to oError:subCode.

<cOperation>

This is a character string holding the name of the failed operation. It is assigned to oError:operation.

<cDescription>

This is a character string holding a description of the failed operation. It is assigned to oError:description.

<aArgs>

This is an array whose elements hold the arguments of the failed operation. It is assigned to oError:args.

<cModuleName>

This is a character string holding the file name of the module where the error occurred. It is assigned to oError:moduleName.The parameter <cModuleName> defaults to the return value of function ProcFile().

<cProcName>

This is a character string holding the name of the function, method or procedure where the error occurred. It is assigned to oError:procName. The parameter <cProcName> defaults to the return value of function ProcName().

<nProcLine>

This is a numeric value indicating the line number of the source code file where the error occurred. It is assigned to oError:procLine. The parameter <nProcLine> defaults to the return value of function ProcLine().

Return

The function returns a new Error object, optionally filled with information about a runtime error.

Description

Objects of the Error class are used for error handling and error recovery by the xHarbour runtime system. An Error object is created when a runtime error occurs. Information about a runtime error is assigned to instance variables of the object before an exception is triggered by the runtime system. The Error object is then passed to the error handling routine programmed in the xHarbour application.

There are two statements available for user-defined error handling routines: BEGIN SEQUENCE and TRY...CATCH. See these statements for examples of local error handling.

Note:  the default error handling routine is function DefError() implemented in the file source\rtl\ErrorSys.prg

Instance variables

:args

Array holding the arguments of a failed operation.

:canDefault

Indicates if a default recovery is available.

:canRetry

Indicates if a retry operation is possible.

:canSubstitute

Indicates if an erroneous result can be substituted.

:cargo

Instance variable for user-defined purposes.

:description

Character string holding a description of the error.

:fileName

Name of the disk file associated with the operation

:genCode

Generic numeric error code.

:moduleName

Character string holding the name of the PRG source file where the error occurred.

:operation

Character string holding a description of the failed operation.

:osCode

Numeric operating system error code.

:procName

Character string holding the name of the function where the error occurred.

:procLine

Numeric value indicating the line number of the source code file where the error occurred.

:severity

Numeric value indicating error severity.

:subCode

Numeric subsystem-specific error code.

:subSystem

Character string holding the name of the subsystem where the error occurred.

:tries

Number of times the failed operation was attempted to be executed.

Info

See also:	BEGIN SEQUENCE, DosError(), ErrorBlock(), FError(), HB_LangErrMsg(), Neterr(), TRY...CATCH, Throw()
Category:	Object functions
Header:	Error.ch
Source:	rtl\terror.prg, rtl\error.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example is a code snippet from the file WIN32OLE.PRG.
// It demonstrates how a runtime error can be handled using the
// TRY...CATCH statements and how to fill an Error object with
// information about a runtime error.

   METHOD OleValuePlus( xArg ) CLASS TOleAuto

      LOCAL xRet, oErr

      TRY
         xRet := ::OleValue + xArg
      CATCH
         oErr := ErrorNew()
         oErr:Args          := { Self, xArg }
         oErr:CanDefault    := .F.
         oErr:CanRetry      := .F.
         oErr:CanSubstitute := .T.
         oErr:Description   := "argument error"
         oErr:GenCode       := EG_ARG
         oErr:Operation     := '+'
         oErr:Severity      := ES_ERROR
         oErr:SubCode       := 1081
         oErr:SubSystem     := "BASE"

         RETURN Throw( oErr )
      END

   RETURN xRet