Exceptions Module (excepts.hhf)

The exceptions module 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.

### The Exceptions Module

To use the exceptions functions in your application, you will need to include one of the following statements at the beginning of your HLA application:

#include( “excepts.hhf” )

or

#include( “stdlib.hhf” )

### Exception Resource Reduction

By default, if you include excepts.hhf or stdlib.hhf in your HLA main program, HLA will automatically link in a set of strings that describe, in detail, each of the possible exceptions. This string data consumes a considerable amount of space and may not be necessary if you’re not taking advantage of HLA’s exception-handling system.

HLA will link in these strings if the compile-time variable @exceptions contains true when HLA encounters the begin associated with the main program. If you would like HLA to link in a single (small) string in place of this huge table of strings, just set the @exceptions compile-time variable to false after include excepts.hhf (or stdlib.hhf), e.g,

#include( “excepts.hhf” )

?@exceptions := false;

This will reduce the size of your executable. Note, however, that you’ll get a single “unhandled exception” error message if an unhandled error ever comes along. So during debugging, it’s probably best to leave the exception strings in the program and remove them only for a release of your program.

### Exception Constants

The following paragraphs 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.

/* 0 */ UnknownException,

// String related exceptions:

/* 1 */ StringOverflow,

/* 2 */ StringIndexError,

// General exceptions:

/* 3 */ ValueOutOfRange,

/* 4 */ IllegalChar,

/* 5 */ AttemptToDerefNULL,

/* 6 */ TooManyCmdLnParms,

/* 7 */ AssertionFailed,

/* 8 */ ExecutedAbstract,

/* 9 */ BadObjPtr,

/* 10 */ InvalidAlignment,

// Formatting and conversion errors:

/* 11 */ ConversionError,

/* 12 */ WidthTooBig,

// File-related exceptions:

/* 13 */ BadFileHandle,

/* 14 */ FileNotFound,

/* 15 */ FileOpenFailure,

/* 16 */ FileCloseError,

/* 17 */ FileWriteError,

/* 18 */ FileReadError,

/* 19 */ FileSeekError,

/* 20 */ DiskFullError,

/* 21 */ AccessDenied,

/* 22 */ EndOfFile,

// FileSys-related exceptions:

/* 23 */ CannotCreateDir,

/* 24 */ CannotRemoveDir,

/* 25 */ CannotRemoveFile,

/* 26 */ CDFailed,

/* 27 */ CannotRenameFile,

// Memory management exceptions:

/* 28 */ MemoryAllocationFailure,

/* 29 */ MemoryFreeFailure,

/* 30 */ MemoryAllocationCorruption,

/* 31 */ AttemptToFreeNULL,

/* 32 */ BlockAlreadyFree,

/* 33 */ CannotFreeMemory,

/* 34 */ PointerNotInHeap,

// Array exceptions:

/* 35 */ ArrayShapeViolation,

/* 36 */ ArrayBounds,

// Time/date exceptions:

/* 37 */ InvalidDate,

/* 38 */ InvalidDateFormat,

/* 39 */ TimeOverflow,

/* 40 */ InvalidTime,

/* 41 */ InvalidTimeFormat,

// Hardware/OS related exceptions

/* 42 */ AccessViolation,

/* 43 */ InPageError,

/* 44 */ NoMemory,

/* 45 */ InvalidHandle,

/* 46 */ ControlC,

/* 47 */ StackOverflow,

/* 48 */ Breakpoint,

/* 49 */ SingleStep,

/* 50 */ PrivInstr,

/* 51 */ IllegalInstr,

/* 52 */ BoundInstr,

/* 53 */ IntoInstr,

/* 54 */ DivideError,

/* 55 */ fDivByZero,

/* 56 */ fInexactResult,

/* 57 */ fInvalidOperation,

/* 58 */ fOverflow,

/* 59 */ fUnderflow,

/* 60 */ fStackCheck,

/* 61 */ fDenormal

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.

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

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.

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

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.

ex.AttemptToDerefNULL(5)

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.

ex.TooManyCmdLnParms(6)

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.

ex.AssertionFailed(7)

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.

ex.ExecutedAbstract(8)

The HLA run-time system raises this exception if you attempt to execute an abstract class method that has not been overridden and defined.

ex.BadObjPtr(9)

The HLA run-time system raises this exception if you attempt to execute a class method using an illegal pointer.

ex.InvalidAlignment(10)

HLA raises this exception if you specify an illegal alignment value for an allocation operation.

ex.ConversionError(11)

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.

ex.WidthTooBig(12)

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

ex.BadFileHandle(13)

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

