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.
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” )
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.
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.
&nb