TOC PREV NEXT INDEX

Put your logo here!


14 Exceptions (excepts.hhf)


The exceptions units contains several things of interest. First, it defines the ExceptionValues enumerated data type that lists out all the standard exceptions in the HLA Standard Library. The second thing provided in the excepts unit is the ex.PrintExceptionError procedure which prints a string associated with the exception number in EAX. Next, the excepts.hhf header file defines the "assert( expr )" macro. Finally, the excepts.hhf header file defines some procedures that the HLA run-time system uses to maintain the exception handling system; these procedures are of interest only to those who want to override the default HLA exception handling mechanisms.

14.1 Exception Constants

The following subsections describe each of the standard HLA exception constants and describe the conditions that lead to the Standard Library routines raising these exceptions. The "excepts.hhf" header file defines these constants. Since this list changes frequently, please refer to the excepts.hhf header file for the most recent list of exception names. HLA and the HLA Standard Library only raise these exceptions; user applications, however, may define other exceptions in addition to these. Of course, user applications may also raise exceptions using these exception constants.

14.1.1 ex.UnknownException (0)

This is a reserved value that HLA's Standard Library functions do not raise. The HLA run-time system displays this exception value if it cannot figure out the source of the interrupt. ex.PrintExceptionError calls also use this value to display an appropriate message for unhandled user exceptions.

14.1.2 ex.StringOverflow (1)

The string functions in the HLA Standard Library raise this exception if the caller attempts to store too many characters into a string variable (causing a string overflow error).

14.1.3 ex.StringIndexError (2)

Some string functions require a parameter that supplies an index into a string. If those functions require that the index be within the range 0..length-1, they will raise this exception to denote an index out of range error.

14.1.4 ex.ValueOutOfRange (3)

Several HLA Standard Library routines raise this exception if an integer calculation overflows. The best examples are the integer input routines (e.g., stdin.geti8) that will raise this exception if the user's input is otherwise legal but out of range for the specific data type (i.e., -128..+127 for stdin.geti8).

14.1.5 ex.IllegalChar (4)

Certain input and conversion routines raise this exception if an unexpected character comes along. An unexpected character is usually a non-ASCII character (character codes in the range $80..$FF). Note that the conversion and input routines do not raise this exception if a non-digit character comes along. See ex.ConversionError to see how the HLA Standard Library handles that exception.

14.1.6 ex.ConversionError (5)

HLA raises this exception whenever there is some sort of error converting data from one from to another (usually, this exception occurs when converting string data to numeric data). For example, when converting a string to an integer value, the HLA Standard Library will raise this exception if it encounters a character that is not legal for that numeric type and is not a delimiter character.

14.1.7 ex.BadFileHandle (6)

The file class and fileio library modules raise this exception if you attempt to read from or write to a file with an illegal file handle (i.e., the file has not been opened or has already been closed).

14.1.8 ex.FileOpenFailure (7)

The HLA file open routines raise this error if there was a catastrophic error opening a file.

14.1.9 ex.FileCloseError (8)

The HLA file close routines raise this error if there was an error closing a file.

14.1.10 ex.FileWriteError (9)

The HLA Standard Library file output routines raise this exception if there is an error while attempting to write data to a file. This is usually a catastrophic error such as file I/O or some hardware error.

14.1.11 ex.FileReadError (10)

The HLA Standard Library file output routines raise this exception if there is an error while attempting to read data from a file. This is usually a catastrophic error such as file I/O or some hardware error.

14.1.12 ex.DiskFullError (11)

The HLA Standard Library raises this exception if you attempt to write data to a disk that is full.

14.1.13 ex.EndOfFile (12)

The HLA Standard Library file I/O routines raise this exception if you attempt to read data from a file after you've reached the end of file. Note that HLA does not raise this exception upon reaching the EOF. You must actually attempt to read beyond the end of the file.

14.1.14 ex.MemoryAllocationFailure (13)

HLA raises this exception if a function attempts to allocate storage and the memory allocation operation fails (because of insufficent storage).

14.1.15 ex.AttemptToDerefNULL (14)

Many HLA Standard Library routines expect a pointer to some object as a parameter. If they do not allow a NULL pointer value (zero) the routines may explicitly test for a NULL value and raise this exception if the user inadventently passes in a NULL pointer. Also see the ex.AccessViolation exception.

14.1.16 ex.CannotFreeMemory (15)

The HLA memory free routines raise this exception if there is an error deallocating memory that was (presumably) allocated earlier.

14.1.17 ex.WidthTooBig (16)

Certain numeric conversion and output functions let you specify a field width value for the conversion. Those routines raise this exception if that field width value is too large (this is nominally 256, but the exact value may be different).

14.1.18 ex.TooManyCmdLnParms (17)

The args.hhf module raises this exception if you specify too many command line parameters. The exact maximum value may vary between versions of the HLA Standard Library, but it's typically a value like 64 or 128.

14.1.19 ex.ArrayShapeViolation (18)

The arrays.hhf module raise this exception if you attempt to copy data from one array to another or otherwise operate on two arrays with incompatible "shapes." The "shape" of an array is the number of dimensions and the bounds on each dimension of that array. Compatible arrays typically have the same number of dimensions and the same bounds on each dimensions (though there are some exceptions to this rule).

14.1.20 ex.ArrayBounds (19)