ex.FileNotFound(14)

HLA raises this exception if you attempt to open (or otherwise access by name) a file and the system could not find the path/filename you specified.

ex.FileOpenFailure(15)

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

ex.FileCloseError(16)

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

ex.FileWriteError(17)

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.

ex.FileReadError(18)

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.

ex.FileSeekError(19)

The HLA Standard Library file routines raise this exception if there was an error while attempting to seek to some new position in a file.

ex.DiskFullError(20)

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

ex.AccessDenied(21)

The HLA Standard Library raises this exception if you attempt to access a file for which you do not have proper access permission.

ex.EndOfFile(22)

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.

ex.CannotCreateDir(23)

The HLA Standard Library mkdir function raises this exception if you attempt to create a subdirectory and the system returns an error.

ex.CannotRemoveDir(24)

The HLA Standard Library rmdir function raises this exception if you attempt to remove a subdirectory and the system returns an error.

ex.CannotRemoveFile(25)

The HLA Standard Library rmdir function raises this exception if you attempt to remove a file and the system returns an error.

ex.CDFailed(26)

The HLA Standard Library raises this exception if you attempt to switch to a new working directory and the system could not find that directory or the change working directory operation otherwise failed.

ex.CannotRenameFile(27)

The HLA Standard Library raises this exception if you attempt to rename a file and the operation failed.

ex.MemoryAllocationFailure(28)

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

ex.MemoryFreeFailure(29)

HLA raises this exception if you attempt to free storage and the request could not be satisfied (see also: CannotFreeMemory).

ex.MemoryFreeFailure(30)

HLA raises this exception if you attempt to free storage and the request could not be satisfied (see also: CannotFreeMemory).

ex.AttemptToFreeNULL(31)

HLA raises this exception if you attempt to free storage storage but you pass a NULL pointer to be freed.

ex.BlockAlreadyFree(32)

HLA raises this exception if you attempt to free storage storage that has already been freed.

ex.CannotFreeMemory(33)

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

ex.PointerNotInHeap(34)

The HLA memory management routines raise this exception if you pass a pointer to an object that is supposed to be on the heap, but the pointer does not reference any object on the heap.

ex.ArrayShapeViolation(35)

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

ex.ArrayBounds(36)

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.

ex.InvalidDate(37)

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

ex.InvalidDateFormat(38)

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

ex.TimeOverflow(39)

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

ex.InvalidTime(40)

The HLA datetime.hhf module raises this expression if you supply an illegal time to a time function. Note that legal times must fall between 00:00:00 and 23:59:59.

ex.InvalidTimeFormat(41)

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

ex.AccessViolation(42)

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

ex.InPageError(43)

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

ex.NoMemory(44)

This is an exception that the OS raises if it cannot provide memory for the requested operation.

ex.InvalidHandle(45)

This is an exception that the OS raises if it you pass it an invalid handle value for some operation.

ex.ControlC(46)

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

ex.StackOverflow(47)

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

ex.Breakpoint(48)

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

ex.SingleStep(49)

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

ex.PrivInstr(50)

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

ex.IllegalInstr(51)

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

ex.BoundInstr(52)

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

ex.IntoInstr(53)

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

ex.DivideError(54)

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.

ex.fDivByZero(55)

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

ex.fInexactResult(56)

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.

ex.fInvalidOperation(57)

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.

ex.fOverflow(58)

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

ex.fUnderflow(59)

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

ex.fStackCheck(60)

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

ex.fDenormal(61)

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.

### Exception Messages

The exceptions module provides two functions for converting exception numbers into meaningful messages.

procedure ex.exceptionMsg( exceptionCode:dword; msg:string );

ex.exceptionMsg converts the exception code passed in the exceptionCode parameter to a string message and stores the resulting string into the string pointed at by the msg parameter. The msg string must be large enough to hold the result (128 characters should be sufficient). Note that this function cannot raise any exceptions because it may be called from inside an exception handler, hence the requirement that msg be of sufficient size to hold the string.

Note: no “ex.a_exceptionMsg” function exists because the error code resulting in the call to the function might be an “out of memory” error and it wouldn’t do to have this function produce an error.

If the exception code is outside the range of the valid exception codes, this function returns the message associated with the “unknown exception” code.

HLA high-level calling sequence examples:

static

msg :str.strvar(256);

.

.

.

ex.exceptionMsg( someCode, msg );

stdout.put( msg );

procedure ex.printExceptionError;

ex.printExceptionError displays the message associated with the exception code in EAX in a form appropriate to the OS (e.g., under Windows this brings up a dialog box, under Linux this prints the message to the standard error device).

##