The arrays.hhf module raises this exception if you attempt to supply the wrong number of array dimensions or one of the array indices is out of bounds for that array.

14.1.21 ex.InvalidDate (20)

The HLA datetime.hhf module raises this expression if you supply an illegal date to a date function. Note that legal dates must fall between Jan 1, 1600 and Dec 31, 9999 and must have valid day and month values (depending on the month and year).

14.1.22 ex.InvalidDateFormat (21)

The HLA date conversion routines raise this exception if the internal date format value is illegal.

14.1.23 ex.TimeOverflow (22)

The HLA datetime.hhf module raises this exception if, during a time calculation, an overflow occurs.

14.1.24 ex.AssertionFailed (23)

The HLA assert statement raises this expression if the value of the assertion expression evaluates false. See the section on assertions later in this section for more details.

14.1.25 ex.ExecutedAbstract (24)

The HLA run-time system will raise this exception if you attempt to execute an abstract method from an abstract class.

14.1.26 ex.AccessViolation ($c0000005)

This is a hardware exception that the CPU raises if you attempt to access an illegal memory or I/O location.

14.1.27 ex.Breakpoint ($80000003)

This is a hardware exception that the CPU raises if you execute an INT 3 (breakpoint) instruction.

14.1.28 ex.SingleStep ($80000004)

This is a hardware exception that the CPU raises after each instruction if the trace flag is set in the EFLAGs register.

14.1.29 ex.PrivInstr ($c0000096)

This is a hardware exception that the CPU raises if you attempt to execute a priviledged instruction while in user (non-kernel) mode.

14.1.30 ex.IllegalInstr ($c000001d)

This is a hardware exception that the CPU raises if you attempt to execute an opcode that is not a legal 80x86 instruction.

14.1.31 ex.BoundInstr ($c000008c)

This is a hardware exception that the CPU raises if you execute a BOUND instruction and the register value is not within the bounds specified by the BOUND memory operand(s).

14.1.32 ex.IntoInstr ($c0000095)

This is a hardware exception that the CPU raises if you execute an INTO instruction and the overflow flag is set.

14.1.33 ex.DivideError ($c0000094)

This is a hardware exception that the CPU raises if you attempt to divide by zero or if the quotient will not fit in the destination operand.

14.1.34 ex.fDenormal ($c000008d)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and a floating point operation produces a demormalized result.

14.1.35 ex.fDivByZero ($c000008e)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and a floating point division by zero occurs.

14.1.36 ex.fInexactResult ($c000008f)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and a floating point operation produces an inexact result.

14.1.37 ex.fInvalidOperation ($c0000090)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and you attempt an illegal operation on the FPU.

14.1.38 ex.fOverflow ($c0000091)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and a floating point operation produces an overflow (see ex.fDenormal and ex.fUnderflow for underflows).

14.1.39 ex.fStackCheck ($c0000092)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and an FPU stack overflow occurs.

14.1.40 ex.fUnderflow ($c0000093)

This is a hardware exception that the FPU raises if you've enable floating point exceptions and an underflow occurs.

14.1.41 ex.InvalidHandle ($c0000008)

Windows raises this exception if you pass it an invalid handle value.

14.1.42 ex.StackOverflow ($c00000fd)

Windows raises this exception if the hardware (80x86) stack exceeds the bounds set by the linker.

14.1.43 ex.ControlC ($c000013a)

If control-C checking is enabled, Windows will raise this exception whenever the user presses control-C on the console device.

14.2 PrintExceptionError

The ex.PrintExceptionError procedure which displays a string associated with the exception number in EAX. Normally, you wouldn't need to call this routine since the HLA run-time system will do this automatically if you don't catch a particular exception. However, if you have an ANYEXCEPTION clause in a TRY..ENDTRY statement, you might want to call this function to display the appropriate message. Note that the value you pass to ex.PrintExceptionError must be one of the values described in the previous section or this function will simply display an "Unknown Exception Error".

The ex.PrintExceptionError procedure opens up a dialog box and displays the associated message. After the user presses the "OK" button in the dialog box, the procedure returns. If the HLA run-time system called this function, then the program aborts. If your program called this function, then it returns control back to your code.

14.3 Assertions

The excepts.hhf header file also defines the "assert( expr )" macro. This macro evaluates the specified expression and raises an exception if the expression is false. The ex.PrintExceptionError routine will display the text of the assert parameter if this macro raises the specified exception. By default, the assert macro is active in a program. However, you may disable asserts within a program by setting the ex.NDEBUG constant (VAL object, actually) to false. By setting ex.NDEBUG to true and false at different points in your program, you may activate and deactivate the assert statements on a line by line basis, if necessary.

The expression in the assert macro must be an expression acceptable to an HLA IF or WHILE statement (specifically, HLA compiles an assert to a JT pseudo-instruction). Note that if ex.NDEBUG is true, HLA does not emit any code whatsoever at all to the output file. Hence there is no run-time penalty for using asserts if you've set ex.NDEBUG to true.

14.4 Miscellaneous

The "excepts.hhf" header file is a special file known to the compiler. If your main program contains a #include( "excepts.hhf" ); statement, the HLA compiler will automatically emit code to call ex.PrintExceptionError if an unclaimed exception occurs. Without this header file, HLA simply prints that an unclaimed exception occurred with no other indication of the problem.



TOC PREV NEXT INDEX