HLA Standard Library Reference Manual

Passing Parameters to Standard Library Routines

Parameter Passing

Standard library functions typically compute some value based on a set of input values. Understanding how to pass these parameter values to the standard library routines is important if you want to make efficient calls to the library routines.

Most standard library functions expect their parameters in one of two locations – in one or more registers or on the stack (or both). Generally, standard library functions preserve all the general-purpose register values across a call, with the exception of those functions that explicitly return a value in a register (or multiple registers, if needed). Therefore, the standard library functions are careful about passing values to a function in a register because such semantics might require the caller to use a register to hold a parameter value that it is already using for a different purpose. However, if a function returns some result in a register, then the standard library routines assume that the register’s contents are fair game on input and may specify the use of that register as an input parameter. In almost every other case, the standard library routines expect the caller to pass parameters on the stack, though there are a few exceptions to this rule.

In most cases, the standard library routines only use a register to pass a parameter when there is exactly one input parameter and one function return result. Typically, the functions will use the EAX register as both the input and output value. In a few rare cases, a function may have two or more parameters with one parameter being passed in a register and the remaining parameters being passed on the stack.

If you are using a high-level calling syntax, you should take care when calling routines that pass multiple parameters in registers. Consider the conv.bToBuf (byte/hex string conversion to buffer) function:

procedure conv.bToBuf( b:byte in al; var buffer:var in edi );

HLA will automatically emit code that loads the registers when you call this function. E.g., the following

conv.bToBuf( b, myBuffer );

will emit the following code:

mov( b, al );

lea( edi, buffer );

call conv.bToBuf;

Suppose, however, that you write code like the following:

conv.bToBuf( b, [eax] ); // EAX points at the buffer

In this case, HLA will generate the following code, which will probably not do what you want:

mov( bl, al ); // Load b parameter into AL, as before

mov( eax, edi ); // EAX’s value was munged by the instruction above

call conv.bToBuf;

While the problem is obvious when writing low-level code, the high-level invocation hides the problem. This is one drawback to using a high-level invocation of the library code: it tends to hide what’s going on and problems like this, though they are very rare, are more easily spotted using low-level code. In defense of the high-level invocation style, it catches far more common errors than it misses, so this isn’t sufficient reason to avoid using high-level invocations.

The correct solution, by the way, is to always be aware of where the standard library routines pass their parameters. When the standard library passes a given parameter in a register, you should attempt to have that value sitting in the register when you call the function. This is safest and generates the most efficient code. For example, consider the following call to the conv.btoBuf library routine:

conv.bToBuf( al, [edi] );

Because the parameter data is already sitting in the registers where conv.bToBuf expects them, this generates the following (very efficient) code:

call bToBuf;

Passing Parameters by Reference and by Value

The standard library routines generally employ one of two different parameter passing mechanisms – pass by value and pass by reference. Pass by value, as its name implies, passes the value of a parameter to a function. For small objects (say, less than 16 bytes or so), pass by value is very efficient. For large objects (e.g., arrays or records larger than 16 bytes or so) the caller must make a copy of the data when passing it to a subroutine, this data copy operation can be very slow if the data object is large. Therefore, the standard library does not use pass by value when passing arrays, records, or other large data structures to a library routine.

Note that the decision to use pass by reference or pass by value is entirely up to the routine’s designer. If you’re calling a standard library routine you must use the same parameter passing mechanism the designer used when writing the function. The function’s documentation will tell you whether a parameter is passed by reference or by value (or you can read the HLA prototype for a function which will also tell you the parameter passing mechanism).

Pass by reference parameters pass the 32-bit address of the actual parameter to their corresponding function. Because an address is always 32 bits, regardless of the actual parameter data size, passing a large parameter by reference can be far more efficient than passing that same parameter by value. Another benefit (or drawback, in certain cases) to using pass by reference parameters is that the function can modify the value of the actual parameter object because it has the memory address of that object. For more details on the semantics of pass by reference versus pass by value, check out the chapter on procedures and functions in The Art of Assembly Language.

When passing a parameter by reference to a function, you must first compute the address of that object and pass the address to the function. For example, consider the following function prototype:

procedure someFunction( var refParm:byte );

(for those unfamiliar with HLA syntax, the "var" prefix tells HLA that refParm is a pass by reference parameter.) To call someFunction, you must push the address of the actual parameter onto the stack. If the parameter is a static object (e.g., an HLA STATIC, READONLY, or STORAGE variable), then you can compute the address using the HLA "&" (address-of operator), thusly:

pushd( &actualByteParameter );

call someFunction;

If the actual parameter is an automatic variable, or you reference it using some complex addressing mode (other than displacement-only), then you’d use code like the following to pass actualByteParameter to someFunction:

lea( eax, actualByteParameter );

push( eax );

call someFunction;

Note that this scheme, unfortunately, makes use of a general-purpose 32-bit register.

Of course, you can use the HLA high-level function invocation syntax to automatically generate the calling sequence for you:

someFunction( actualByteParameter );

HLA is smart enough to determine the storage class of the actualByteParameter object and generate appropriate code to pass that parameter’s address on the stack. Note that, unlike the example given earlier, HLA does not wipe out the value in the EAX register if it needs to compute the parameter’s address with an LEA instruction; HLA will always preserve all register values unless you explicitly state that you’re passing the parameter in a 32-bit register. For simple local variables or other variables allocated on the stack (e.g., parameters passed into the current function), HLA will actually generate code like the following:

push( ebp ); // Assumes EBP points at the current stack frame

add( @offset( actualByteParameter ), (type dword [esp]));

This pushes the address of a local variable or parameter onto the stack without affecting any general-purpose register values (other than ESP, which we expect).

Note that registers do not have addresses. Therefore, you cannot pass a register by reference to a function; i.e., the following is always illegal:

someFunction( edi );

Of course, what most programmer’s mean when they attempt something like this is that EDI contains the address of the variable to pass to the function. However, HLA assumes that you’re trying to take the address of EDI, which is always illegal. The quick and dirty way to handle this issue is to explicitly tell HLA that EDI is a pointer to the data using an invocation like this:

someFunction( [edi] );

This approach works great when the 32-bit address appears in a register. In the more general case, the 32- bit value could appear in any 32-bit object (e.g., in a pointer variable). You can use HLA’s VAL prefix to explicitly tell HLA to treat a 32-bit value as an address to be passed as a reference parameter, e.g.,

someFunction( val edi );

someFunction( val dwordVar );

HLA is actually smart enough to recognize certain special cases where you’re trying to pass the contents of a pointer variable as a reference parameter. Consider the following HLA code fragment:

static

ptrVar :pointer to byte := &someStaticByteVar;

someFunction( ptrVar );

HLA realizes that ptrVar is a pointer to a byte object and will automatically push ptrVar’s value onto the stack rather than generating an error. No explicit VAL will be necessary. Note that the base type of the pointer variable must match the reference parameter’s type for this call to be successful.

HLA supports a special "untyped pass by reference parameter" syntax. The following example demonstrates this:

procedure untypedRefParm( var anyMemoryType: var );

Note that the parameter does not have an explicit type. The keyword "var" tells the compiler that the parameter is an untyped reference parameter and any memory variable can be passed to this function.

If you pass a variable name as an actual parameter for an untyped reference parameter, HLA will always take the address of that object, regardless of it’s type. If you want to pass the value of a pointer variable, rather than the address of that pointer variable, then you must explicitly supply the VAL prefix, e.g.,

untypedRefParm( val ptrVal );

HLA string objects are hybrid pointer/value objects. An HLA string variable is a dword object that contains a pointer to the actual string data. Consider, though, the following HLA procedure declaration:

procedure someStrFunction( s:string );

This function has a single pass-by-value parameter. It might seem confusing that this is a pass-by-value object as it passes the address of the actual character data that makes up the string to the function. However, keep in mind that a string object is a pointer and what you’re really passing by value is the value of that pointer variable. If you were to pass a string object by reference, what you would be passing is the address of the string variable (that is, the address of the address of the actual character data). For this reason, if a 32-bit register contains the value of a string variable (that is, the register contains the address of the actual character data), then the following call to someStrFunction is perfectly legitimate:

someStrFunction( eax );

Passing Byte Parameters on the Stack

For efficiency reasons, standard library routines always pass all parameters as a multiple of four bytes. When passing a byte-sized parameter on the stack by value, the actual parameter value consumes the L.O. byte of the double word passed on the stack. The function ignores the H.O. three bytes of the value passed for this parameter, though by convention (to make debugging a little easier) you should try to pass zeros in the H.O. three bytes if it is not inconvenient to do so.

When passing a byte-sized constant, you should simply push the dword containing the 8-bit value, e.g,

pushd( 5 );

call someLibraryRoutine;

When passing the 8-bit value of the 8-bit registers AL, BL, CL or DL onto the stack, you should simply push the 32-bit register that holds the 8-bit register, e.g.,

push( eax ); // Pushes AL onto the stack

call someLibraryRoutine;

push( ebx ); // Pushes BL onto the stack

call someOtherLibraryRoutine;

Note that this trick does not apply to the AH, BH, CH, or DH registers. The best code to use when you need to push these registers is to drop the stack down by four bytes and then move the desired register into the memory location you’ve just created on the stack, e.g.,

sub( 4, esp );

mov( AH, [esp] ); // Pushes AH onto the stack

call someLibraryRoutine;

sub( 4, esp );

mov( BH, [esp] ); // Pushes BH onto the stack

call anotherLibraryRoutine;

Here’s another way you can accomplish this (a little slower, but leaves zeros in the H.O. three bytes):

pushd( 0 );

mov( CH, [esp] ); // Pushes CH onto the stack

call someLibraryRoutine;

When passing a byte-sized variable, you should try to push the variable’s value and the following three bytes, using code like the following (HLA syntax):

pushd( (type dword eightBitVar ));

call someLibraryroutine;

There is one drawback to the approach above. In three very rare cases the code above could cause a segmentation fault. If the 8-bit variable is located on the last three bytes of a page in memory (4,096 bytes) and the next memory page is not readable, the system will generate a fault if you attempt to push all four bytes. In such a case, the next best solution, if a register is available, is to move the 8-bit value into AL, BL, CL, or DL and push the corresponding 32-bit register. If no registers are available, then you can write code like the following:

push( eax );

mov( byteVar, al );

mov( al, [esp+4] );

pop( eax );

call someLibraryRoutine;

This code is ugly and slightly inefficient, but it will always work (assuming, of course, you don’t get a stack overflow).

The HLA compiler will generate code similar to this last example if you pass a byte variable as the actual parameter to a library function expecting an 8-bit value parameter:

someLibraryRoutine( byteVar );

Therefore, if efficiency is a concern to you, you should try to load the byte variable (byteVar in this example) into AL, BL, CL, or DL prior to calling someLibraryRoutine, e.g.,

mov( boolVar, al );

someLibraryRoutine( al );

Another solution, if you want to use an HLA high-level-like calling sequence, is to use a hybrid calling sequence and explicitly specify the instruction(s) to use to pass a byte-sized parameter on the stack. For example,

someLibraryRoutine( #{ push( (type dword boolVar) ); }# );

Unfortunately, you lose the benefit of type checking and other semantic checks the compiler would normally do for you when using this hyrbrid syntax. Nevertheless, this scheme does have the advantage of encapsulating the parameter pushing code into a single sequence, so that it’s obvious which instruction(s) go with the particular parameter. This is not the case when you manually push the parameters onto the stack as in the earlier examples.

Passing Word Parameters on the Stack

For efficiency reasons, standard library routines always pass all parameters as a multiple of four bytes. When passing a word-sized parameter on the stack by value, the actual parameter value consumes the L.O. two bytes of the double word passed on the stack. The function ignores the H.O. word of the value passed for this parameter, though by convention (to make debugging a little easier) you should try to pass zeros in the H.O. word if it is not inconvenient to do so.

When passing a word-sized constant, you should simply push the double word containing the 16-bit value, e.g,

pushd( 5 );

call someLibraryRoutine;

When passing the 16-bit value of a 16-bit register (AX, BX, CX, DX, SI, DI, BP, or SP) onto the stack, you should simply push the 32-bit register that holds the 16-bit register, e.g.,

push( eax ); // Pushes AX onto the stack

call someLibraryRoutine;

push( ebx ); // Pushes BX onto the stack

call someOtherLibraryRoutine;

When passing a word-sized variable, you should try to push the variable’s value and the following two bytes, using code like the following (HLA syntax):

pushd( (type dword sixteenBitVar ));

call someLibraryroutine;

There is one drawback to the approach above. In three very rare cases the code above could cause a segmentation fault. If the 16-bit variable is located on the last three bytes of a page in memory (4,096 bytes) and the next memory page is not readable, the system will generate a fault if you attempt to push all four bytes. In such a case, the next best solution, is to use two consecutive pushes:

pushw( 0 ); // H.O. word is zeros

push( sixteenBitVar );

call someLibraryRoutine;

The HLA compiler will generate code similar to this last example if you pass a word variable as the actual parameter to a library function expecting a 16-bit value parameter:

someLibraryRoutine( wordVar );

Passing DWord Parameters on the Stack

Because 32-bit dword objects are the native x86 data type, there are only a few issues with passing 32-bit parameters on the stack to a standard library routine.

First of all, and this applies to all stack operations not just 32-bit pushes and pops, you should always keep the stack 32-bit aligned. That is, the value in ESP should always contain a value that is a multiple of four (i.e., the L.O. two bits of ESP must always contain zeros). If this is not the case, many standard library routines will fail.

When passing a 32-bit value onto the stack, just about any mechanism you can use to push that value is perfectly valid. You can efficiently push constants, registers, and memory locations using a single push instruction, e.g.,

pushd( 12345 ); // Passing a 32-bit constant

push( mem32 ); // Passing a dword variable

push( eax ); // Passing a 32-bit register

call someLibraryRoutine;

One type of double word parameter deserves special mention – a reference parameter. Reference parameters pass the address of their object on the stack rather than the value of the object (that is, they pass a pointer to the actual object). HLA actually supports several different reference parameter types including pass by reference (VAR) parameters, pass by result (RESULT) parameters, and pass by value/returned (VALRES) parameters. Of these three parameter types, the standard library only uses the VAR (pass by reference) type, though if you ever see a function that uses one of these other parameter mechanisms the calling sequence is exactly the same.

When passing a parameter by reference, you must push the address of the actual parameter (rather than its value) onto the stack. For static objects, you can use the push immediate instruction, e.g., (in HLA syntax):

pushd( &staticVar );

call someLibraryRoutine;

For automatic variables, or objects whose address is not a simple static offset (e.g., a complex pointer address involving registers and what-not), you’ll have to use the LEA instruction to first compute the address and then push that register’s value, e.g.,

lea( eax, anAutomaticVar ); // Variable allocated on the stack

push( eax );

call someLibraryRoutine;

If the variable’s address is a simple offset from a single register (such as automatic variables declared in the stack frame and referenced off of the EBP register), you can push the address of the variable by pushing the base register and adding the offset of that variable to the value left on the stack, thusly:

push( ebp ); // anAutoVar is found at EPB+@offset(anAutoVar)

add( @offset( anAutoVar ), (type dword [esp]));

call someLibraryRoutine;

If the address you want to pass in a reference parameter is a complex address, you’ll have to use the LEA instruction to compute that address and push it onto the stack. This, unfortunately, requires a free 32-bit register. If no 32-bit registers are free, you can use code like the following to achieve this:

sub( 4, esp ); // Reserve space for parameter on stack

push( eax ); // Preserve EAX

lea( eax, [ebp+@offset(autoVar)][ecx*4+3] );

mov( eax, [esp+4] ); // Store in parameter location

pop( eax ); // Restore EAX

call someLibraryRoutine;

Of course, it’s much nicer to use the HLA high-level syntax for calls like this as the HLA compiler will automatically handle all the messy code generation details for you.

Passing QWord Parameters on the Stack

Because qword (64-bit) objects are a multiple of 32 bits in size, manually passing qword objects on the stack is very easy. All you need do is push two dword values. Because the stack grows downward in memory and the x86 is a little endian machine, you must push the H.O. dword first and the L.O. dword second.

If the qword value is held in a register pair, then push the register containing the H.O. dword first and the L.O. dword second. For example, if EDX:EAX contains the 64-bit value, then you’d push the qword as follows:

push( edx ); // Push H.O. dword

push( eax ); // Push L.O. dword

call someLibraryRoutine;

If the qword value is held in a qword variable, then you must first push the H.O. dword of that variable followed by the L.O. dword, e.g.,

push( (type dword qwordVar[4])); // Push H.O. dword first

push( (type dword qwordVar)); // Push L.O. dword second

call someLibraryRoutine;

If the qword value you wish to pass is a constant, then you’ve got to compute the L.O. and H.O. dword values for that constant and push those. When using HLA, you can use the compile-time computational capabilities of HLA to do this for you, e.g.,

pushd( ((some64bitConst) >> 32);

pushd( ((some64bitConst) & $FFFF_FFFF );

call someLibraryRoutine;

If this is something you do frequently, you might want to create a macro to break up the 64-bit value and push it for you.

Of course, you can always use the HLA high-level syntax to pass a 64-bit object to a standard library routine. HLA automatically generates the appropriate code to pass the qword object as a parameter on the stack.

Passing TByte Parameters on the Stack

For efficiency reasons, standard library routines always pass all parameters as a multiple of four bytes. When passing a tbyte-sized parameter on the stack by value, the actual parameter value consumes the L.O. ten bytes of the three double words passed on the stack. The function ignores the H.O. word of the value passed for this parameter, though by convention (to make debugging a little easier) you should try to pass zeros in the H.O. word if it is not inconvenient to do so.

The following code demonstrates how to pass a ten-byte object to a standard library routine:

pushw( 0 ); // Dummy H.O. word of zero

push( (type word tbyteVar[8])); // Push H.O. byte of tbyte object

push( (type dword tbyteVar[4])); // Push bytes 4-7 of tbyte object

push( (type dword tbyteVar[0])); // Push L.O. dword of tbyte object

call someLibraryRoutine;

If your tbyte object is not at the very end of allocated memory, you could probably combine the first two instructions in this sequence to produce the following (slightly more efficient) code:

push( (type dword tbyteVar[8])); // Pushes two extra bytes.

This pushes the two bytes beyond tbyteVar onto the stack, but presumably the function will ignore all bytes beyond the tenth byte passed on the stack, so the actual values in those H.O. two bytes are irrelevant. Note the earlier discussion (in the section on pushing byte parameters) about the rare possibility of a memory access error when using this trick.

Of course, you can always use the HLA high-level syntax to pass an 80-bit object to a standard library routine. HLA automatically generates the appropriate code to pass the tbyte object as a parameter on the stack.

Passing LWord Parameters on the Stack

Because lword (128-bit) objects are a multiple of 32 bits in size, manually passing lword objects on the stack is very easy. All you need do is push four dword values. Because the stack grows downward in memory and the x86 is a little endian machine, you must push the H.O. dword first and the L.O. dword last.

If the lword value is held in an lword variable, then you must first push the H.O. dword of that variable followed by the lower-order dwords, down to the L.O. dword, e.g.,

push( (type dword qwordVar[12])); // Push H.O. dword first

push( (type dword qwordVar[8])); // Push bytes 8-11 second

push( (type dword qwordVar[4])); // Push bytes 4-7 third

push( (type dword qwordVar)); // Push L.O. dword last

call someLibraryRoutine;

If the lword value you wish to pass is a constant, then you’ve got to compute the four dword values for that constant and push those. When using HLA, you can use the compile-time computational capabilities of HLA to do this for you, e.g.,

pushd( ((some128bitConst) >> 96);

pushd( ((some128bitConst) >> 64 & $FFFF_FFFF );

pushd( ((some128bitConst) >> 32 & $FFFF_FFFF );

pushd( ((some128bitConst) & $FFFF_FFFF );

call someLibraryRoutine;

If this is something you do frequently, you might want to create a macro to break up the 128-bit value and push it for you.

Of course, you can always use the HLA high-level syntax to pass a 128-bit object to a standard library routine. HLA automatically generates the appropriate code to pass the lword object as a parameter on the stack.

Command-Line Arguments (args.hhf)

The HLA args module provides access to, and support for, Windows Command Line Interpreter or Linux/*nix shell command line parameters.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

A Note About Thread Safety: The args module maintains a couple of static global variables that maintain the command-line values. Currently, these values apply to all threads in a process. You should take care when changing these values in threads. The command-line is a resource that must be shared amongst all threads in an application. If you write multi-threaded applications, it is your responsibility to serialize access to the command-line functions.

The Args Module

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

#include( "args.hhf" )

#include( "stdlib.hhf" )

Retrieving the Command Line

The arg.cmdLn and arg.a_cmdLn functions retrieve the entire command-line as a string. This string typically consists of the list of command-line parameters, each parameter separated by a single space. Note that on some operating systems, the HLA standard library command-line functions might actually synthesize this string by concatenating the command-line arguments together, so you can not expect this string to be an exact representation of the command line that the user typed (that is, the user may have typed extra spaces or other delimiter characters that the OS’ shell discarded before passing the command line text to the program). Also, the command-line string will not contain I/O redirection or other process-related items (e.g., pipes) found on the command line.

procedure arg.cmdLn();

arg.cmdLn returns a pointer to a static string held inside the stdlib code. This function returns the string pointer in EAX. The caller must not modify any data in this string (use arg.a_cmdLn if you need a malleable string).

HLA high-level calling sequence examples:

arg.cmdLn();

stdout.put( "Command line: ", (type string eax), nl );

HLA low-level calling sequence examples:

call arg.cmdLn;

push( eax );

call stdout.puts;

procedure arg.a_cmdLn();

arg.a_cmdLn returns, in EAX, a string containing a copy of the command-line parameter text. This is a pointer to a string allocated on the heap. It is the caller’s responsibility to free this storage (via a call to str.free) when it is done using the string.

HLA high-level calling sequence examples:

arg.a_cmdLn();

stdout.put( "Command line: ", (type string eax), nl );

str.free( eax );

HLA low-level calling sequence examples:

call arg.cmdLn;

push( eax );

call stdout.puts;

push( eax );

call str.free;

Argument Count and Item

The functions in this category are the standard argument functions that most programs use: arg.c, arg.v, and arg.a_v. The arg.c function returns the number of command-line parameters and arg.v/arg.a_v return a pointer to a string that corresponds to an individual parameter.

procedure arg.c();

arg.c returns the number of command-line parameters in EAX. This count includes the program name on the command line.

HLA high-level calling sequence examples:

arg.c();

stdout.put( "Number of arguments: ", (type uns32 eax), nl );

HLA low-level calling sequence examples:

call arg.c;

mov( eax, argCount );

procedure arg.v( whichArg:dword );

arg.v returns a pointer to the string that corresponds to the specified command-line argument. Argument indexes are in the range 0..arg.c()-1. This function will raise an exception if you pass it an argument value outside this range. This function returns a pointer to a string whose storage is internal to the standard library. You must treat this data as read-only data and not modify this data.

HLA high-level calling sequence examples:

arg.c();

mov( eax, edx );

for( mov( 0, ecx ); ecx < edx; inc( ecx )) do

arg.v(ecx);

stdout.put( "arg[", (type uns32 ecx), "]=", (type string eax), nl );

endfor;

HLA low-level calling sequence examples:

pushd( 0 );

call arg.v;

mov( eax, firstArg );

procedure arg.a_v( whichArg:dword );

arg.a_v returns a pointer to the string that corresponds to the specified command-line argument. Argument indexes are in the range 0..arg.c()-1. This function will raise an exception if you pass it an argument value outside this range. This function returns a pointer to a string it allocates on the heap. The caller must free this storage (via a call to str.free) when it is done using the string.

HLA high-level calling sequence examples:

arg.c();

mov( eax, edx );

for( mov( 0, ecx ); ecx < edx; inc( ecx )) do

arg.a_v(ecx);

stdout.put( "arg[", (type uns32 ecx), "]=", (type string eax), nl );

str.free( eax );

endfor;

HLA low-level calling sequence examples:

pushd( 0 );

call arg.a_v;

mov( eax, firstArg );

str.free( firstArg );

Deleting Command Line Arguments

The functions in this category delete command-line arguments from the internal array or deallocate all the command-line arguments from the internal array. When an individual command-line parameter is deleted, the indexes of the following command-line arguments are reduced by one (that is, argument n+1 becomes argument n, argument n+2 becomes argument n+1, etc., up to the number of command-line arguments). Also note that deleting a command-line argument reduces the value that arg.c returns by one.

procedure arg.delete( index:uns32 );

arg.delete removes the specified command-line parameter from the internal argv array. The index parameter must be in the range 0..argc, where argc is the current value that arg.c() returns. If the index parameter is outside this range, this function will raise an ex.BoundsError exception. This function decrements the value that arg.c returns by one. Note that this function does not affect the value that arg.cmdLn returns.

HLA high-level calling sequence examples:

arg.c();

stdout.put( "Number of arguments: ", (type uns32 eax), nl );

arg.delete( 0 );

arg.c();

stdout.put

(

"Number of arguments after delete: ",

(type uns32 eax),

);

HLA low-level calling sequence examples:

pushd( 2 );

call arg.delete;

procedure arg.destroy();

arg.destroy deletes all of the command line parameters from internal storage and resets the command-line processor. The next function that requests a command line parameter value will force the run-time system to regenerate the command-line argument list.

HLA high-level calling sequence examples:

arg.destroy();

arg.c(); // Regenerates original command-line

mov( eax, originalArgc );

HLA low-level calling sequence examples:

call arg.destroy;

call arg.c;

mov( eax, originalArgc );

Argument Iterators

The iterators in this category process command-line arguments within a foreach loop.

iterator arg.args();

arg.args is an iterator (used in an HLA foreach loop) that returns successive command line parameters on each iteration of the foreach loop. This iterator returns a pointer to a newly allocated string in the EAX register. It is the caller’s responsibility (usually in the body of the foreach loop) to free the allocated storage with a call to str.free.

HLA high-level calling sequence examples:

foreach arg.args() do

stdout.put( "current Arg: ", (type string eax), nl );

str.free( eax );

endfor;

HLA low-level calling sequence examples:

(You really should only use the high-level calling sequence

for a foreach loop that calls an iterator.)

iterator arg.globalOptions( options:cset );

arg.globalOptions is an iterator (i.e., you use it in a FOREACH loop) that yields a sequence of command line parameter options. A command line parameter option is a command line parameter that begins with a ’-’ or ’/’ character. arg.globalOptions only returns those command line parameters whose first character is a member of the "options" character set.

A typical command line might be something like the following:

c:> pgmName -o2 -warn filename1 -c filename2 -d filename3 -x

The command line options in this example are "-o2", "-warn", "-c", "-d", and "-x". The arg.globalOptions iterator only considers those command line parameters that begin with "-" and whose first character is a member of the options parameter. Assuming options contains at least {’c’, ’d’, ’o’, ’w’, ’x’} then the arg.globalOptions iterator will return the strings "o2", "warn", "c", "d", and "x", in that order (that is, in the order they appear on the command line). If the first character of a command line option is not in the options character set, then arg.globalOptions does not return that particular command line parameter.

Note that arg.globalOptions does not remove the command line parameters from the command line string or from the arg.v array. If you want to remove them, you must explicitly do so using the arg.delete function. Note, however, that you must not delete command line arguments while scanning through the arguments in a FOREACH loop using the arg.globalOptions iterator.

Note that this iterator allocates storage for each string it returns on the heap. It is the caller’s responsibility to free the storage when the caller is done using the string.

HLA high-level calling sequence examples:

foreach arg.globalOptions( {‘a’, ‘b’, ‘c’ } ) do

stdout.put( "current option: ", (type string eax), nl );

str.free( eax );

endfor;

HLA low-level calling sequence examples:

(You really should only use the high-level calling

sequence for a foreach loop that calls an iterator.)

iterator arg.localOptions( options:cset );

arg.localOption is an iterator that yields the sequence of command line options begining at parameter "index". This iterator only yields strings as long as successive parameters begin with a "-". It fails upon encountering a command line parameter that is not an option (that is, begins with "-"). Note that this iterator only yields those command line options whose first character beyond the "-" character is a member of the options character set.

Typically, you would use the arg.localOption iterator inside a FOREACH loop to obtain the command line parameters for a specific filename on the command line. That is, some programs process multiple files and let you associate command line parameters with a single filename. Consider the following simple example:

c:> pgm -o2 -c file1 -o5 file2 -c file3

In this example, the "pgm" program (presumably) associates "-o2" and "-c" with file1, "-o5" with file2, and "-c" with file3.

Were you to call arg.localOption as follows:

foreach arg.localOption( 1, {’o’, ’c’} ) do ... endfor;

then the arg.localOption iterator would return two strings: the first would be "o2" and the second would be "c". Within that iterator your code should save these options and count the number of command line parameters processed so it will know the index of the associated filename command line parameter once it is done processing the options. Typically, you would bury this FOREACH loop (with some minor modifications) inside some other loop that processes each filename (or other command line parameter preceded by command line options).

Note that this iterator allocates storage for each string it returns on the heap. It is the caller’s responsibility to free the storage when the caller is done using the string.

See the CmdLnDemo.hla file in the Examples directory of the HLA distribution for an example of each of these routines.

HLA high-level calling sequence examples:

foreach arg.localOptions( 4, {‘a’, ‘b’, ‘c’ } ) do

stdout.put( "current option: ", (type string eax), nl );

str.free( eax );

endfor;

HLA low-level calling sequence examples:

(You really should only use the high-level calling

sequence for a foreach loop that calls an iterator.)

Arrays Module (arrays.hhf)

The HLA Arrays module provides a set of datatypes, macros, and procedures that simplify array access in assembly language (especially multidimensional array access). In addition to supporting standard HLA arrays with static size declarations, the HLA arrays module also supports dynamic arrays that let you specify the array size at run-time.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

The Arrays Module

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

#include( "arrays.hhf" )

#include( "stdlib.hhf" )

Array Data Types

The array namespace defines the following useful data types:

#macro array.dArray( type, dimensions );

The first feature in the array package to consider is the support for dynamic arrays. HLA provides a macro/data type that lets you tell HLA that you want to specify the array size under program control. This macro/data type is array.dArray (dArray stands for dynamic array). You use this macro invocation in place of a standard data type identifier in an HLA variable declaration.

The first macro parameter is the desired data type; this would typically be an HLA primitive data type like int32 or char, although any data type identifier is legal.

The second parameter is the number of dimensions for this array data type Generally this value is two or greater (since creating dynamic single dimensional arrays using only malloc is trivial). Because of the way array indicies are computed by HLA, it is not possible to specify the number of dimensions dynamically.

Note: since array.dArray is not a data type identifier (it’s a macro), you cannot directly create a dynamic array of dynamic arrays. I.e., the following is not legal:

static

DAofDAs: array.dArray( array.dArray( uns32, 2), 2 );

However, you can achieve exactly the same thing by using the following code:

type

DAs: array.dArray( uns32, 2 );

static

DAofDAs: array.dArray( DAs, 2 );

The TYPE declaration creates a type identifier that is a dynamic array. The STATIC variable declaration uses this type identifier in the array.dArray invocation to create a dynamic array of dynamic arrays.

Array Allocation and Deallocation

#macro array.daAlloc( dynamicArrayName, <<list of dimension bounds>> );

The array.dArray macro allocates storage for a dynamic array variable. It does not, however, allocate storage for the dynamic array itself; that happens at run-time. You must use the array.daAlloc macro to actually allocate storage for your array while the program is running. The first parameter must be the name of the dynamic array variable you’ve declared via the array.dArray macro. The remaining parameters are the number of elements for each dimension of the array. This list of dimension bounds must contain the same number of values as specified by the second parameter in the array.dArray declaration. The dimension list can be constants or memory locations (note, specifically, that registers are not currently allowed here; this may be fixed in a future version).

The following code demonstrates how to declare a dynamic array and allocate storage for it at run-time:

program main;

static

i:uns32;

j:uns32;

k:uns32;

MyArray: array.dArray( uns32, 3 );

begin main;

stdout.put( "Enter size of first dimension: " );

stdin.get( i );

stdout.put( "Enter size of second dimension: " );

stdin.get( j );

stdout.put( "Enter size of third dimension: " );

stdin.get( k );

// Allocate storage for the array:

array.daAlloc( MyArray, i, j, k );

<< Code that manipulates the 3-D dynamic array >>

end main;

#macro array.daFree( dynamicArrayName );

Use the array.daFree macro to free up storage you’ve allocated via the array.daAlloc call. This returns the array data storage to the system so it can be reused later. Warning: do not continue to access the array’s data after calling array.daFree. The system may be using the storage for other purposes after you release the storage back to the system with array.daFree.

Note: You should only call array.daFree for arrays you’ve allocated via array.daAlloc.

Example:

// Allocate storage for the array:

array.daAlloc( MyArray, i, j, k );

<< Code that manipulates the 3-D dynamic array >>

array.daFree( MyArray );

Array Predicates

#macro array.IsItVar( objectName )

This is a macro that evaluates to a compile-time expression yielding true if the object is a variable identifier. Variable identifiers are those IDs you declare in a VAR, STATIC, READONLY, or STORAGE declaration section, or IDs you declare as parameters to a procedure. This macro returns false for all other parameters.

#macro array.IsItDynamic( arrayName )

This is a macro that expands to a compile-time expression yielding true or false depending upon whether the parameter was declared with the array.dArray data type. If so, this function returns true; else it returns false. Note that a return value of false does not necessarily indicate that the specified parameter is a static array. Anything except a dynamic array object returns false. For example, if you pass the name of a scalar variable, an undefined variable, or something that is not a variable, this macro evaluates false. Note that you can use the HLA @type function to test to see if an object is a static array; however, @type will not return hla.ptArray for dynamic array objects since array.dArray objects are actually records. Hence the array.IsItDynamic function to handle this chore.

Array Element Access

#macro array.index( reg32, arrayName, <<list of indicies>> );

This macro computes a row-major order index into a multidimensional array. The array can be a static or dynamic array. The list of indicies is a comma separate list of constants, 32-bit memory locations, or 32-bit registers. You should not, however, specify the register appearing as the first parameter in the list of indicies.

If the VAL constant array.BoundsChk is true, this macro will emit code that checks the bounds of the array indicies to ensure that they are valid. The code will raise an ex.ArrayBounds exception if any index is out of bounds. You may disable the code generation for the bounds checking by setting the array.BoundsChk VAL object to false using a statement like the following:

?array.BoundsChk := false;

You can turn the bounds checking on and off in segments of your code by using statements like the above that set array.BoundsChk to true or false.

This macro leaves pointer into the array sitting in the specified 32-bit register.

Example:

static

arrayS: uns32[ 2,3,4 ];

arrayD: array.dArray( uns32, 3 );

// copy arrayS[i, j, k] to arrayD[m,n,p]:

array.index( ebx, arrayS, i, j, k );

mov( [ ebx ], eax ); // EAX := arrayS[I,j,k];

array.index( ebx, arrayD, m, n, p );

mov( eax, [ebx] ); // EAX := arrayD[m,n,p];

iterator array.element( arrayName );

This iterator returns each successive element of the specified array. It returns the elements in row major order (that is, the last dimension increments the fastest and the first dimension increments the slowest when returning elements of a multidimensional array). This iterator returns byte objects in the AL register; it returns word objects in the AX register; it returns dword objects in the EAX register; it returns 64-bit (non-real) objects in the EDX:EAX register pair. This routine returns all floating point (real) objects on the top of the FPU stack.

Note that array.element is actually a macro, not an iterator. The macro, however, simply provides overloading to call one of seven different iterators depending on the size and type of the operand. However, this macro implementation is transparent to you. You would use this macro exactly like any other iterator.

Note that array.element works with both statically declared arrays and dynamic arrays you’ve declared with array.dArray and you’ve allocated via array.daAlloc.

Examples:

static

arrayS: uns32[ 2,3,4 ];

arrayD: array.dArray( uns32, 3 );

foreach array.element( arrayS ) do

stdout.put( "Current arrayS element = ", eax, nl );

endfor;

foreach array.element( arrayD ) do

stdout.put( "Current arrayD element = ", eax, nl );

endfor;

Array Operations

#macro array.cpy( srcArray, destArray );

This macro copies a source array to a destination array. Both arrays must be the same size and shape (shape means that they have the same number of dimensions and the bounds on all the dimensions correspond between the source and destination arrays). Both static and dynamic array variables are acceptable for either parameter.

Example:

static

arrayS: uns32[ 2,3,4 ];

arrayD: array.dArray( uns32, 3 );

// note: for the following to be legal at run-time,

// the arrayD dynamic array must have storage allocated

// for it with a statement like

// "array.daAlloc( arrayD, 2, 3, 4 );"

array.cpy( arrayS, arrayD );

#macro array.reduce( srcArray, destArray );

#keyword array.beforeRow;

#keyword array.reduction;

#keyword array.afterRow;

#terminator array.endreduce;

The array.reduce macro emits code to do a "row-reduction" on an array. A row reduction is a function that compresses all the rows (that is, the elements selected by running through all the legal values of the last dimension) to a single element. Effectively, this macro reduces an array of arity n to an array of arity n-1 by eliminating the last dimension.

Reduction is not accomplished by simply throwing away the data in the last dimension (although it’s possible to do this). Instead, you’ve got to supply some code that the array.reduce macro will use to compress each row in the array.

A very common reduction function, for example, is addition. Reduction by addition produces a new array that contains the sums of the rows in the previous array. For example, consider the following matrix:

1 2 3 4

6 5 4 1

5 9 8 0

This is a 3x4 array. Reducing it produces a one dimensional array with three elements containing the value 10, 16, 22 (the sums of each of the above rows).

The best way to understand how the array.reduce macro works is to manual implement addition reduction manually. To reduce the 3x4 array above to a single array with three elements, you could use the following code:

// (a) Any initialization required before loops

// (this example requires no such initialization.)

for( mov( 0, i ); i < 3; inc( i )) do

mov( 0, eax ); // (b) Initialize sum for each row.

for( mov( 0, j); j < 4; inc( j )) do

// (c) Sum up each element in this row into EAX:

index( ebx, array3x4, i, j );

add( [ebx], eax );

endfor;

// (d) At the end of each row, store the sum away

// into the destination array.

mov( i, ebx );

mov( eax, array3[ ebx*4 ]);

endfor;

The array.reduce macro is an example of an HLA context-free macro construct. This means that the call to array.reduce consists of multiple parts, just like the REPEAT..UNTIL and SWITCH..CASE..ENDSWITCH control structures. Specifically, an array.reduce invocation consists of the following sequence of macro invocations:

array.reduce( srcArray, destArray );

<< Initialization statements needed before

loops,(a) in the code above >>

array.beforeRow;

<< Initialization before each row, (b) in the

code above. Note that edi contains the row

number times the size of an element and esi contains

an index into the array to the current element. >>

array.reduction;

<< Code that compresses the data for each

row, to be executed for each element

in the row. Corresponds to (c) in the

the code above. Note that ecx contains

the index into the current row. >>

array.afterRow;

<< Code to process the compressed data at

the end of each row. Corresponds to (d)

in the code above. >>

array.endreduce;

A conversion of the previous code to use the array.reduce macro set looks like the following:

array.reduce( array3x4, array3 )

// No pre-reduction initialization...

array.beforeRow

mov( 0, eax ); // Initialize the sum for each row.

array.reduction

add( array3x4[esi], eax );

array.afterRow

mov( i, edx );

mov( eax, array3[ edx*4 ]);

array.endreduce;

Note that the array.reduce macro set makes extensive use of the 80x86 register set. The EAX and EDX registers are the only free registers you can use (without restoring) within the macro. Of course, array.reduce will preserve all the regsiters is uses, but within the macro itself it assumes it can use all registers except EAX and EDX for its own purposes.

#macro array.transpose( srcArray, destArray, optionalDimension);

The array.transpose macro copies the source array to the destination array transposing the elements of the last dimension with the dimension specified as the last parameter. For the purposes of this macro, the array dimensions of an n-dimensional array are numbered as follows:

SomeArray[ n-1, n-2, ..., 3, 2, 1, 0 ];

Therefore, array.transpose will transpose dimension zero with some other dimension (1..n-1) in the source array when copying the data to the destination array. By default (if you don’t supply the optional, third parameter), array.transpose will transpose dimensions zero and one when copying the source array to the destination array.

The source and destination arrays must have at least two dimensions. They can be static or dynamic arrays. Note that array.transpose emits special, efficient, code when transposing dimensions zero and one.

The source and destination arrays must have compatible shapes. The shapes are compatible if the arrays have the same number of dimensions and all the dimensions have the same bounds except dimension zero and the transpose dimension (which must be swapped). For example, the following two arrays are transpose-compatible when transposing dimensions zero and two:

static

s: uns32[ 2, 2, 3];

d: uns32[ 3, 2, 2];

Generally, one uses array.transpose to transpose a two-dimensional matrix. However, the transposition operation is defined for any number of dimensions. To understand how array.transpose works, it is instructive to look at the code you’d write to manually transpose the data in an array. Consider the transposition of the data in the s and d arrays above:

for( mov(0, i); i<2; inc(i)) do

for( mov(0,j); j<2; inc(j)) do

for( mov(0,k); k<3; inc(k)) do

index( edx, s, i, j, k );

mov( [edx], eax );

index( edx, d, k, j, i );

mov( eax, [edx] );

endfor;

Note that when storing away the value into the destination array, the i and k indicies were swapped. The following example demonstrates the use of array.transpose:

static

s: uns32[2,3] := [1,2,3,4,5,6];

d: uns32[3,2];

array.transpose( s, d );

note: The code above copies s, as

1 2 3

4 5 6

to d, as

1 4

2 5

3 6

Lookup Tables

The array.lookupTable macro lets you easily construct a standard lookup table. This macro invocation must appear within a STATIC or a READONLY declaration section in your program. A lookup table declaration takes the following form:

readonly

tableName:

array.lookupTable

(

element_data_type,

default_table_value,

value: list_of_indexes,

value: list_of_indexes

);

where:

element_data_type is the data type for each element of the array, for example, byte.

default_table_value is a value to use for "holes" in the table for which you do not supply an explicit index/value.

value is some value that you want to use to initialize a sequence of one or more table entries with.

list_of_indexes is a list of values that specify indexes into the lookup table. Each entry in a specific list is separated from the other entries with a space (not commas!). Note that each index value you specify must be unique across all lists of indexes in this table (that is, you cannot put two values into the array element specified by a single index). The array.lookupTable macro will report an error if you specify a non-unique index value in one of the lists.

Here is a concrete example:

static

tableName:

array.lookupTable

(

int32,

-1,

0: 1 2 3 4,

1: 5 6 7 8,

2: 9 10 11 12,

3: 13 14 15,

4: 20 22 24,

5: 16 21 25,

6: 23 19 18

);

This declaration creates a table with 25 dword entries, that will hold the values 1..25. The table will be initialized as follows:

tableName:int32[25] :=

[

0, 0, 0, 0, // Elements 0..3

1, 1, 1, 1, // Elements 4..7

2, 2, 2, 2, // Elements 8..11

3, 3, 3, // Elements 12..14

5, // Element 15

-1, // Element 16 (no index 17 specified above)

6, 6, // Elements 17 & 18

4, // Element 19

5, // Element 20

4, // Element 21

6, // Element 22

4, // Element 23

5 // Element 24

];

The number of elements appearing in the lookup table will be the difference between the largest index value you supply in all the lists (25 in this example) and the smallest value (1 in this example) plus one. This particular lookup table has 25 entries because (25-1+1) = 25.

Note that each line in the example above specifies the value to store into each of the table entries in the list that immediately follows. This is probably backwards to what your intution would suggest. But the nice thing about this arrangement is that it lets you specify a single value to be placed into several different array indices. If there are any gaps in the array indexes you specify (as the value 17 is missing above), then the array.lookupTable macro will fill in those entries with the default value specified as the second parameter.

In order to access this lookup table at run-time, you must know the minimum index into the array so you can subtract this from the calculated index you use to access the table. The array.lookupTable macro generates four constants for you to help you do this (and other things):

tableName_maxValue

tableName_minValue

tableName_maxIndex

tablename_maxIndex

The tableName_minValue and tableName_maxValue constants specify the minimum and maximum index values for the table. In the current example, these constants would be 1 and 25, respectively. The tableName_minIndex and tableName_maxIndex values are the product of the array element’s size with the _minValue and _maxValue constants. In the table above, the element size is four, so tableName_minIndex will be four and tableName_maxIndex will be 100. Whenever you access an element of the tableName array (in this example), you’ll want to subtract the tableName_minIndex value from your computed index in order to adjust for non-zero starting indexes, e.g.,

mov( someIndex, ebx );

mov( tableName[ebx*4 - tableName_minIndex], eax );

Bit Manipulation (bits.hhf)

The HLA BITS module contains several procedures useful for bit manpulation. Currently, this includes routines like counting bits, reversing bits, and merging bit streams.

A Note About Thread Safety: The routines in this module are all thread safe.

Note about stack diagrams: this documentation includes stack diagrams for those functions that pass parameters on the stack. To conserve space, this documentation does not include a stack diagram for any function that does not pass data on the stack (that is, only a return address appears on the stack).

Bit Module

To call functions in the Bits module, you must include one of the following statements in your HLA application:

#include( "bits.hhf" )

#include( "stdlib.hhf" )

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

Bit Counting Function

bits.cnt( b:dword in eax ); @returns( "EAX" );

This procedure returns the number of one bits present in the "b" parameter (passed in the EAX register). It returns the count in the EAX register. To count the number of zero bits in the parameter value, invert the value of the parameter before passing it to bits.cnt . If you want to count the number of bits in an 8-bit or 16-bit operand, simply zero extend it to 32 bits prior to calling this function. Here are a couple of examples:

If you want to compute the number of bits in an eight-bit operand it’s probably faster to write a simple loop that rotates all the bits in the source operand and adds the carry into the accumulating sum. Of course, if performance isn’t an issue, you can zero extend the byte to 32 bits and call the bits.cnt procedure.

Note: to count the number of zero bits in an object, first invert than object and then call bits.cnt .

HLA high-level calling sequence examples:

bits.cnt( mem32 );

mov( eax, count );

mov( bits.cnt( ebx ), count ); // Note: count is in EAX

// Count the number of bits in 8-bit and 16-bit operands:

bits.cnt( movzx( al, eax ) );

mov( eax, count8 );

mov( bits.cnt( movzx( ax, eax )), count16 ); // Count is left in EAX.

HLA low-level calling sequence examples:

mov( mem32, eax );

call bits.cnt;

mov( eax, count );

mov( ebx, eax );

call bits.cnt;

mov( eax, count );

movzx( al, eax );

call bits.cnt;

mov( eax, count8 );

movzx( ax, eax );

call bits.cnt;

mov( eax, count16 );

Bit Reversal Functions

The functions in this category swap the bits in their input operand. That is, they exchange the H.O. and L.O. bits, the next-to-high-order bit with bit #1, and so on.

bits.reverse32( b:dword in eax ); @returns( "eax" );

This function reverses the bits passed to it in EAX and returns the swapped value in EAX. This function swaps bit 31 and 0, bits 30 and 1, bits 29 and 2, bits 28 and 3, and so on. See the diagram for bits.reverse8 and generalize that diagram to 32 bits for a pictorial example.

HLA high-level calling sequence examples:

bits.reverse32( mem32 );

mov( eax, reversed32 );

mov( bits.reverse32( ebx ), ebxReversed ); // Note: result is in EAX

HLA low-level calling sequence examples:

mov( mem32, eax );

call bits.reverse32;

mov( eax, reversed32 );

mov( ebx, eax );

call bits.reverse32;

mov( eax, ebxReversed );

bits.reverse16( b:word in ax ); @returns( "eax" );

This function reverses the bits passed to it in AX and returns the swapped value in AX. This function swaps bit 15 and 0, bits 14 and 1, bits 13 and 2, bits 12 and 3, and so on. Note that this function does not zero or sign-extend the result into EAX. Although this function currently preserves the H.O. word of EAX, it’s safer to assume that the H.O. word of EAX contains an undefined value upon return. See the diagram for bits.reverse8 and generalize that diagram to 16 bits for a pictorial example.

HLA high-level calling sequence examples:

bits.reverse16( mem16 );

mov( ax, reversed16 );

mov( bits.reverse16( bx ), bxReversed ); // Note: result is in AX

HLA low-level calling sequence examples:

mov( mem16, ax );

call bits.reverse16;

mov( ax, reversed16 );

mov( bx, ax );

call bits.reverse16;

mov( ax, bxReversed );

bits.reverse8( b:byte in al ); @returns( "eax" );

This function reverses the bits passed to it in AL and returns the swapped value in AL. This function swaps bit 7 and 0, bits 6 and 1, bits 5 and 2, and bits 4 and 3 (see the diagram for bits.reverse8). Note that this function does not zero or sign-extend the result into EAX. Although this function currently preserves the H.O. three bytes of EAX, it’s safer to assume that the H.O. three bytes of EAX contain an undefined value upon return. See the diagram for bits.reverse8 and generalize that diagram to 16 bits for a pictorial example.

HLA high-level calling sequence examples:

bits.reverse8( mem8 );

mov( al, reversed8 );

mov( bits.reverse8( bl ), blReversed ); // Note: result is in AL

HLA low-level calling sequence examples:

mov( mem8, al );

call bits.reverse8;

mov( al, reversed8 );

mov( bl, al );

call bits.reverse8;

mov( al, blReversed );

Bit Merging Functions

The bit merging operands take two small values and produce a single larger value by interleaving the bits from the source operands in the destination operand. One operand’s bits are spread out into the destination operand’s even bit positions, the other operand’s bits are distributed in the odd bit positions (see the following diagram).

bits.merge32( even:dword in eax; odd:dword in edx ); @returns( "EDX:EAX" );

This function merges two dword values to produce a single qword value. The bits in the even operand are placed in the even bit positions of the qword result, the bits in the odd operand are merged into the odd bit positions. This function returns the qword result in edx:eax (edx contains the H.O. dword).

Note: because this function passes the parameters in EAX and EDX, you may get an undefined result if you specify EDX as the even parameter or EAX as the odd parameter.

HLA high-level calling sequence examples:

bits.merge32( mem32Even, mem32Odd );

mov( edx, (type dword mergedQword[4]) );

mov( eax, (type dword mergedQword[0]) );

bits.merge32( ecx, ebx );

mov( edx, (type dword mergedQword[4]) );

mov( eax, (type dword mergedQword[0]) );

HLA low-level calling sequence examples:

mov( mem32Even, eax );

mov( mem32Odd, edx );

call bits.merge32;

mov( edx, (type dword mergedQword[4]) );

mov( eax, (type dword mergedQword[0]) );

mov( ecx, eax );

mov( ebx, edx );

call bits.merge32;

mov( edx, (type dword mergedQword[4]) );

mov( eax, (type dword mergedQword[0]) );

bits.merge16( even:word; odd:word ); @returns( "EAX" );

This function merges two word values to produce a single dword value. The bits in the even operand are placed in the even bit positions of the dword result, the bits in the odd operand are merged into the odd bit positions. This function returns the dword result in EAX.

HLA high-level calling sequence examples:

bits.merge16( mem16Even, mem16Odd );

mov( eax, mergedDword );

bits.merge16( cx, bx );

mov( eax, mergedDword );

HLA low-level calling sequence examples:

// If mem16Even and mem16Odd are not at the end

// of some page in memory, you can safely do the following

push( (type dword mem16Even) );

push( (type dword mem16Odd) );

call bits.merge16;

mov( eax, mergedDword );

// To be absolutely safe, do something like the following

// (EAX is free to use because the result comes back in EAX):

movzx( mem16Even, eax );

push( eax );

movzx( mem16Odd, eax );

push( eax );

call bits.merge16;

mov( eax, mergedDword );

push( ecx );

push( edx );

call bits.merge16;

mov( eax, mergedDword );

bits.merge8( even:byte in al; odd:byte in ah ); @returns( "AX" );

This function merges two byte values to produce a single word value. The bits in the even operand are placed in the even bit positions of the word result, the bits in the odd operand are merged into the odd bit positions. This function returns the word result in AX.

Note: because this function passes the parameters in AL and AH, you may get an undefined result if you specify AH as the even parameter or AL as the odd parameter.

HLA high-level calling sequence examples:

bits.merge8( mem8Even, mem8Odd );

mov( ax, mergedWord );

bits.merge8( cl, bh );

mov( eax, mergedWord );

HLA low-level calling sequence examples:

mov( mem8Even, al );

mov( mem8Odd, ah );

call bits.merge8;

mov( ax, mergedWord );

mov( cl, al );

mov( bh, ah );

call bits.merge8;

mov( ax, mergedWord );

Bit Extraction Functions

These functions extract nibbles from their source operands, zero extend those nibbles to bytes, and return the values in an operand twice the size of the original operand (e.g., AL->AX, AX->EAX, and EAX->EDX:EAX). For example, the bits.nibbles8 function does the following:

bits.nibbles32( d:dword in eax ); @returns( "EDX:EAX" );

This function extracts the 8 nibbles from EAX, zero extends each of them to 8 bits, and then places them in the following locations

EAX[0:3] -> EAX[0:7]

EAX[4:7] -> EAX[8:15]

EAX[8:11] -> EAX[16:23]

EAX[12:15] -> EAX[24:31]

EAX[16:19] -> EDX[0:7]

EAX[20:23] -> EDX[8:15]

EAX[24:27] -> EDX[16:23]

EAX[28:31] -> EDX[24:31]

HLA high-level calling sequence examples:

bits.nibbles32( mem32 );

mov( eax, LONibbles );

mov( edx, HONibbles );

bits.nibbles32( ecx );

mov( eax, LONibbles );

mov( edx, HONibbles );

HLA low-level calling sequence examples:

mov( mem32, eax );

call bits.nibbles32;

mov( ax, mergedWord );

mov( ecx, eax );

call bits.nibbles32;

mov( eax, LONibbles );

mov( edx, HONibbles );

bits.nibbles16( w:word in ax ); @returns( "EAX" );

This function extracts the 4 nibbles from AX, zero extends each of them to 8 bits, and then places them in the following locations

AX[0:3] -> EAX[0:7]

AX[4:7] -> EAX[8:15]

AX[8:11] -> EAX[16:23]

AX[12:15] -> EAX[24:31]

HLA high-level calling sequence examples:

bits.nibbles16( mem16 );

mov( eax, Nibbles );

bits.nibbles16( cx );

mov( eax, Nibbles );

HLA low-level calling sequence examples:

mov( mem16, ax );

call bits.nibbles16;

mov( ax, mergedWord );

mov( cx, ax );

call bits.nibbles16;

mov( eax, LONibbles );

bits.nibbles8( b:byte in al ); @returns( "AX" );

This function extracts the 2 nibbles from AL, zero extends each of them to 8 bits, and then places them in the following locations

AL[0:3] -> AL[0:7]

AL[4:7] -> AH[0:7]

HLA high-level calling sequence examples:

bits.nibbles8( mem8 );

mov( ax, TwoNibbles );

bits.nibbles8( ch );

mov( ax, TwoNibbles );

HLA low-level calling sequence examples:

mov( mem8, al );

call bits.nibbles8;

mov( ax, TwoNibbles );

mov( ch, al );

call bits.nibbles8;

mov( ax, TwoNibbles );

procedure bits.extract( var d:dword );

@returns( "EAX" ); // Really a macro.

This function extracts the first set bit in d searching from bit #0 and returns the index of this bit in the EAX register; the function will also return the zero flag clear in this case. This function also clears that bit in the operand. If d contains zero, then this function returns the zero flag set and EAX will contain -1.

Note that HLA actually implements this function as a macro, not a procedure. This means that you can pass any double word operand as a parameter (i.e., a memory or a register operand). However, the results are undefined if you pass EAX as the parameter (since this function returns the bit number in EAX). Note that the macro will report an error message if you try to pass EAX as the parameter.

Bit Distribution Functions

bits.distribute( source:dword; mask:dword; dest:dword );

@returns( "EAX" );

This function takes the L.O. n bits of source, where n is the number of "1" bits in mask , and inserts these bits into dest at the bit positions specified by the "1" bits in mask . This function does not change the bits in dest that correspond to the zeros in the mask value. This function does not affect the value of the actual dest parameter, instead, it returns the new value in the EAX register.

Example:

source = $FF00_AA55

mask = $F0FF_000F

dest = $1234_5678

The bits.distribute function grabs the L.O. 16 bits of source and inserts these bits at positions 0, 1, 2, 3, 16, 17, 18, 19, 20, 21, 22, 23, and 28, 29, 30, and 31 into the value $1234_5678 and returns the result in EAX. For this example, bits.distribute begins by grabbing the L.O. four bits of source and inserts them at bit positions 0..3 of $1234_5678 (since mask contains four set bits at positions 0..3). This yields the temporary result $1234_5675. Next, bits.distribute grabs bits 4..11 from source ($A5) and inserts these bits into bit positions 16..23 since mask contains eight consecutive bits between positions 16 and 23. The produces the temporary result $12A5_5675. Finally, bits.distribute grabs bits 12..15 from the source operand ($A) and inserts these into the result at bit positions 28..31 (since the mask value contains set bits at these positions). The final result this function returns in EAX is $A2A5_5675.

bits.coalese( source:dword; mask:dword );

@returns( "EAX" );

This function is the converse of bits.distribute . It extracts all the bits in source whose corresponding positions in mask contain a one. This function coalesces (right justifies) these bits in the L.O. bit positions of the result and returns the result in EAX.

Example:

source = $afff_ffce

mask = $aaaa_5555

bits.coalesce grabs bits 0, 2, 4, 6, 8, 10, 12, 14, 17, 19, 21, 23, 25, 27, 29, and 31 from source and packs these into the L.O. 16 bits of EAX (it also sets the H.O. bits of EAX to zero). The final result in EAX is $FFFA.

The Blobs Module (blobs.hhf)

This unit contains routines that read data from and write data to memory-based streams (blobs, or Binary Large OBjects). The blob functions can be broken down into five generic categories: general functions that initialize and allocate blobs, functions that convert between blobs and generic memory buffers, functions that do blob file I/O, accessor functions that provide access to the internal blob data structure, and blob I/O functions.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

A Note About the FPU: The Standard Library code makes occasional use of the FPU, particularly when converting between real and string formats and when computing certain mathematical functions. You should exercise caution when using MMX instructions in a program that makes use of the Standard Library. In particular, you should ensure that you are always in FPU mode (by executing an EMMS instruction) after you are finished using MMX instructions. Better yet, you should avoid the MMX instruction set altogether and use the improved SSE instruction set that accomplishes the same tasks (and doesn’t disturb the FPU).

A note about thread safety: Each blob object maintains its own critical section variable. Therefore, blobs are protected from multi-threaded access on a per-blob level. Because blobs create this critical section object whenever a blob is initialized or allocated, you must ensure that you free or destroy the blob when you are done using it (and before your program quits) in order to free up system resources.

Conversion Format Control

The blob output functions that convert numeric values to hexadecimal, unsigned decimal, and signed decimal output provide the ability to inject underscores between groups of three (decimal) or four (hexadecimal) digits to make it easier to read large numbers. You enable and disable underscore output using the conv.setUnderscores and conv.getUnderscores functions. Please refer to their documentation in the conv.rtf file for more details.

When reading numeric data from a blob, the blob functions use an internal delimiters character set to determine which characters may legally end a sequence of numeric digits. You can change the complexion of this character set using the conv.getDelimiters and conv.setDelimiters functions. Please refer to their documentation in the conv.rtf file for more details.

When converting numeric values to string form for output, the blob routines call the conversion functions found in the conv (conversions) module. For detailed information on the actual conversions, please consult the conv.rtf document.

Blob Synopsis

The best way to describe a blob (Binary Large Object) is by calling it a "memory-based file." You generally read and write data to a blob using a file I/O paradigm, that is, by using function calls similar to the HLA standard library's fileio functions. The advantage of blobs over files is that blobs are much faster than files; the disadvantage of blobs is that blob data is volatile (meaning that you lose all data written to a blob when the program quits or if there is a power outage). Another pair of blob disadvantages is that blobs' sizes are limited by the amount of available system RAM (files are limited by the amount of free disk space, which is usually much larger) and that you have to predeclare a blob's size before using it. By contrast, files can grow to any size up to the amount of free disk space you having to specify the maximum size prior to creating the file. Despite these limitations, blobs are quite useful because blob manipulation is much faster than file manipulation (often three orders of magnitude faster).

Blobs are very similar to strings. The main differences between strings and blobs are

Strings generally hold character data (ASCII text), blobs hold arbitrary character and binary data (hence the name "Binary Large OBject").
Strings generally represent a single coherent value (e.g., a single line of text), blobs may contain many records (e.g., multiple lines of text).
Strings are generally created and manipulated in their entirety; blobs are generally built up and accessed using a sequence of operations (similar to file I/O operations).
Blobs' data can be aligned on any address that is a power of two (and greater than or equal to 4); strings are always aligned on dword addresses. This makes blobs especially useful for manipulating data objects with certain SSE instructions.

Blob Internal Representation

The following is the internal representation of a blob object (these declarations are inside the blob namespace):

type

blobRec:

record := -20;

allocPtr :dword;

criticalSection :dword

rcursor :dword;

wcursor :dword;

maxlen :dword;

length :dword;

blobData :byte[16]; // Minimum is 16 bytes

endrecord;

t :pointer to blobRec; // blob.t outside blob namespace

blob_t :t; // blob.blob_t outside blob namespace

blob :t; // blob.blob outside blob namespace

Note that the fieldnames in blobRec are generally considered private to the blobRec record declaration and are intended for internal use (by the blobs package) only. Applications should only reference or modify these fields using the blob accessor functions (described a little later in this document).

The allocPtr field contains the address of the start of the memory block allocated for the blob. Blobs can be allocated to any address (that is a power of two and greater than or equal to 4). Because the stdlib's mem.alloc function only guarantees 8-byte alignment, certain calls that allocate storage for a blob might need to allocate extra storage in order to align the blob's data (the blobData field) at an appropriate address in memory. This might insert (an arbitrary amount of) padding bytes before the allocPtr field in the blob data structure. The blob data structure needs to save this allocation address (in allocPtr ) so that the application can free the storage consumed by the blob object. Much of the time, the allocPtr field will contain it's own address; for unaligned (the most common) blobs, or blobs aligned on 8-byte or less addresses, no extra padding is necessary. If the blob object is allocated in static memory rather than on the heap (or in memory that was not allocated by the blob library functions), the allocPtr field will contain NULL.

The criticalSection field contains the object that controls access to the blob’s critical section in multi-threaded applications. Note that this field is still present (though unused) in single-threaded applications. This is a private field and should never be accessed by code outside the blob library.

The rcursor (read cursor) field contains the offset into the blob's data where the next value will be read from the blob using one of the blob.get* functions or any of the other blob input functions that read data from the read cursor position.

The wcursor (write cursor) field contains the offset into the blob's data where the next value will be written to in the blob using one of the blob.put* functions or any of the other blob output functions that write data to the write cursor position in the blob.

The maxlen (maximum length) field contains the maximum size of the blob. If an application attempts to read or write data beyond this point in the blob, the library routines will generate an exception.

The length field is the current (dynamic) length of the blob. This field's value is always less than or equal to maxlen's value.

The blobData field is where the blob's data appears in memory. This is an array of bytes containing at least maxlen bytes (it may contain more, depending on the alignment of the blob allocation). This field always contains at least 16 bytes (hence the declared size of 16 in the blobRec record).

Declaring Blob Variables

HLA stdlib blob variables are pointers. When declaring blob objects, you should use the blob.blob , blob.blob_t , or blob.t data types. These three names are all synonyms, you can use whatever form you choose. Whenever this documentation refers to a "blob variable", it is actually talking about a pointer to a blob object, that is, a variable of type blob.blob , blob.blob_t , or blob.t . For example:

var

blobVar : blob.t;

blobVar2 : blob.blob_t;

blobVar3 : blob.blob;

Note that these declarations all reserve exactly four bytes for the blob variables ( blobVar1 , blobVar2 , and blobVar3 ). Blob variables always hold pointers to the actual blob data. Of course, like strings and other pointers, these declarations do not actually allocate storage for the blob object itself. You will have to call a function such as blob.alloc to allocate the actual storage for a blob object.

You can also use the blob.init function to initialize a block of memory you’ve allocated for use as a blob.

See the description of this function for more details.

Initializing and Allocating Blob Variables

The HLA Blobs module provides several functions that let you allocate storage for a blob on the heap or associate other storage with the blob. Because you must allocate storage for a blob before using it, these functions will generally be the first functions you call before using a blob.

blob.init( var b:var; numBytes:dword ); @returns( "eax" );

The blob.init routine initializes a block of memory so that it contains a blob object. This function returns a pointer to the blob object in EAX, which you should store into a blob.t variable. The b argument is the address of a block of bytes that you want to use as the blob object. The numBytes argument is the total size of the block of memory pointed at by the b parameter. Note that at least 20 bytes of the object pointed at by b will be used to hold the blob's metadata (internal data structure). That is, numBytes does not specify the maximum size of the blob; the maximum size will actually be slightly smaller than this value. This function will raise an exception if numBytes is too small (insufficient space to allocate the blob metadata and at least 16 bytes of blob data.). Warning: that this function sets the allocPtr field of the blobRec data structure to NULL. If you have allocated this storage on the heap, it is your responsibility to call mem.free with the original allocation address to return the storage to the heap. You must never call blob.free to free the blob storage that you've initialized with a blob.init call.

Important: this function creates a new critical section object and initializes the criticalSection field of the blob data object.

You must call blob.destroy when you are done with the blob to delete the critical section object and return its resources to the operating system.

blob.init16( var b:var; numBytes:dword ); @returns( "eax" );

Just like blob.init except that this function always returns an address that is aligned to a 16-byte boundary. Note that if the memory block pointed at by b isn't at an appropriate address, blob.init16 will use up to 15 bytes at the beginning of this block as padding bytes to guarantee that the address this function returns in eax is aligned to a 16-byte boundary. Therefore, you should ensure that the block of memory whose address you pass is at least 16 bytes larger than you need to ensure you have enough space after padding is removed from the total. The warnings above apply to blob.init16 as well as blob.init .

blob.alloc( size:dword); @returns( "eax" );

The blob.alloc routine allocates storage for a blob object that contains at least size bytes of blob data. It initializes the blob header ( blobRec ) data structure and returns a pointer to the blob in EAX (that you should store into a blob variable). This function will raise an exception if it cannot allocate the specified amount of storage on the heap for the blob object. Note that this function also allocates storage for the blob header and pads the size of the blob (typically to a multiple of 16 bytes) so this call allocates a little bit more storage than size bytes on the heap. Note that blobs created with the blob.alloc function are always aligned on a 16-byte boundary and they always initialize the blobRec allocPtr field with the address of the storage allocated by an (internal) mem.alloc call.

Important: this function creates a new critical section object and initializes the criticalSection field of the blob data object.

You must call blob.free when you are done with the blob to delete the critical section object and return its resources to the operating system.

blob.allocAligned( size:dword; alignment:dword); @returns( "eax" );

The blob.allocAligned routine also allocates storage for a blob object on the heap. The alignment argument is an integer in the range 0..16 specifying the alignment on a 2** alignment byte boundary. That is, the alignment value is interpreted as follows:

alignment	Blob data aligned to
0	16 bytes
1	16 bytes
2	16 bytes
3	16 bytes
4	16 bytes
5	32 bytes
6	64 bytes
7	128 bytes
8	256 bytes
9	512 bytes
10	1024 bytes
11	2048 bytes
12	4096 bytes
13	8192 bytes
14	16384 bytes
15	32768 bytes
16	65536 bytes

Note that the minimum alignment is always 16 bytes because this is the alignment that blob.alloc guarantees. Note that the blob.allocAligned function might have to add as many as 2*alignment+32 bytes to the size of the storage allocated on the heap in order to guarantee alignment on the desired address boundary. As for the blob.alloc call, this function initializes the internal allocPtr field with the address of the block of storage allocated on the heap.

Important: this function creates a new critical section object and initializes the criticalSection field of the blob data object.

You must call blob.free when you are done with the blob to delete the critical section object and return its resources to the operating system.

blob.realloc( theBlob:blob.t; size:dword ); @returns( "eax" );

The blob.realloc routine resizes an existing blob. The first argument, theBlob , is the address of the blob object to resize and the second argument is the new maximum size of the resultant blob. This function works by allocating a new blob of the specified size, copying the blob data from the original blob to the new blob, and then freeing the storage associated with the original blob if the allocPtr field contains a non-NULL value.

It will also destroy the critical section object held by the original blob.

Important: this function creates a new critical section object and initializes the criticalSection field of the blob data object.

You must call blob.free when you are done with the blob to delete the critical section object and return its resources to the operating system.

Note that there is no blob.reallocAligned function call, but you can easily write your own using the following code:

blob.allocAligned( newsize, desiredAlignment );

push( eax );

blob.cpy( originalBlob, eax );

blob.free( originalBlob );

pop( eax );

mov( eax, originalBlob );

blob.free( theBlob:blob.t);

The blob.free routine frees the storage associated with a blob object if that blob object was allocated on the heap with a call to blob.alloc or blob.allocAligned (specifically, if the allocPtr field in the blobRec data structure contains a non-NULL value). If the allocPtr field contains NULL, then this function returns without raising an exception. If theBlob is NULL, contains a bad address, or if allocPtr isn't pointing at an object on the heap, then this routine will raise an appropriate exception.

This function will also delete the critical section object held b the blob.

blob.destroy( theBlob:blob.t);

The blob.destroy routine deletes the critical section held by the blob. If the allocPtr

field is non-NULL, this will also deallocate the storage held by the blob. Functionally, blob.free and blob.destroy are equivalent; though blob.free is intended for blobs allocated via some blob.allooc* or blob.a_* function and blob.destroy is intended for blobs initialized via the blob.init* functions.

Blob Accessor Functions

The following functions in the HLA blobs unit provide access to the blobRec data structure. Programs should use these accessor functions rather than directly accessing the blobRect fields.

blob.length( b:blob.t); @returns( "eax" );

The blobl.length routine returns the value of the blobRec.length field, that is, the current size (actual data) of the blob.

HLA high-level calling sequence example:

blob.length( b );

mov( eax, blobLength );

HLA low-level calling sequence example:

push( b );

call blob.length;

mov( eax, blobLength );

blob.setLength( b:blob.t; newLen:dword );

The blobl.setLength routine sets the value of the blobRec.length field to the value specified by the newLen parameter. You should exercise extreme caution when using this function. The blob.setLength function does not check the value of the newLen argument to determine if it is valid. You could supply a value larger than the actual amount of data currently in the blob (meaning you've just added garbage to the end of the blob) or you could even supply a value that is beyond the allocated size of the blob (creating memory access problems down the road).

HLA high-level calling sequence example:

blob.setLength( b, 32768 );

HLA low-level calling sequence example:

push( b );

pushd( 32768 );

call blob.setLength;

blob.maxlen( b:blob.t); @returns( "eax" );

The blob.maxlen routine returns the value of the blobRec.maxlen field, that is, the current maximum size of the blob.

HLA high-level calling sequence example:

blob.maxlen( b );

mov( eax, blobMaxLen );

HLA low-level calling sequence example:

push( b );

call blob.maxlen;

mov( eax, blobMaxLen );

blob.setMaxlen( b:blob.t; newLen:dword );

The blobl.setMaxlen routine sets the value of the blobRec.maxlen field to the value specified by the newLen parameter. You should exercise extreme caution when using this function. The blob.setMaxlen function does not check the value of the newLen argument to determine if it is valid. You should only set the value of this field when allocating storage for a new blob or if you are shrinking the size of a blob in-place. Expanding the maxlen value does not allocate any more storage for the blob and such action will probably lead to a memory fault later on in your program. Note that this function does not change the value of the blobRec.length field, even if the new value for maxlen is less than the existing length.

HLA high-level calling sequence example:

blob.setMaxlen( b, 32768 );

HLA low-level calling sequence example:

push( b );

pushd( 32768 );

call blob.setMaxlen;

blob.rcursor( b:blob.t); @returns( "eax" );

The blobl.rcursor routine returns the value of the blobRec.rcursor field in the EAX register.

HLA high-level calling sequence example:

blob.rcursor( b );

mov( eax, blobReadPosition );

HLA low-level calling sequence example:

push( b );

call blob.rcursor;

mov( eax, blobReadPosition );

blob.setrCursor( b:blob.t; newCursor:dword );

The blobl.setrCursor routine sets the value of the blobRec.rcursor field to the value specified by the newCursor parameter. You should exercise extreme caution when using this function. The blob. setrCursor function does not check the value of the newCursor argument to determine if it is valid. If you point the rcursor field beyond the end of the blob's length you could get a memory fault error or read garbage data.

HLA high-level calling sequence example:

blob.setrCursor( b, 0 );

HLA low-level calling sequence example:

push( b );

pushd( 0 );

call blob.setrCursor;

blob.wcursor( b:blob.t); @returns( "eax" );

The blobl.wcursor routine returns the value of the blobRec.wcursor field in the EAX register.

HLA high-level calling sequence example:

blob.wcursor( b );

mov( eax, blobWritePosition );

HLA low-level calling sequence example:

push( b );

call blob.wcursor;

mov( eax, blobWritePosition );

blob.setwCursor( b:blob.t; newCursor:dword );

The blobl.setwCursor routine sets the value of the blobRec.rcursor field to the value specified by the newCursor parameter. You should exercise extreme caution when using this function. The blob. setwCursor function does not check the value of the newCursor argument to determine if it is valid. If you point the wcursor field beyond the end of the blob's length you could get a memory fault error or leave garbage data in the middle of the blob.

HLA high-level calling sequence example:

blob.setwCursor( b, 0 );

HLA low-level calling sequence example:

push( b );

pushd( 0 );

call blob.setwCursor;

blob.reset;

The blobl.reset routine sets the blob's rcursor , wcursor , and length fields to zero. This effectively restores the blob to its original state when it was created. Note that this does not change any actual data appearing the the blob's memory storage, but since blob.reset sets the length field to zero, this effectively erases any data present in the blob.

HLA high-level calling sequence example:

blob.reset();

HLA low-level calling sequence example:

call blob.reset;

blob.eof( b:blob.t ); @returns( "@c" );

This function returns true (1) in EAX and the carry flag if the read cursor is at the end of the blob's data. It returns false (0) otherwise. Note that this function actually returns true/false in EAX even though the "returns" value is "@c". It also returns the EOF state in the carry flag (c=1 if EOF, c=0 if not at EOF).

HLA high-level calling sequence example:

while( !(blob.eof( blobPointer )) do

<< something while not at EOF>>

endwhile;

HLA low-level calling sequence example:

whileNotEOF:

push( blobPointer );

call blob.eof;

cmp( al, true );

jne atEOF;

<< something while not at EOF>>

jmp whileNotEOF;

atEOF:

Blob Assignment Functions

These functions copy blobs and fill a blob with a single byte, word, or double-word value.

blob.a_cpy( b:blob.t ); @returns( "eax" );

This function creates a new blob on the heap that is a copy of the blob pointed at by the b parameter. It returns a pointer to the new blob in the EAX register. When you are done using this new blob, you should free the storage associated with it (and delete the criticalsection it creates) by calling the blob.free function.

HLA high-level calling sequence example:

blob.a_cpy( someBlob );

mov( eax, newBlob );

HLA low-level calling sequence example:

push( someBlob );

call blob.a_cpy;

mov( eax, newBlob);

blob.cpy( src:blob.t; dest:blob.t ); @returns( "eax" );

This function copies the data from the source blob (pointed at by src ) to the destination blob (pointed at by dest ) and returns a pointer to the destination blob in EAX. This function raises an ex.BlobOverflow exception if the destination blob isn’t large enough to hold the data copied from the source blob.

HLA high-level calling sequence example:

blob.cpy( someBlob, destBlob );

HLA low-level calling sequence example:

push( someBlob );

push( destBlob );

call blob.cpy;

blob.fillb( theValue:byte; numBytes:dword; dest:blob );

This function fills an existing blob with numBytes copies of the byte value theValue . This function resets the rcursor field to zero and the wcursor and length fields to numBytes . This function raises an ex.BlobOverflow exception if the destination blob (pointed at by dest ) is not large enough to hold numBytes bytes.

HLA high-level calling sequence example:

blob.fillb( 0, 1024, destBlob );

HLA low-level calling sequence example:

pushd( 0 );

pushd( 1024 );

push( destBlob );

call blob.fillb;

blob.fillw( theValue:word; numWords:dword; dest:blob );

This function fills an existing blob with numWords copies of the word value theValue . This function resets the rcursor field to zero and the wcursor and length fields to numWords*2 . This function raises an ex.BlobOverflow exception if the destination blob (pointed at by dest ) is not large enough to hold numWords*2 bytes.

HLA high-level calling sequence example:

blob.fillw( 1000, 1024, destBlob );

HLA low-level calling sequence example:

pushd( 1000 );

pushd( 1024 );

push( destBlob );

call blob.fillw;

blob.filld( theValue:word; numDwords:dword; dest:blob );

This function fills an existing blob with numDwords copies of the dword value theValue . This function resets the rcursor field to zero and the wcursor and length fields to numDwords*4 . This function raises an ex.BlobOverflow exception if the destination blob (pointed at by dest ) is not large enough to hold numDwords*4 bytes.

HLA high-level calling sequence example:

blob.filld( 1_000_000, 1024, destBlob );

HLA low-level calling sequence example:

pushd( 1_000_000 );

pushd( 1024 );

push( destBlob );

call blob.filld;

Blob Extraction Functions

These funcions extract subranges (slices) of a blob.

blob.a_subBlob( src:blob; start:dword; len:dword ); @returns( "eax" );

This function creates a new blob on the heap and initializes it with data from an existing blob (pointed at by src ). The new blob is initialized with len bytes starting at offset start in blob src . This function returns a pointer to the new blob on the heap in the EAX register. It is the callers responsibility to call blob.free to free the storage associated with this new blob (and delete the critical section that this function creates).

HLA high-level calling sequence example:

blob.a_subBlob( someBlob, 1024, 256 );

mov( eax, newBlob );

HLA low-level calling sequence example:

push( someBlob );

pushd( 1024 );

pushd( 256 );

call blob.a_subBlob;

mov( eax, newBlob );

blob.subBlob( src:blob; start:dword; len:dword; dest:blob.t );

This function copies a sequence from a source blob ( src ) to a destination blob ( dest ). It copies len bytes starting at offset start in src to dest . This function raises an ex.BlobOverflow exception if d is too small to receive the blob data.

HLA high-level calling sequence example:

blob.subBlob( someBlob, 1024, 256, destBlob );

HLA low-level calling sequence example:

push( someBlob );

pushd( 1024 );

pushd( 256 );

push( destBlob

call blob.subBlob;

Blob Comparison Functions

These funcions compare two blobs for equality or inequality.

blob.eq( left:blob; right:blob.t ); @returns( "@c" );

This function compares two blobs and returns true in the carry flag and the AL register if the two blobs are equal to one another.

HLA high-level calling sequence example:

if( blob.eq( someBlob, anotherBlob ) ) then

// Do something if blobs are equal

endif;

HLA low-level calling sequence example:

push( someBlob );

push( anotherBlob );

call blob.eq;

jnc blobsNotEqual;

// Do something if blobs are equal

blobsNotEqual:

blob.ne( left:blob; right:blob.t ); @returns( "@c" );

This function compares two blobs and returns true in the carry flag and the AL register if the two blobs are not equal to one another.

HLA high-level calling sequence example:

if( blob.ne( someBlob, anotherBlob ) ) then

// Do something if blobs are not equal

endif;

HLA low-level calling sequence example:

push( someBlob );

push( anotherBlob );

call blob.eq;

jnc blobsEqual;

// Do something if blobs are not equal

blobsEqual:

Blob Scanning Functions

These funcions convert memory buffers (ranges of bytes) to blob objects

blob.index( src1:blob; src2:blob.t ); @returns( "@c" );

blob.index( src1:blob; offs:dword src2:blob.t ); @returns( "@c" );

blob.index2( src1:blob; src2:blob.t ); @returns( "@c" );

blob.index3( src1:blob; offs:dword src2:blob.t ); @returns( "@c" );

blob.indexStr( src1:blob; src2:string ); @returns( "@c" );

blob.indexStr( src1:blob; offs:dword src2:string ); @returns( "@c" );

blob.indexStr2( src1:blob; src2:string ); @returns( "@c" );

blob.indexStr3( src1:blob; offs:dword src2:string ); @returns( "@c" );

These functions search for the presence of a string or blob within some blob. They return the carry flag set if they find the src2 blob or string within the src1 blob and clear if the src2 string or blob is not found within the src1 blob. The variants with the offs parameter begin searching for the blob or string at offset offs within the blob src1 . If the carry comes back set (meaning src2 was found), then the EAX register will contain the offset into src1 where src1 is first found. These functions raise an ex.ValueOutOfRange exception if the offs value is greater than the current length of src1 .

HLA high-level calling sequence example:

if( blob.index( someBlob, subBlob ) ) then

// Do something if subBlob is a subblob of someBlob

endif;

HLA low-level calling sequence example:

push( someBlob );

push( subBlob );

call blob.index;

jnc notPresent;

// Do something if subBlob is a subblob of someBlob

notPresent:

blob.rindex( src1:blob; src2:blob.t ); @returns( "@c" );

blob.rindex( src1:blob; offs:dword src2:blob.t ); @returns( "@c" );

blob.rindex2( src1:blob; src2:blob.t ); @returns( "@c" );

blob.rindex3( src1:blob; offs:dword src2:blob.t ); @returns( "@c" );

blob.rindexStr( src1:blob; src2:string ); @returns( "@c" );

blob.rindexStr( src1:blob; offs:dword src2:string ); @returns( "@c" );

blob.rindexStr2( src1:blob; src2:string ); @returns( "@c" );

blob.rindexStr3( src1:blob; offs:dword src2:string ); @returns( "@c" );

These functions search backwards for the presence of a string or blob within some blob starting at the end of that blob. They return the carry flag set if they find the src2 blob or string within the src1 blob and clear if the src2 string or blob is not found within the src1 blob. The variants with the offs parameter begin searching for the blob or string at offset length-offs within the blob src1 . If the carry comes back set (meaning src2 was found), then the EAX register will contain the offset into src1 where src1 is last found. These functions raise an ex.ValueOutOfRange exception if the offs value is greater than the current length of src1 .

HLA high-level calling sequence example:

if( blob.rindex( someBlob, subBlob ) ) then

// Do something if subBlob is a subblob of someBlob

endif;

HLA low-level calling sequence example:

push( someBlob );

push( subBlob );

call blob.rindex;

jnc notPresent;

// Do something if subBlob is a subblob of someBlob

notPresent:

blob.chpos( src1:blob; src2:char ); @returns( "@c" );

blob.chpos( src1:blob; offs:dword src2:char ); @returns( "@c" );

blob.chpos2( src1:blob; src2:char ); @returns( "@c" );

blob.chpos3( src1:blob; offs:dword src2:char ); @returns( "@c" );

These functions search for the presence of a character within some blob. They return the carry flag set if they find the src2 character within the src1 blob and clear if the src2 character is not found within the src1 blob. The variants with the offs parameter begin searching for the character at offset offs within the blob src1 . If the carry comes back set (meaning src2 was found), then the EAX register will contain the offset into src1 where src2 is first found. These functions raise an ex.ValueOutOfRange exception if the offs value is greater than the current length of src1 .

HLA high-level calling sequence example:

if( blob.chpos( someBlob, someChar ) ) then

// Do something if someChar is within someBlob

endif;

HLA low-level calling sequence example:

push( someBlob );

mov( someChar, al );

push( eax );

call blob.chpos;

jnc notPresent;

// Do something if someChar is within someBlob

notPresent:

blob.rchpos( src1:blob; src2:char ); @returns( "@c" );

blob.rchpos( src1:blob; offs:dword src2:char ); @returns( "@c" );

blob.rchpos2( src1:blob; src2:char ); @returns( "@c" );

blob.rchpos3( src1:blob; offs:dword src2:char ); @returns( "@c" );

These functions search for the presence of a character within some blob, searching from the end of the blob. They return the carry flag set if they find the src2 character within the src1 blob and clear if the src2 character is not found within the src1 blob. The variants with the offs parameter begin searching for the character at offset offs within the blob src1 . If the carry comes back set (meaning src2 was found), then the EAX register will contain the offset into src1 where src2 is first found. These functions raise an ex.ValueOutOfRange exception if the offs value is greater than the current length of src1 .

HLA high-level calling sequence example:

if( blob.rchpos( someBlob, someChar ) ) then

// Do something if someChar is within someBlob

endif;

HLA low-level calling sequence example:

push( someBlob );

mov( someChar, al );

push( eax );

call blob.rchpos;

jnc notPresent;

// Do something if someChar is within someBlob

notPresent:

Blob Concatenation Functions

There are two major types of blob concatentation functions. The first group (consisting of the blob.cat macro and the blob.cat2 , blob.cat3 , and blob.a_cat functions) take all the data from one blob and concatenates that data to the end (that is, at the length offset) of a second blob. These functions set the length and wcursor fields to point at the end of the new blob and reset the rcursor position of the result to zero.

The second group of concatenation functions take data from a string, a buffer, or a blob and append this to the end of some destination blob starting at the wcursor position in the destination blob.

blob.a_cat( src1:blob; src2:char ); @returns( "@eax" );

This function creates a new blob on the heap whose size is equivalent to the current lengths of the src1 and src2 blobs whose pointers are passed as parameters. This function then copies the data from src1 to the new blob and then appends the data from src2 to the end of this. This function returns a pointer to the new blob in EAX and the length and wcursor fields are set to the new blob’s length and the rcursor field is set to zero. Note that it is the caller’s responsibility to call blob.free in order to return the allocated storage to the heap and delete the newly created critical section object for the blob.

HLA high-level calling sequence example:

blob.a_cat( blob1, blob2 );

mov( eax, newBlob );

HLA low-level calling sequence example:

push( blob1 );

push( blob2 );

call blob.a_cat;

mov( eax, newBlob );

blob.cat( src:blob; dest:blob );

blob.cat2( src:blob; dest:blob );

These functions concatenate the data from the src blob to the end of the data in the dest blob. They raise an ex.BlobOverflow exception if the result will not fit in the destination blob.

HLA high-level calling sequence example:

blob.cat2( srcblob, destblob );

HLA low-level calling sequence example:

push( srcblob );

push( destblob );

call blob.cat2;

mov( eax, newBlob );

blob.cat( src1:blob; src2:blob; dest:blob );

blob.cat3( src1:blob; src2:blob; dest:blob );

These functions concatenate the data from two blobs ( src1 and src2 ) and store the concatenated result into the dest operand. They raise an ex.BlobOverflow exception if the result will not fit in the destination blob.

HLA high-level calling sequence example:

blob.cat3( blob1, blob2, dest );

HLA low-level calling sequence example:

push( blob1 );

push( blob2 );

push( dest );

call blob.cat3;

blob.catsub( src:blob; start:dword; len:dword; dest:blob );

blob.catsub4( src:string; start:dword; len:dword; dest:blob );

blob.catsub( src2:blob; start:dword; len:dword; src1:string; dest:blob );

blob.catsub5( src2:string; start:dword; len:dword; src1:string; dest:blob );

The blob.catsub functions are actually overloaded procedures that map to the blob.catsub4 and blob.catsub5 functions, depending on the call signature.

These functions concatenate the data froma string ( src ) or pair of strings ( src1 and src2 ) and store the concatenated result into the dest blob operand. They raise an ex.BlobOverflow exception if the result will not fit in the destination blob. These functions raise an ex.StringIndexError exception if the start index value is greater than the current length of the string.

The first two functions extract a substring of length len , starting at character position start , from src and concatenate this string to the end of the dest blob.

The second two functions copy the src1 string to the blob and then copy the substring of src2 (specified by start and len ) to the end of this blob.

All of these functions concatenate their strings to the blob starting at the wcursor position in the blob. They will leave wcursor pointing beyond the data just concatenated and will update the length field of the blob if the concatenated data extends the length. These functions do not affect the rcursor field of the blob.

HLA high-level calling sequence example:

blob.catsub4( strVar, 0, 24, dest );

blob.catsub5( strVar2, 0, 24, strVar1, dest );

HLA low-level calling sequence example:

push( strVar );

pushd( 0 );

pushd( 24 );

push( dest );

call blob.catsub4;

push( strVar2 );

pushd( 0 );

pushd( 24 );

push( strVar1 );

push( dest );

call blob.catsub5;

blob.a_catsub( src:blob; start:dword; len:dword; dest:blob );

This function extracts a substring ( src , from start of length len ) and creates a new blob on the heap from the substring data. This function returns a pointer to the new blob in EAX This function sets the rcursor field of the blob to zero and the wcursor and length fields of the blob to len . It is the caller’s responsibility to free the storage allocated by the function (and the critical section it creates) by calling blob.free when the caller is done with this blob.

HLA high-level calling sequence example:

blob.a_catsub( strVar, 0, 24 );

mov( eax, newBlob );

HLA low-level calling sequence example:

push( strVar );

pushd( 0 );

pushd( 24 );

call blob.a_catsub;

mov( eax, newBlob );

blob.catbuf2( src:buf_t; dest:blob );

blob.catbuf3a( startBuf:dword; endBuf:dword; dest:blob );

blob.catbuf2 is a synonym for blob.catbuf3a . As it turns out, a buf_t object passed on the stack is the same as passing the start Buf and endBuf dwords on the stack.

This function concatenates the bytes from a buffer (specified by the src or startBuf / endBuf variables) to the end of an existing blob ( dest ). This function stores the buffer data starting at the offset specified by the wcursor field of the blob. The bytes from memory locations startBuf to endBuf-1 are concatenated to the blob. If the new wcursor field value is greater than length , this function also extends the value of the length field. This function raises an ex. BlobOverflow exception if the new blob size would be greater than the maxlen field value.

HLA high-level calling sequence example:

blob.catbuf3a( startAddress, endAddressPlus1, destBlob );

HLA low-level calling sequence example:

push( startAddress );

push( endAddressPlus1 );

pushd( destBlob );

call blob.catbuf3a;

blob.catbuf3b( src2:buf_t; src1:string; dest:blob );

blob.catbuf4( startBuf:dword; endBuf:dword; strSrc:string; dest:blob );

blob.catbufe3b is a synonym for blob.catbuf4 . As it turns out, a buf_t object passed on the stack is the same as passing the startBuf and endBuf dwords on the stack.

This function concatenates the bytes from a buffer (specified by the src2 or startBuf / endBuf variables) to the end of a string ( strSrc ) and concatenate this data to the end of an existing blob ( dest ). This function stores the buffer data starting at the offset specified by the wcursor field of the blob. The bytes from the string ( strSrc ) and then memory locations startBuf to endBuf-1 are concatenated to the blob. If the new wcursor field value is greater than length , this function also extends the value of the length field. This function raises an ex. BlobOverflow exception if the new blob size would be greater than the maxlen field value.

HLA high-level calling sequence example:

blob.catbuf4( startAddress, endAddressPlus1, someStr, destBlob );

HLA low-level calling sequence example:

push( startAddress );

push( endAddressPlus1 );

push( someStr );

pushd( destBlob );

call blob.catbuf4;

Blob Conversion Functions

These funcions convert memory buffers (ranges of bytes) to blob objects

and strings to blob objects.

blob.bufToBlob2( buf:@global:buf_t; b:blob.t );

blob.bufToBlob3( startBuf:dword; endBuf:dword; b:blob.t );

These functions convert a

range of bytes (specified by a starting and ending address) into a blob object. The blob data is stored into the (previously allocated) blob object pointed at by the b parameter.

Note that these function names are actually synonyms for the same function. As it turns out, passing a buf_t object on the stack produces the exact same stack frame as passing a starting and ending buffer address.

The startBuf parameter is the address of the first byte of the memory block to convert; the endBuf parameter supplies the last address of the buffer plus one.

The b parameter must point at a previously allocated and initialized blob object. This blob must be large enough ( maxlen ) to hold the range of bytes specified by the buffer parameter(s).

HLA low-level calling sequence examples:

blob.bufToBlob3( startingAddress, endingAddress, blobPtr1 );

blob.bufToBlob3( ebx, ecx, blobPtr2 );

blob.bufToBlob2( buf_t_Variable, blobPtr3 );

HLA low-level calling sequence examples:

push( startingAddress );

push( endingAddress );

push( blobPtr1 );

call blob.bufToBlob3;

push( ebx );

push( ecx );

push( blobPtr2 );

call blob.a_bufToBlob2;

push( (type dword buf_t_Variable[0]) );

push( (type dword buf_t_Variable[4]) );

push( blobPtr3 );

call blob.a_bufToBlob1;

blob.a_bufToBlob1( buf:@global:buf_t ); @returns( "@eax" );

blob.a_bufToBlob2( startBuf:dword; endBuf:dword ); @returns( "@eax" );

These functions convert a range of bytes (specified by a starting and ending address) into a blob object. The blob’s data is allocated on the heap and these functions return a pointer to the blob data in the EAX register.

The startBuf parameter is the address of the first byte of the memory block to convert; the endBuf parameter supplies the last address of the buffer plus one.

It is the caller’s responsibility to call blob.free to free up the allocated storage and release the critical section object when the caller is done using the blob these function create.

HLA low-level calling sequence examples:

blob.a_bufToBlob2( startingAddress, endingAddress );

mov( eax, blobPtr1);

blob.a_bufToBlob2( ebx, ecx );

mov( eax, blobPtr2);

blob.a_bufToBlob1( buf_t_Variable );

mov( eax, blobPtr3);

HLA low-level calling sequence examples:

push( startingAddress );

push( endingAddress );

call blob.a_bufToBlob2;

mov( eax, blobPtr1);

push( ebx );

push( ecx );

call blob.a_bufToBlob2;

mov( eax, blobPtr2);

push( (type dword buf_t_Variable[0]) );

push( (type dword buf_t_Variable[4]) );

call blob.a_bufToBlob1;

mov( eax, blobPtr3);

blob.strToBlob( src:string; dest:blob );

blob.zstrToBlob( src:string; dest:blob );

General Blob I/O Functions

Here are the blob file I/O routines provided by the HLA blobs unit:

blob.a_load( FileName: string ); @returns( "eax" );

The blobl.a_load routine opens the file by the specified name, allocates sufficient storage to hold all the data in the file, reads the file's data into the blob, and then closes the file. This function returns a pointer to the initialized blob in the EAX register. You should call blob.free to return this storage to the heap when you are done using the blob.

This function initializes the read cursor so that it points at the beginning of the blob data read from the file. It initializes the write cursor to point at the end of the blob's data; note, however, that there is no additional space allocated at the end of the blob, so any attempt to write data to the blob (without resetting the write cursor to some other point in the blob) will produce a blob overflow exception.

blob.a_loadExtended( FileName: string; extend:dword ); @returns( "eax" );

The blobl.a_loadExtended routine opens the file by the specified name, allocates sufficient storage to hold all the data in the file plus the number of bytes specified by the extend argument, reads the file's data into the blob, and then closes the file. This function returns a pointer to the initialized blob in the EAX register. You should call blob.free to return this storage to the heap when you are done using the blob.

This function initializes the read cursor so that it points at the beginning of the blob data read from the file. It initializes the write cursor to point at the end of the blob's data. Because the blob's size has been extended by the value of the second parameter in the call, you can write that many additional bytes to the file.

blob.load( filename:string; b:blob.t );

The blob.load routine opens the file by the specified name and reads the file's data into the blob specified by the b parameter. This routine raise an exception if there is a problem opening the file (e.g., the file does not exist). If the file is successfully opened, this function will read the file's data into the blob (raising an exception if the file's data is too large to fit in the blob or if there is an error reading the file).

HLA high-level calling sequence examples:

blob.load( filenameStr, b );

blob.a_load( "myfile2.txt" );

mov( eax, b2 );

blob.a_loadExtended( "myfile3.txt", 8192 );

mov( eax, b3 );

HLA low-level calling sequence examples:

push( filenameStr );

push( b );

call blob.open;

// Note: If you want to use a string literal for the filename, the best

// solution is to create a string object in the readonly section, e.g.,

// readonly

// filenameStr2 :string := "myfile2.txt";

// and just use the "filenameStr2" object you’ve created.

push( filenameStr2 );

call blob.a_open;

mov( eax, b2 );

// You may also do the following if you have a register available:

lea( eax, "myfile3.txt" );

push( eax );

pushd( 8192 );

call blob.a_loadExtended;

mov( eax, b3 );

blob.appendFile( filename:string; b:blob.t.blob );

This function opens a file, reads its data, and appends that data to the end of an existing blob. It raises the ex.BlobOverflow exception if the file is to large to append to the end of the blob specified by the b parameter. This call sets the write cursor to the end of the file appended to the blob in memory; it does not affect the value of the read cursor.

HLA high-level calling sequence example:

blob.appendFile( fileNameStr, b );

HLA low-level calling sequence example:

push( filenameStr );

push( b );

call blob.appendFile;

blob.a_appendFile( filename:string; b:blob.t.blob ); @returns( "eax" );

This function creates a new blob on the heap that is the size of the data in the b blob plus the size of the file specified by filename . It copies the data from the b blob to the new blob and then reads the file's data and appends that data to the end of the new blob. It returns a pointer to the new blob in the EAX register (the caller should ultimately call blob.free to return this storage to the heap). This call sets the write cursor to the end of the file appended to the blob in memory; the value of the read cursor will be the same value found in the b blob.

HLA high-level calling sequence example:

blob.a_appendFile( fileNameStr, b );

mov( eax, b2 );

HLA low-level calling sequence example:

push( filenameStr );

push( b );

call blob.a_appendFile;

mov( eax, b2 );

blob.a_appendFileExtended( filename:string; b:blob.t.blob; extend:dword )
{@returns( "eax" )};

This function allocates storage for a new blob that is the size of the existing blob plus the size of the file and the extend value. It then copies the blob specified by the b parameter to the newly allocated blob and appends the file's data to the end of this blob. Finally, it returns a pointer to the new blob in the EAX register. Note that the original blob (specified by the b parameter) is unaffected by this operation. This call sets the write cursor to the end of the file appended to the blob in memory; it sets the value of the read cursor to the same value of the original blob (passed in b ).

HLA high-level calling sequence example:

blob.a_appendFileExtend( fileNameStr, b, 16384 );

HLA low-level calling sequence example:

push( filenameStr );

push( b );

pushd( 16384 )

call blob.a_appendFileExtend;

blob.save( filename:string; b:blob.t );

This function writes the blob's data (specified by the b parameter) to the file specified by the filename parameter. This function will overwrite any existing file.

HLA high-level calling sequence examples:

blob.save( fileNameStr, blobVar );

HLA low-level calling sequence examples:

push( fileNameStr );

push( blobVar );

call blob.save;

Blob Binary I/O Routines

blob.write( b:blob.t; var src:var; len:dword ); @returns( "eax" );

This procedure writes the number of bytes specified by the len variable to the blob specified by the b parameter (at offset wcursor in the blob). The bytes starting at the address of the src object are written to the blob. No range checking is done on the src address value. It is your responsibility to ensure that the buffer contains at least len valid data bytes. Note that src is an untyped reference parameter. This means that blob.write will take the address of whatever object you provide as this parameter (including pointer variables, which may not be what you want). If you want to pass the value of a pointer variable as the buffer address (rather than the address of the pointer variable) when using the high-level style calling syntax, use the VAL keyword as a prefix to the parameter (see the following examples). This function returns the number of bytes written to the blob in the EAX register. If this operation writes bytes beyond the previous length of the blob, it will increment the blobRec.length field of the blob appropriately.

HLA high-level calling sequence examples:

blob.write( blobPointer, buffer, count );

// If bufPtr is a dword object containing the

// address of the buffer whose data you wish to

// write to the blob:

blob.write( blobPointer, val bufPtr, count );

// The following writes the four-byte value of

// the bufPtr variable to the blob (an unusual

// operation):

blob.write( blobPointer, bufPtr, 4 );

HLA low-level calling sequence examples:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

pushd( &buffer );

push( count );

call blob.write;

// If a 32-bit register is available and buffer

// isn’t at a fixed, static, address:

push( blobPointer );

lea( eax, buffer );

push( eax );

push( count );

call blob.write;

// If a 32-bit register is not available and buffer

// isn’t at a fixed, static, address:

push( blobPointer );

sub( 4, esp );

push( eax );

lea( eax, buffer );

mov( eax, [esp+4] );

pop( eax );

push( count );

call blob.write;

// If bufPtr points at the buffer to write,

// then use code like this:

push( blobPointer );

push( bufPtr);

push( count );

call blob.write;

// To write the 4 bytes at bufPtr to

// the file (unusual), you could use

// code like this:

push( blobPointer );

lea( eax, bufPtr );

push( eax );

pushd( 4 );

call blob.write;

blob.writeAt( b:blob.t; var src:var; index:dword; len:dword );
@returns( "eax" );

This procedure writes the number of bytes specified by the len variable to the blob specified by the b parameter at the offset specified by the index parameter. This procedure does not use nor does it modify the blobRec.wcursor value. The bytes starting at the address of the src object are written to the blob. No range checking is done on the src address value. It is your responsibility to ensure that the buffer contains at least len valid data bytes. Note that src is an untyped reference parameter. This means that blob.writeAt will take the address of whatever object you provide as this parameter (including pointer variables, which may not be what you want). If you want to pass the value of a pointer variable as the buffer address (rather than the address of the pointer variable) when using the high-level style calling syntax, use the VAL keyword as a prefix to the parameter (see the following examples). This function returns the number of bytes written to the blob in the EAX register. If the sum of index+len is greater than the previous length of the blob, then this function will extend the length of the blob. If the value of index is greater than the original length of the blob, then this function will return zero in EAX and will not transfer any data to the blob.

HLA high-level calling sequence example:

blob.writeAt( blobPointer, buffer, writeOffset, count );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

pushd( &buffer );

push( writeOffset );

push( count );

call blob.writeAt;

blob.putByte( b:blob.t; byteVal:byte );

This procedure writes a single byte value ( byteVal , which is a single-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 1. This call is effectively equivalent to blob.write( b, byteVal, 1); except that it does not return the number of bytes written in EAX (which is always 1, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putByte( blobPointer, ByteValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory and EAX is available for use:

push( blobPointer );

movzx( ByteValue, eax );

push( eax );

call blob.putByte;

blob.putWord( b:blob.t; wordVal:word );

This procedure writes a single word value ( wordVal , which is a two-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 2. This call is effectively equivalent to blob.write( b, wordVal, 2); except that it does not return the number of bytes written in EAX (which is always 2, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putWord( blobPointer, WordValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

pushw( 0 );

push( WordValue );

call blob.putWord;

blob.putDword( b:blob.t; dwordVal:dword );

This procedure writes a single dword value ( dwordVal , which is a four-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 4. This call is effectively equivalent to blob.write( b, dwordVal, 4); except that it does not return the number of bytes written in EAX (which is always 4, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putDword( blobPointer, DwordValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

push( DwordValue );

call blob.putDword;

blob.putQword( b:blob.t; QwordVal:qword );

This procedure writes a single qword value ( qwordVal , which is an eight-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 8. This call is effectively equivalent to blob.write( b, qwordVal, 8); except that it does not return the number of bytes written in EAX (which is always 8, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putQword( blobPointer, QwordValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

push( (type dword QwordValue[4]) );

push( (type dword QwordValue[0]) );

call blob.putQword;

blob.putTbyte( b:blob.t; tbyteVal:tbyte );

This procedure writes a single tbyte value ( tbyteVal , which is a 10-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 10. This call is effectively equivalent to blob.write( b, tbyteVal, 10); except that it does not return the number of bytes written in EAX (which is always 10, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putTbyte( blobPointer, TByteValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

pushw( 0 );

push( (type word TByteValue [8]) );

push( (type dword TByteValue [4]) );

push( (type dword TByteValue [0]) );

call blob.putTbyte;

blob.putLword( b:blob.t; LwordVal:lword );

This procedure writes a single lword value ( lwordVal , which is a 16-byte binary value) to the blob specified by the b parameter (at offset wcursor in the blob). This function call advances the value of wcursor by 16. This call is effectively equivalent to blob.write( b, lwordVal, 16); except that it does not return the number of bytes written in EAX (which is always 16, assuming there are no exceptions).

HLA high-level calling sequence example:

blob.putLword( blobPointer, LwordValue );

HLA low-level calling sequence example:

// Assumes buffer is a static object at a fixed

// address in memory:

push( blobPointer );

push( (type dword LwordValue[12]) );

push( (type dword LwordValue[8 ]) );

push( (type dword LwordValue[4 ]) );

push( (type dword LwordValue[0 ]) );

call blob.putLword;

blob.read( b:blob.t; var buffer:byte; count:uns32 ); @returns( "eax" );

This routine reads a sequence of count bytes from the specified blob starting at the rcursor position in the blob. It stores the bytes into memory at the address specified by buffer .

It returns the number of bytes actually read from the blob in the EAX register (this is usually equal to the count value, unless the read operation attempts to read beyond the current length of the blob, in which case the actual number of bytes is returned in EAX).

HLA high-level calling sequence examples:

blob.read( blobPointer, buffer, count );

blob.read( blobPointer, [eax], 1024 );

HLA low-level calling sequence examples:

// If buffer is a static variable:

push( blobPointer );

pushd( &buffer );

push( count );

call blob.read;

blob.readAt( b:blob.t; var buffer:byte; index:dword; len:uns32 )

This routine reads a sequence of len bytes from the specified blob starting at offset index into the blob. It stores the bytes into memory at the address specified by buffer .

This function call ignores the initial value in the rcursor variable and it does not change this value. This function returns the actual number of bytes read in the EAX register (which is usually equal to len ). If len plus index is greater than the current blob length, this this function returns the actual number of bytes read (which will be less than len ) in the EAX register.

HLA high-level calling sequence examples:

blob.readAt( blobPointer, buffer, index, count );

blob.readAt( blobPointer, [eax], 500, 1024 );

HLA low-level calling sequence examples:

push( blobPointer );

pushd( &buffer );

push( index );

push( count );

call blob.readAt;

blob.getByte( b:blob.t ); @returns( "al" );

This procedure reads a single byte value from the blob specified by the b parameter (at offset rcursor in the blob) and returns this byte in the AL register. This function call advances the value of rcursor by 1. This call is effectively equivalent to blob.read( b, byteVal, 1); except that it does not return the number of bytes read in EAX (which is always 1, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getByte( blobPointer );

mov( al, ByteValue );

HLA low-level calling sequence example:

push( blobPointer );

call blob.getByte;

mov( al, ByteValue );

blob.getWord( b:blob.t ); @returns( "ax" );

This procedure reads a single word value from the blob specified by the b parameter (at offset rcursor in the blob) and returns this word in the AX register. This function call advances the value of rcursor by 2. This call is effectively equivalent to blob.read( b, wordVal, 2); except that it does not return the number of bytes read in EAX (which is always 2, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getWord( blobPointer );

mov( ax, WordValue );

HLA low-level calling sequence example:

push( blobPointer );

call blob.getWord;

mov( ax, WordValue );

blob.getDword( b:blob.t ); @returns( "eax" );

This procedure reads a single dword value from the blob specified by the b parameter (at offset rcursor in the blob) and returns this dword in the EAX register. This function call advances the value of rcursor by 4. This call is effectively equivalent to blob.read( b, dwordVal, 4); except that it does not return the number of bytes read in EAX (which is always 4, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getDword( blobPointer );

mov( eax, DwordValue );

HLA low-level calling sequence example:

push( blobPointer );

call blob.getDword;

mov( ax, DwordValue );

blob.getQword( b:blob.t ); @returns( "edx:eax" );

This procedure reads a single qword value from the blob specified by the b parameter (at offset rcursor in the blob) and returns this qword in the EDX:EAX register pair. This function call advances the value of rcursor by 8. This call is effectively equivalent to blob.read( b, qwordVal, 8); except that it does not return the number of bytes read in EAX (which is always 8, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getQword( blobPointer );

mov( eax, (type dword QwordValue[0]) );

mov( edx, (type dword QwordValue[4]) );

HLA low-level calling sequence example:

push( blobPointer );

call blob.getQword;

mov( eax, (type dword QwordValue[0]) );

mov( edx, (type dword QwordValue[4]) );

blob.getTbyte( b:blob.t; tbyteVal:tbyte );

This procedure reads a single tbyte value from the blob specified by the b parameter (at offset rcursor in the blob) and stores this tbyte via the tbyteVal reference parameter. This function call advances the value of rcursor by 10. This call is effectively equivalent to blob.read( b, tbyteVal, 10); except that it does not return the number of bytes read in EAX (which is always 10, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getTbyte( blobPointer, tByteVar );

HLA low-level calling sequence example:

push( blobPointer );

pushd( &tbyteVar );

call blob.getTbyte;

blob.getLword( b:blob.t; lwordVal:lword );

This procedure reads a single lword value from the blob specified by the b parameter (at offset rcursor in the blob) and stores this lword via the lwordVal reference parameter. This function call advances the value of rcursor by 16. This call is effectively equivalent to blob.read( b, lwordVal, 16); except that it does not return the number of bytes read in EAX (which is always 16, assuming there are no exceptions).

It will raise an ex.BlobOverflow exception if the value of rcursor is greater than or equal to the current blob length.

HLA high-level calling sequence example:

blob.getLword( blobPointer, lwordVar );

HLA low-level calling sequence example:

push( blobPointer );

pushd( &lwordVar );

call blob.getLword;

Blob Output Routines

The output routines in the blobs module are very similar to the file output routines in the fileio module as well as the output routines in the stdout library module. In general, these routines require (at least) two parameters; the first is the (pointer to the) blob object, the second parameter is usually the value to write to the blob. Some functions contain additional parameters that provide formatting information.

All output is written to the blob at the wcursor offset into the blob's data. For each byte written, wcursor is incremented by 1. If wcursor’s value becomes greater than or equal to the blob’s length value, then length is adjusted as well (that is, length and wcursor will have the same value). If wcursor exceeds the value in the maxlen field, then these functions raise an ex.BlobOverflow exception.

See the descriptions of the corresponding functions in the fileio module for more details.

Note that function names of the form blob.cat* are synonyms for the blob.put* functions.

blob.newln( b:blob.t )

blob.putbool( b:blob.t; b:boolean )

blob.putc( b:blob.t; c:char )

blob.putcSize( b:blob.t; c:char; width:int32; fill:char )

blob.putcset( b:blob.t; cst:cset )

blob.puts( b:blob.t; s:string )

blob.putsSize( b:blob.t; s:string; width:int32; fill:char )

blob.putb( b:blob.t; b:byte )

blob.puth8( b:blob.t; b:byte )

blob.puth8Size( b:blob.t; b:byte; size:dword; fill:char )

blob.putw( b:blob.t; w:word )

blob.puth16( b:blob.t; w:word )

blob.puth16Size( b:blob.t; w:word; size:dword; fill:char )

blob.putd( b:blob.t; d:dword )

blob.puth32( b:blob.t; d:dword )

blob.puth32Size( b:blob.t; d:dword; size:dword; fill:char )

blob.putq( b:blob.t; q:qword )

blob.puth64( b:blob.t; q:qword )

blob.puth64Size( b:blob.t; q:qword; size:dword; fill:char )

blob.puttb( b:blob.t; tb:tbyte )

blob.puth80( b:blob.t; tb:tbyte )

blob.puth80Size( b:blob.t; tb:tbyte; size:dword; fill:char )

blob.putl( b:blob.t; l:lword )

blob.puth128( b:blob.t; l:lword )

blob.puti8 ( b:blob.t; b:byte )

blob.puti8Size ( b:blob.t; b:byte; width:int32; fill:char )

blob.puti16( b:blob.t; w:word )

blob.puti16Size( b:blob.t; w:word; width:int32; fill:char )

blob.puti32( b:blob.t; d:dword )

blob.puti32Size( b:blob.t; d:dword; width:int32; fill:char )

blob.puti64( b:blob.t; q:qword )

blob.puti64Size( b:blob.t; q:qword; width:int32; fill:char )

blob.puti128( b:blob.t; l:lword )

blob.puti128Size( b:blob.t; l:lword; width:int32; fill:char )

blob.putu8 ( b:blob.t; b:byte )

blob.putu8Size( b:blob.t; b:byte; width:int32; fill:char )

blob.putu16( b:blob.t; w:word )

blob.putu16Size( b:blob.t; w:word; width:int32; fill:char )

blob.putu32( b:blob.t; d:dword )

blob.putu32Size( b:blob.t; d:dword; width:int32; fill:char )

blob.putu64( b:blob.t; q:qword )

blob.putu64Size( b:blob.t; q:qword; width:int32; fill:char )

blob.putu128( b:blob.t; l:lword )

blob.putu128Size( b:blob.t; l:lword; width:int32; fill:char )

blob.pute32( b:blob.t; r:real32; width:uns32 )

blob.pute64( b:blob.t; r:real64; width:uns32 )

blob.pute80( b:blob.t; r:real80; width:uns32 )

blob.putr32( b:blob.t; r:real32; width:uns32; decpts:uns32; pad:char )

blob.putr64( b:blob.t; r:real64; width:uns32; decpts:uns32; pad:char )

blob.putr80( b:blob.t; r:real80; width:uns32; decpts:uns32; pad:char )

blob.put( list_of_items )

Blob Input Routines

The input routines in the blobs module are very similar to the file input routines in the fileio module as well as the input routines in the stdin library module. In general, these routines require one parameter: the pointer to the blob object.

All input is read from the blob starting at the rcursor offset into the blob's data. For each byte read, rcursor is incremented by 1. If rcursor’s value becomes greater than or equal to the blob’s length value, then these functions raise an ex.EndOfFile exception.

See the descriptions of the corresponding functions in the fileio module for more details.

blob.readLn( b:blob.t );

blob.eoln( b:blob.t ); @returns( "al" );

blob.getc( b:blob.t ); @returns( "al" );

blob.gets( b:blob.t; s:string );

blob.a_gets( b:blob.t ); @returns( "eax" );

blob.geth8( b:blob.t ); @returns( "al" );

blob.geth16( b:blob.t ); @returns( "ax" );

blob.geth32( b:blob.t ); @returns( "eax" );

blob.geth64( b:blob.t );@returns( "edx:eax" );

blob.geth80( b:blob.t; var dest:tbyte );

blob.geth128( b:blob.t; var dest:lword );

blob.geti8( b:blob.t ); @returns( "al" );

blob.geti16( b:blob.t ); @returns( "ax" );

blob.geti32( b:blob.t ); @returns( "eax" );

blob.geti64( b:blob.t );@returns( "edx:eax" );

blob.geti128( b:blob.t; var dest:lword );

blob.getu8( b:blob.t ); @returns( "al" );

blob.getu16( b:blob.t ); @returns( "ax" );

blob.getu32( b:blob.t ); @returns( "eax" );

blob.getu64( b:blob.t );@returns( "edx:eax" );

blob.getu128( b:blob.t; var dest:lword );

blob.getf( b:blob.t ); @returns( "st0" );

blob.get( List_of_items_to_read );

Character Classification and Utilities Module (chars.hhf)

The HLA CHARS module contains several procedures that classify and convert various character subtypes. Conversion routines include upper and lower case conversion. Classification routines include checking for alphabetic characters, numeric characters, whitespace characters, etc. This module works with ASCII characters in the range #0..#$7F only. Though the functions accept 8-bit character values, non-ASCII characters generally do not get translated by the conversion routines and the predicate routines almost always return false for non-ASCII characters.

A Note About Thread Safety: The routines in this module are all thread safe.

Note about stack diagrams: To conserve space, this documentation does not include a stack diagram for any functions because none of the current "chars" functions pass data on the stack (that is, only a return address appears on the stack).

Conversion Functions

The conversion functions in the chars module convert (alphabetic) characters to lowercase and to uppercase.

chars.toUpper( c:byte ); @returns( "AL" );

This routine returns the character passed as a parameter in the AL register. If the character passed as a parameter was a lower case alphabetic character, this procedure converts it to upper case before returning it. Character values in the range #128..#255 are returned as-is; no conversion is done on those characters even if in some language they could be interpreted as alphabetic characters.

HLA high-level calling sequence examples:

chars.toUpper( charVar );

mov( al, uppercaseCharVar );

chars.toUpper( al );

// AL now contains the uppercase version.

mov( chars.toUpper( ch ), uppercaseCharVar ); // Char is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.toUpper;

mov( al, uppercaseCharVar );

// Char to convert is in AL

call chars.toUpper;

// Result char is left in AL

mov( ch, al );

call chars.toUpper;

mov( al, uppercaseCharVar );

chars.toLower( c:byte ); @returns( "AL" );

This routine returns the character passed as a parameter in the AL register. If the character passed as a parameter was an upper case alphabetic character, this procedure converts it to lower case before returning it. Character values in the range #128..#255 are returned as-is; no conversion is done on those characters even if in some language they could be interpreted as alphabetic characters.

HLA high-level calling sequence examples:

chars.toLower( charVar );

mov( al, lowercaseCharVar );

chars.toLower( al );

// AL now contains the lowercase version.

mov( chars.toLower( ch ), lowercaseCharVar ); // Char is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.toLower;

mov( al, lowercaseCharVar );

// Char to convert is in AL

call chars.toLower;

// Result char is left in AL

mov( ch, al );

call chars.toLower;

mov( al, lowercaseCharVar );

Predicates (Tests)

The following functions test characters in the seven-bit ASCII character set. These functions produce undefined results for other character sets. Note: Although the "returns" value for each of these functions is "AL", in reality these functions all return the Boolean result zero-extended to 32 bits in EAX.

chars.isAlpha( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is an alphabetic character.

HLA high-level calling sequence examples:

chars.isAlpha( charVar );

mov( al, booleanVar );

chars.isAlpha( al );

// AL now contains the Boolean result.

mov( chars.isAlpha( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isAlpha;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isAlpha;

// Result boolean is left in AL

mov( ch, al );

call chars.isAlpha;

mov( al, booleanVar );

chars.isUpper( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is an upper case alphabetic character.

HLA high-level calling sequence examples:

chars.isUpper( charVar );

mov( al, booleanVar );

chars.isUpper( al );

// AL now contains the Boolean result.

mov( chars.isUpper( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isUpper;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isUpper;

// Result boolean is left in AL

mov( ch, al );

call chars.isUpper;

mov( al, booleanVar );

chars.isLower( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is a lower case alphabetic character.

HLA high-level calling sequence examples:

chars.isLower( charVar );

mov( al, booleanVar );

chars.isLower( al );

// AL now contains the Boolean result.

mov( chars.isLower( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isLower;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isLower;

// Result boolean is left in AL

mov( ch, al );

call chars.isLower;

mov( al, booleanVar );

chars.isAlphaNum( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is an alphanumeric character.

HLA high-level calling sequence examples:

chars.isAlphaNum( charVar );

mov( al, booleanVar );

chars.isAlphaNum( al );

// AL now contains the Boolean result.

mov( chars.isAlphaNum( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isAlphaNum;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isAlphaNum;

// Result boolean is left in AL

mov( ch, al );

call chars.isAlphaNum;

mov( al, booleanVar );

chars.isDigit( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is a decimal digit character.

HLA high-level calling sequence examples:

chars.isDigit( charVar );

mov( al, booleanVar );

chars.isDigit( al );

// AL now contains the Boolean result.

mov( chars.isDigit( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isDigit;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isDigit;

// Result boolean is left in AL

mov( ch, al );

call chars.isDigit;

mov( al, booleanVar );

chars.isXDigit( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is a hexadecimal digit character.

HLA high-level calling sequence examples:

chars.isXDigit( charVar );

mov( al, booleanVar );

chars.isXDigit( al );

// AL now contains the Boolean result.

mov( chars.isXDigit( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isXDigit;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isXDigit;

// Result boolean is left in AL

mov( ch, al );

call chars.isXDigit;

mov( al, booleanVar );

chars.isGraphic( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is a printable character or a space (this excludes control characters; also, this function only applies to ASCII characters).

HLA high-level calling sequence examples:

chars.isGraphic( charVar );

mov( al, booleanVar );

chars.isGraphic( al );

// AL now contains the Boolean result.

mov( chars.isGraphic( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isGraphic;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isGraphic;

// Result boolean is left in AL

mov( ch, al );

call chars.isGraphic;

mov( al, booleanVar );

chars.isSpace( c:byte ); @returns( "AL" );

This routine returns true in the AL register if the parameter is a white space character. A white space character is a space, carriage return, linefeed, or tab character.

HLA high-level calling sequence examples:

chars.isSpace( charVar );

mov( al, booleanVar );

chars.isSpace( al );

// AL now contains the Boolean result.

mov( chars.isSpace( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isSpace;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isSpace;

// Result boolean is left in AL

mov( ch, al );

call chars.isSpace;

mov( al, booleanVar );

chars.isASCII( c:byte ); @returns( "AL" );

This routine returns true in AL if the parameter byte is an ASCII character (value in the range $0..$7F).

HLA high-level calling sequence examples:

chars.isASCII( charVar );

mov( al, booleanVar );

chars.isASCII( al );

// AL now contains the Boolean result.

mov( chars.isASCII( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isASCII;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isASCII;

// Result boolean is left in AL

mov( ch, al );

call chars.isASCII;

mov( al, booleanVar );

chars.isCtrl( c:byte ); @returns( "AL" );

This function returns true in AL if the parameter is a control character ($0..$1F or $7F).

HLA high-level calling sequence examples:

chars.isCtrl( charVar );

mov( al, booleanVar );

chars.isCtrl( al );

// AL now contains the Boolean result.

mov( chars.isCtrl( ch ), booleanVar ); // Result is left in AL.

HLA low-level calling sequence examples:

mov( charVar, al );

call chars.isCtrl;

mov( al, booleanVar );

// Char to convert is in AL

call chars.isCtrl;

// Result boolean is left in AL

mov( ch, al );

call chars.isCtrl;

mov( al, booleanVar );

Console Display Control (console.hhf)

The HLA console module provides a reasonably portable way to control the console display under different operating systems. The routines in this module let you write "really-smart-terminal" console applications that behave in a similar fashion under different operating. The HLA console module routines take advantage of the Windows console API when running under Windows, they use the VT100/ANSI terminal control code sequences for other operating systems that use ANSI terminal control codes for console control. The routines in this module let you control the cursor position, erase selected portions of data from the screen, insert and delete characters and lines of text, scroll the screen, select display colors, and so on.

Note: this console module replaces the older HLA Standard Library console module that was Win32-specific. That earlier console module provided many features that are not present in the current console module because the Win32 console capabilities are quite a bit more sophisiticated than is possible with an ANSI terminal emulation. Older code that took advantage of these extra features will not be able to compile properly with this new console module. The original console module is still available in the HLA distribution under the "Examples" directory; new code, however, should not use that module; if you want to take advantage of the Win32 console capabilities, you should call the Win32 API routines directly.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

The Console Module Module

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

#include( "console.hhf" )

#include( "stdlib.hhf" )

Cursor Positioning Functions

The functions in this category reposition the cursor on the display

procedure console.gotoxy( x:dword; y:dword ); @pascal
procedure console.gotorc( r:dword; c:dword ); @stdcall

console.gotoxy and console.gotorc are actually the same function. The only difference between the two calls is that they (internally) swap their parameters before making the call to the function. Note that the "rc" in gotorc stands for "row/column" which is equivalent to saying "gotoyx". The console.gotorc function was provided because people intuitively prefer to specify the row (y) value as the first argument and the column (x) value as the second argument.

These functions position the cursor at the specified (x,y)/(c,r) coordinate on the screen.

HLA high-level calling sequence examples:

console.gotoxy( 0, 10 );

stdout.put( "Print this on line 10, column 0" nl );

console.gotoxy( 15, 0 );

stdout.put( "Print this on line 15, column 0" nl );

HLA low-level calling sequence examples:

pushd( 0 );

pushd( 10 );

call console.gotoxy; // row = 10, column = 0

// Note that console.gotorc uses the @stdcall calling convention, so

// it’s arguments are reversed from the declaration, that is, you

// push the same exact arguments you push for gotoxy (which makes

// sense, as both functions are actually the same code).

pushd( 0 );

pushd( 15 );

call console.gotorc;

procedure console.up();

console.up moves the cursor up one line. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure when the cursor is on the first line of the display. Some consoles scroll the screen down one line, others ignore the request.

HLA high-level calling sequence example:

console.up();

HLA low-level calling sequence example:

call console.up;

procedure console.nup( n:uns32);

console.nup moves the cursor up n lines. Because of the variation in terminal emulations out there, the results are undefined if this procedure attempts to move above the top line on the display. Some consoles scroll the screen down one line, others ignore the request.

HLA high-level calling sequence example:

console.nup( 5 );

HLA low-level calling sequence example:

pushd( 5 );

call console.nup;

procedure console.down();

console.down moves the cursor down one line. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure when the cursor is on the last line of the display. Some consoles scroll the screen up one line, others ignore the request..

HLA high-level calling sequence example:

console.down();

HLA low-level calling sequence example:

call console.down;

procedure console.ndown( n:uns32);

console.ndown moves the cursor down one line. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure when the cursor is on the last line of the display. Some consoles scroll the screen up one line, others ignore the request.

HLA high-level calling sequence example:

console.ndown( 5 );

HLA low-level calling sequence example:

pushd( 5 );

call console.ndown;

procedure console.left();

console.left moves the cursor up n lines. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure and it attempts to move the cursor before the first column on the line. Some consoles move the cursor to the end of the previous line, others ignore the request.

HLA high-level calling sequence example:

console.left();

HLA low-level calling sequence example:

call console.left;

procedure console.nleft( n:uns32);

console.nleft moves the cursor down one line. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure when the cursor is on the last line of the display. Some consoles scroll the screen up one line, others ignore the request.

HLA high-level calling sequence example:

console.nleft( 5 );

HLA low-level calling sequence example:

pushd( 5 );

call console.nleft;

procedure console.right();

console.right moves the cursor to the right one character position. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure when the cursor is at the last column of the display. Some consoles move the cursor to the beginning of the next line, others ignore the request.

HLA high-level calling sequence example:

console.right();

HLA low-level calling sequence example:

call console.right;

procedure console.nright( n:uns32);

console.nright moves the cursor down one line. Because of the variation in terminal emulations out there, the results are undefined if you execute this procedure and it attempts to move the cursor beyond the last column of the display. Some consoles move the cursor to the beginning of the next line, others ignore the request.

HLA high-level calling sequence example:

console.nright( 5 );

HLA low-level calling sequence example:

pushd( 5 );

call console.nright;

procedure console.saveCursor();

console.saveCursor saves the current cursor position in an internal variable. You can restore the cursor position via the console.restoreCursor call. Note that there is only one level of save available.

HLA high-level calling sequence example:

console.saveCursor();

HLA low-level calling sequence example:

call console.saveCursor;

procedure console.restoreCursor();

console.saveCursor restores the cursor to the position previously saved by console.saveCursor. Note that there is only one level of "save" available.

HLA high-level calling sequence example:

console.restoreCursor();

HLA low-level calling sequence example:

call console.restoreCursor;

Console Clearing Functions

The functions in this category clear portions (or all) of the display.

procedure console.cls();
procedure console.home();

console.cls and console.home are actually the same function. These procedures clear the screen and move the cursor to the home (0,0) position.

HLA high-level calling sequence examples:

console.cls();

console.home();

HLA low-level calling sequence examples:

call console.cls;

call console.home;

procedure console.clrToEOLN();

console.clrToEOLN clears the text (by writing spaces) from the current cursor position to the end of the line that the cursor is on.

HLA high-level calling sequence examples:

console.clrToEOLN();

HLA low-level calling sequence examples:

call console.clrToEOLN;

procedure console.clrToBOLN();

console.clrToBOLN clears the text (by writing spaces) from the current cursor position to the beginning of the line that the cursor is on.

HLA high-level calling sequence examples:

console.clrToBOLN();

HLA low-level calling sequence examples:

call console.clrToBOLN;

procedure console.clrLn();

console.clrLn clears the line that the cursor is on by writing spaces to that line. This does not delete the line from the screen, it only clears the characters from the line.

HLA high-level calling sequence examples:

console.clrLn();

HLA low-level calling sequence examples:

call console.clrLn;

procedure console.clrToEOScrn();

console.clrToEOScrn clears the text (by writing spaces) from the current cursor position to the end of the screen.

HLA high-level calling sequence examples:

console.clrToEOScrn();

HLA low-level calling sequence examples:

call console.clrToEOScrn;

procedure console.clrToBOScrn();

console.clrToBOScrn clears the text (by writing spaces) from the current cursor position to the beginning of the screen.

HLA high-level calling sequence examples:

console.clrToBOScrn();

HLA low-level calling sequence examples:

call console.clrToBOScrn;

Character Insertion/Removal Functions

The functions in this category insert and delete characters on the console display.

procedure console.insertChar();

console.insertChar inserts room for a single character by shifting the characters under the cursor and to the right of the cursor to the right one position. The vacated position is filled with a space. The last character on the line is lost.

HLA high-level calling sequence examples:

console.insertChar();

HLA low-level calling sequence examples:

call console.insertChar;

procedure console.insertChars( n:dword );

console.insertChars inserts room for n characters by shifting the characters under the cursor and to the right of the cursor right n positions. The vacated positions are filled with spaces. The last n characters on the line are lost.

HLA high-level calling sequence examples:

console.insertChars( n );

HLA low-level calling sequence examples:

pushd( n );

call console.insertChars;

procedure console.insertLine();

console.insertLine inserts a blank line before the line the cursor is on by pushing the line under the cursor, and the lines below the cursor, down one line on the screen. The new line is filled with blanks. The last line on the screen is lost.

HLA high-level calling sequence examples:

console.insertLine();

HLA low-level calling sequence examples:

call console.insertLine;

procedure console.insertLines( n:dword );

console.insertLines opens up n new blank lines at the current cursor position by pushing the lines at and below the cursor down n lines on the screen. The last n lines on the screen will be lost.

HLA high-level calling sequence examples:

console.insertLines( 5 );

HLA low-level calling sequence examples:

pushd( 5 );

call console.insertLines;

procedure console.deleteChar();

console.deleteChar deletes the character under the cursor by shifting the characters after the cursor one position to the left. The last character position at the end of the line is filled with a blank.

HLA high-level calling sequence examples:

console.deleteChar();

HLA low-level calling sequence examples:

call console.deleteChar;

procedure console.deleteChars( n:dword );

console.deleteChars deletes n characters under and to the right of the cursor by shifting the characters after the cursor n positions to the left. The n character positions at the end of the line are filled with blanks.

HLA high-level calling sequence examples:

console.deleteChars( n );

HLA low-level calling sequence examples:

pushd( n );

call console.deleteChars;

procedure console.deleteLine();

console.deleteLine deletes the line the cursor is one by shifting all the lines below the cursor position up one line. The last line on the screen is filled with blanks.

HLA high-level calling sequence examples:

console.deleteLine();

HLA low-level calling sequence examples:

call console.deleteLine;

procedure console.deleteLines( n:dword );

console.deleteLines procedure deletes n lines at and below the current cursor position. The vacated lines at the bottom of the screen are filled with blanks.

HLA high-level calling sequence examples:

console.deleteLines( 5 );

HLA low-level calling sequence examples:

pushd( 5 );

call console.deleteLines;

Console Scrolling

The functions in this category scroll the screen up and down.

procedure console.scrollUp( );

console.scrollUp scrolls the entire screen up one line.

HLA high-level calling sequence examples:

console.scrollUp();

HLA low-level calling sequence examples:

call console.scrollUp;

procedure console.scrollDown( );

console.scrollDown scrolls the entire screen down one line.

HLA high-level calling sequence examples:

console.scrollDown();

HLA low-level calling sequence examples:

call console.scrollDown;

Console Output Colors

The functions in this category control the color of the characters printed on the display.

procedure console.setAttrs( foreground:uns32; background:uns32 );

console.setAttrs sets the console internal attribute value to be used for all following character output. Use the routine to set the color of the characters you wish to print. The foreground parameter sets the color for the text characters, the background parameter sets the color of the background area of each character cell.

The console module defines the following constants that represent the corresponding colors:

console.black := 0;

console.red := 1;

console.green := 2;

console.yellow := 3;

console.blue := 4;

console.magenta := 5;

console.cyan := 6;

console.white := 7;

HLA high-level calling sequence examples:

console.setAttrs( console.yellow, console.blue );

HLA low-level calling sequence examples:

pushd( console.yellow );

pushd( console.blue );

call console.setAttrs;

Conversions (conv.hhf)

This unit contains routines that perform general conversions from one data type to another. Primarily, this unit supplies the routines that convert various data types to and from string form.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

Most string conversion routines take two forms: one version that writes data to an existing (preallocated) string and one that automatically allocates storage for a new string on the heap. Those functions that automatically allocate storage generally have a name that begins with "a_" (for allocate) whereas the functions that use a preallocated string do not have such a prefix. For example, the conv.h8ToStr function converts an 8-bit integer to a string using hexadecimal representation and stores the result in a preallocated string object. The conv.a_h8ToStr function converts an 8-bit value to a (hexadecimal) string that it allocates on the heap; conv.a_h8ToStr returns a pointer to that string in the EAX register.

An important point to keep in mind is that string variables are pointers. Unless you call a function that allocates storage for a string (i.e., one of the "a_..." functions), you must ensure that you’ve allocated sufficient storage to hold any string result the function produces. Failure to do so will produce a memory access error, null pointer reference error, or string overflow error. Remember, simply declaring a string variable does not automatically allocate storage for any string data; the declaration only allocates storage for the string pointer. You must call a function such as str.alloc to actually allocate the string data.

Buffer vs. String Conversions

The Standard Library supports two generic types of numeric-to-string conversions – output to a string variable (an "HLA string" object) and output to a memory buffer. The string conversion routines are the safest to use, but the buffer conversion routines are a bit more general.

If you’re working with HLA-style string objects, then using the conversion-to-string functions make the most sense because you get to take full advantage of range checking and other facilities that are possible with the string format. Furthermore, you can use the Standard Library string manipulation functions to process such strings once the conversion is complete.

There are two drawbacks to the string conversion routines (versus the buffer conversion routines):

You may intend to pass the converted data on to some other routine that doesn’t know anything about the HLA string format, so you may need to produce the string using a different data structure.
If you want to produce a longer string as a sequence of conversion operations, it is slightly more efficient to do the conversion to a single buffer (which may very well be an HLA string object) and fix up the string data structure afterwards.

Perhaps the most common example of a non-HLA-string data type you’ll encounter is the simple zero-terminated string (the word "simple" appears here because HLA strings are zero-terminated and you can often use them whenever you need a zero-terminated string). Consider the conv.i32ToBuf routine that converts a 32-bit signed integer to the corresponding sequence of characters. This function stores that characters at the memory address passed in EDI and upon return EDI points at the first byte beyond the converted sequence, e.g.,

// Stores the characters "12345" at [edi]

conv.i32ToBuf( 12345, [edi] );

Upon return from this function, EDI will contain a value that is 5 greater than it was upon entry, and the five memory locations that EDI has skipped over will contain the characters "12345". Note that this string is not zero-terminated, but you can easily zero-terminate it by storing a zero byte at the location where EDI points upon return from the function:

// Stores the characters "12345" at [edi] and zero

// terminates the string.

conv.i32ToBuf( 12345, [edi] );

mov( 0, (type byte [edi]));

As a final example, suppose you want to build up an HLA style string by concatenating two converted strings together. You could do something like the following:

// Produces " 12345 67890" in fullStr

conv.i32ToStr( 12345, 6, ‘ ‘, leftStr );

conv.i32ToStr( 67890, 7, ‘ ‘, rightStr

str.cat( leftStr, rightStr, fullStr );

The only problem with this approach is that there is unnecessary string processing (e.g., data copying) taking place. If efficiency is paramount, and you don’t need the intermediate conversions (leftStr and rightStr), then you can do this sequence a little bit faster by generating the two strings in place as follows:

mov( fullStr, edi ); // Point EDI at start of string data

mov( edi, ebx ); // Save to compute length

conv.i32ToBuf( 12345, 6, ‘ ‘ ); // Store " 12345" at fullStr

conv.i32ToBuf( 67890, 7, ‘ ‘ ); // Store " 67890" at fullStr+6

mov( 0, (type byte [edi])); // HLA strings must be zero terminated

sub( fullStr, edi ); // Compute string length

mov( edi, (type str.strRec [ebx]).length ); // Save new length.

As the number of objects you append to the string increases, this scheme becomes even more efficient than using the str.cat approach. The code above, of course, assumes that you’ve already allocated a sufficient amount of string storage for the leftStr, rightStr, and fullStr string variables.

Conversion Format Control

The following functions control the numeric conversion process.

Underscore Control

When converting numeric data types to strings, the standard library offers the option of inserting underscores at appropriate places in the numbers (i.e., where you would normally expect a digit separator to appear, such as a comma [U.S.] or period [Europe]). The conv.setUnderscores and conv.getUnderscores functions control the operation of this feature.

The standard library conversion functions will inject underscores into hexadecimal, unsigned integers, and signed integers if the feature is enabled. For hexadecimal output the standard library conversion routines will emit an underscore between every fourth and fifth digit, starting with the L.O. digit (e.g., 1234_5678). For decimal integers (signed or unsigned), the conversion routines emit an underscore between each third and fourth digit starting with the L.O. digit (e.g., 123_456_789).

Note that the conversion routines do not emit underscores into conversions of floating-point/real values.

Thread Issues: Because the standard library maintains the internal underscore flag as a static object there will be some problems if you attempt to read and set the underscore flag in multiple threads running in the same address space. In particular, if you read the underscores flag and save it, set it to a different value, do some conversions, and then restore the underscores flag its original value, it is quite possible that another thread could do some conversions between those two points and produce incorrect output. Indeed, it would even be possible for half the number to contain underscores and the other half not contain underscores, depending on where the system interrupts the second thread. The current library code does not address this issue because the cost is very high to solve a problem that almost never occurs (most assembly applications are single-threaded). However, if you are writing a multi-threaded application, you should note that constantly changing the underscores flag is not a good idea – you should try to set the flag once, at the beginning of your program, and leave it alone throughout the program’s execution. If you must change the underscore flag setting on a regular basis within a multi-threaded application, you should put appropriate locks around all calls to conversion routines (and those routines, such as the I/O routines, that call the conversion code) to protect the settings.

Current plans are to make the Standard Library thread-safe when the threads module is added to the library.

conv.setUnderscores( onOff: boolean );

The conv.setUnderscores function lets you enable or disable the emission of underscores in numeric values. Passing true enables underscore emission, passing false disables it.

For efficiency reasons, the standard library routines always pass all parameters as a multiple of four bytes. The onOff Boolean parameter consumes the L.O. byte of the double word passed on the stack. The conv.setUnderscore routine ignores the H.O. three bytes of the value passed for this parameter, though by convention (to make debugging a little easier) you should try to pass zeros in the H.O. three bytes if it is not inconvenient to do so.

When passing a Boolean constant, you should simply push the dword containing the value true (1) or false (0), e.g,

pushd( true );

call conv.setUnderscores;

pushd( false );

call conv.setUnderscores;

When passing the Boolean value in one of the 8-bit registers AL, BL, CL or DL, you should simply push the 32-bit register that holds the 8-bit register, e.g.,

push( eax ); // Pushes AL onto the stack

call conv.setUnderscores;

push( ebx ); // Pushes BL onto the stack

call conv.setUnderscores;

sub( 4, esp );

mov( AH, [esp] ); // Pushes AH onto the stack

call conv.setUnderscores;

sub( 4, esp );

mov( BH, [esp] ); // Pushes BH onto the stack

call conv.setUnderscores;

Here’s another way you can accomplish this (a little slower, but leaves zeros in the H.O. three bytes):

pushd( 0 );

mov( CH, [esp] ); // Pushes CH onto the stack

call conv.setUnderscores;

When passing a Boolean variable, you should try to push the Boolean value and the following three bytes, using code like the following (HLA syntax):

pushd( (type dword boolVar ));

call conv.setUnderscores;

There is one drawback to the approach above. In three very rare cases the code above could cause a segmentation fault. If the Boolean variable is located on the last three bytes of a page in memory (4,096 bytes) and the next memory page is not readable, the system will generate a fault if you attempt to push all four bytes. In such a case, the next best solution, if a register is available, is to move the Boolean value into AL, BL, CL, or DL and push the corresponding 32-bit register. If no registers are available, then you can write code like the following:

push( eax );

mov( boolVar, al );

mov( al, [esp+4] );

pop( eax );

call conv.setUnderscores;

This code is ugly and slightly inefficient, but it will always work (assuming, of course, you don’t get a stack overflow).

The HLA compiler will generate code similar to this last example if you pass a boolean variable as the actual parameter to conv.setUnderscores:

conv.setUnderscores( boolVar );

Therefore, if efficiency is a concern to you, you should try to load the Boolean variable (boolVar in this example) into AL, BL, CL, or DL prior to calling conv.setUnderscores, e.g.,

mov( boolVar, al );

conv.setUnderscores( al );

conv.getUnderscores; @returns( "eax" );

You can test the current state of the underscore conversion by calling conv.getUnderscores. This function call returns the boolean result in EAX (true means underscores will be output); AL will contain the actual Boolean value and the H.O. three bytes of EAX will all contain zero. This routine does not have any parameters.

The following example demonstrates how to preserve the value of the internal underscores flag across some section of code:

conv.getUnderscores();

mov( al, saveUnderscores );

conv.setUnderscores( true );

mov( saveUnderscores, al );

conv.setUnderscores( al );

Note: Do not try to access the internal underscores flag directly in your program. Always use the conv.setUnderscores and conv.getUnderscores accessor functions. In a future version of the Standard Library, the internal representation of this flag will change and any code that accesses it directly will break at that point. However, if you call conv.setUnderscores and conv.getUnderscores, you’re guaranteed that the internal implementation will be hidden from you and your code will not fail when the internal representation changes.

Delimiter Control

During the conversion from string to a numeric form, the conversion routines will skip over zero or more delimiter characters and then process all numeric digits (including hexadecimal digits, if doing a hexadecimal conversion) up to the end of string or the first delimiter character it finds. If a conversion function encounters a value that is not a valid digit or delimiter character, it will raise a conversion exception or an illegal character exception By default, the delimiter characters are members of the following set:

Delimiters: cset :=

{

#0, // End of string

#9, // Tab

#10, // Line feed

#13, // Carriage return

' ' , // Space

',', // Comma

';', // Semicolon

':' // Colon

};

While this default delimiters character set is probably appropriate for most applications, some programmers may want to add or remove characters from this set based on their application requirements. The standard library provides two routines that provide access to this internal character set object: conv.getDelimiters and conv.setDelimiters. You should always use these routines to access this character set object rather than accessing it directly (as an external object).

Thread Issues: Because the standard library maintains the internal delimiters character set as a static object there will be some problems if you attempt to read and set the delimiters in multiple threads running in the same address space. In particular, if you read the delimiters character set and save it, set it to a different value, do some conversions, and then restore the delimiters to the original value, it is quite possible that another thread could do some conversions between those two points and produce incorrect. The current library code does not address this issue because the cost is very high to solve a problem that almost never occurs (most assembly applications are single-threaded). However, if you are writing a multi-threaded application, you should note that constantly changing the delimiters character set is not a good idea – you should try to set the delimiters once, at the beginning of your program, and leave them alone throughout the program’s execution. If you must change the delimiters character set on a regular basis within a multi-threaded application, you should put appropriate locks around all calls to conversion routines (and those routines, such as the I/O routines, that call the conversion code) to protect the settings.

Current plans are to make the delimiters character set object thread-safe when the processes module is added to the library.

Note: Do not try to access the internal delimiters character set directly in your program. Always use the conv.setDelimiters and conv.getDelimiters accessor functions. In a future version of the Standard Library, the internal representation of this character set will change and any code that accesses it directly will break at that point. However, if you call conv.setDelimiters and conv.getDelimiters , you’re guaranteed that the internal implementation will be hidden from you and your code will not fail when the internal representation changes.

conv.getDelimiters( var Delims: cset );

The conv.getDelimiters routine returns the current delimiters character set in the variable you pass by reference as the parameter. The Delims parameter is passed by reference (that is, you pass the address of the actual cset variable to receive the result). The following are examples of typical HLA high-level invocations of this routine looks like this:

conv.getDelimiters( saveDelims );

// EDI points at the delimiter cset:

conv.getDelimiters( [edi] );

// ptrtoDelims is a dword/pointer variable that contains

// the address of a cset object:

conv.getDelimiters( val ptrToDelims );

To call conv.getDelimiters using a low-level assembly syntax, you must push the address of a cset variable object onto the stack and then call the conv.getDelimiters function:

// saveDelims_s is a variable declared in the static/storage section:

pushd( &saveDelims_s );

call conv.getDelimiters;

// saveDelims_v is a variable declared in the var section or

// is a parameter:

lea( eax, saveDelims_v );

push( eax );

call conv.getDelimiters;

// Alternative call passing saveDelims_v if no 32-bit registers

// are available (this code assumes that EBP points at the current

// activation record/stack frame that contains saveDelims_v):

push( ebp );

add( @offset( saveDelims_v ), (type dword [esp] ));

call conv.getDelimiters;

// Low-level call assuming a 32-bit register (esi in this case)

// contains the address of the cset:

push( esi );

call conv.getDelimiters;

// Low-level call assuming a dword or pointer variable contains the

// address of the cset that will receive the delimiter character set:

push( ptrToDelims );

call conv.getDelimiters;

conv.setDelimiters( Delims: cset )

The conv.setDelimiters function lets you change the value of the internal delimiter character set. It requires a 16-byte character set parameter (passed by value) and will copy the value of this parameter to the internal character set variable. Note that this routine makes a copy of the actual parameter you pass it. If you pass an character set variable as the actual parameter, future changes to that character set variable (without a corresponding call to conv.setDelimiters) will have no effect on the internal delimiters character set that the standard library routines use. The following examples are typical HLL style calls to this function:

conv.setDelimiters( {‘ ‘, ‘,’} ); // Pass in a literal constant

conv.setDelimiters( csetVar ); // Pass in a cset variable’s value

conv.setDelimiters( [edx] ); // EDX points at a cset variable

To call conv.setDelimiters using a low-level calling sequence, you’d first push the 16 bytes associated with the character set object (H.O. dword first down to the L.O. dword) and then call the conv.setDelimiters function. Here are some examples:

// Push the literal cset constant {‘ ‘, ‘,’} onto the stack:

pushd( 0 ); // Must manually convert cset to a sequence of

pushd( $1001 ); // four dwords (ugh!). Note: ORD( ‘ ‘ ) = $20

pushd( 0 ); // and ORD(‘,’) = $2C so bit positions $20 and

pushd( 0 ); // $2c must contain ‘1’s, zeros everywhere else.

call conv.setDelimiters;

// Push the cset variable "saveDelims" onto the stack and

// call conv.setDelimiters:

push( (type dword saveDelims[12]));

push( (type dword saveDelims[8]) );

push( (type dword saveDelims[4]) );

push( (type dword saveDelims[0]) );

call conv.setDelimiters.

// If manually converting a literal cset constant to the equivalent

// numeric values isn’t your thing, you can also do the following

// (though this is slightly less efficient):

readonly

spaceAndComma :cset := {‘ ‘, ‘,’ };

endreadonly

push( (type dword spaceAndComma [12]));

push( (type dword spaceAndComma [8]) );

push( (type dword spaceAndComma [4]) );

push( (type dword spaceAndComma [0]) );

call conv.setDelimiters.

If you insist on using low-level calling sequences to call the conv.setDelimiters routine, you might want to consider writing a macro that will automatically push a literal cset constant for you. Here is a set of HLA macros that will do this task:

program t;

// dword_n extracts the nth dword (0, 1, 2, 3) from a

// 16-byte object such as a character set. cst must be

// a cset constant value (or an lword), n must be an

// integer constant in the range 0..3.

#macro dword_n( cst, n );

(

(@byte( @lword(cst), n*4+3) << 24)

| (@byte( @lword(cst), n*4+2) << 16)

| (@byte( @lword(cst), n*4+1) << 8)

| (@byte( @lword(cst), n*4+0) << 0)

)

#endmacro

// pushcset pushes the cset constant passed as an argument

// onto the CPU’s stack. H.O. dword is pushed first, L.O.

// dword is pushed last.

#macro pushcset( cst );

// Push the four dwords that make up a cset constant:

pushd( dword_n( cst, 3 ) );

pushd( dword_n( cst, 2 ) );

pushd( dword_n( cst, 1 ) );

pushd( dword_n( cst, 0 ) );

#endmacro

begin t;

// Example of pushcset invocation:

pushcset( {' ', ','} );

end t;

Here is an example using conv.getDelimiters and conv.setDelimiters that demonstrates how to temporarily change the delimiters character set and the restore its value:

var

saveDelims :cset;

conv.getDelimiters( saveDelims );

conv.setDelimiters( { ‘!’, ‘@’ } )l

conv.setDelimiters( saveDelims );

Hexadecimal Conversions

The standard library hexadecimal routines convert numeric values of varying sizes (8, 16, 32, 64, 80, and 128 bits) into a string of characters holding the hexadecimal representation of those values. The hexadecimal output routines can be broken down into the following categories:

Output type (string or sequence of characters to a buffer)

Fill type (no fill; fill with zeros to

a standardized length, based on data type; fill with a caller-specified character to a caller-specified length).

Internal Routines

The conversions module in the standard library contains several routines that are intended for internal use only. Generally, you should not call these routines directly from your application programs. These routines all have names that begin with an underscore. The internal hexadecimal conversion routines include: _hexTobuf64Size, _hexTobuf80, _hexTobuf80Size, _hexTobuf128, _hexTobuf128Size, _hexTobuf32, _hexTobuf32Size, and _hexTobuf64.

Hexadecimal Numeric Size Functions

The hexadecimal conversion size functions return the number of digit print positions required by the conversion of a numeric value to a hexadecimal string. There are two sets of six routines that compute the output size: one set computes the fixed-size width and the other set computes a varying-sized width.

Fixed Size Hexadecimal Size Functions

It is common practice to display hexadecimal values using exactly one digit for each nibble of the corresponding data type, including leading zeros, as necessary. The common fixed sizes are byte=2, word=4, dword=8, qword=16, tbyte=20, and lword=32. With underscore output enabled (see conv.setUnderscores) these values are byte=2, word=4, dword=9, qword=19, tb=24, and lword=39. Because these numbers are fixed (at least, for a given underscores flag setting) there are only three reasons for calling these functions:

You don’t know the underscores flag setting when executing a particular section of code (which can affect the output size of dword, qword, tbyte, and lword objects), or,
You’re generating a call to these functions via some macro that is given a function name like "putb" or "puth8" and you’re manually constructing the size function to call via the assembler’s compile-time language. or,
You’re writing generic code and you want to make it easy to modify the code in the future.

procedure conv.bSize( b:byte in al ); @returns( "eax" );

This function always returns 2 because the fixed output size of a byte is two hexadecimal digits (two 4-bit nibbles).

HLA high-level calling sequence examples:

conv.bSize( byteVariable );

conv.bSize( <byte register> ); // al, ah, bl, bh, cl, ch, dl, dh

conv.bSize( <constant> ); // Must fit into eight bits

Because conv.bSize passes its input parameter in the AL register, any form of the high-level calling sequence except "conv.bSize( al );" will automatically generate an instruction of the form "mov(<operand>,al);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the AL register and pass AL as the parameter to conv.bSize.

HLA low-level calling sequence examples:

mov( byteVariable, al );

call conv.bSize;

mov( <byte register>, al ); // ah, bl, bh, cl, ch, dl, dh

call conv.bSize;

mov( <constant>, al );

call conv.bSize;

procedure conv.wSize( w:word in ax ); @returns( "eax" );

This function always returns 4 because the "natural" size of a word is four hexadecimal digits (four 4-bit nibbles).

HLA high-level calling sequence examples:

conv.wSize( wordVariable );

conv.wSize( <word register> ); // ax, bx, cx, dx, bp, sp, si, di

conv.wSize( <constant> ); // Must fit into 16 bits

Because conv.wSize passes its input parameter in the AX register, any form of the high-level calling sequence except "conv.wSize( ax );" will automatically generate an instruction of the form "mov(<operand>,ax);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the AX register and pass AX as the parameter to conv.wSize.

HLA low-level calling sequence examples:

mov( wordVariable, ax );

call conv.wSize;

mov( <word register>, ax ); // bx, cx, dx, bp, sp, si, di

call conv.wSize;

mov( <constant>, ax );

call conv.wSize;

procedure conv.dSize( d:dword in eax ); @returns( "eax" );

This function returns 8 if the internal underscores flag is false, 9 if it is true, because the "natural" size of a double word is eight hexadecimal digits (eight 4-bit nibbles).

HLA high-level calling sequence examples:

conv.dSize( dwordVariable );

conv.dSize( <dword register> ); // eax, ebx, ecx, edx,

//ebp, esp, esi, edi

conv.dSize( <constant> ); // Must fit into 32 bits

Because conv.dSize passes its input parameter in the EAX register, any form of the high-level calling sequence except "conv.dSize( eax );" will automatically generate an instruction of the form "mov(<operand>,eax);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the EAX register and pass EAX as the parameter to conv.dSize.

HLA low-level calling sequence examples:

mov( dwordVariable, eax );

call conv.dSize;

mov( <dword register>, eax ); // ebx, ecx, edx, ebp, esp, esi, edi

call conv.dSize;

mov( <constant>, eax );

call conv.dSize;

procedure conv.qSize( q:qword ); @returns( "eax" );

This function returns 16 if the internal underscores flag is false, 19 if it is true, because the "natural" size of a quad word is 16 hexadecimal digits (16 4-bit nibbles) and there are four groups of four digits with underscores between them (if the underscores flag contains true).

HLA high-level calling sequence examples:

conv.qSize( qwordVariable );

conv.qSize( <constant> ); // Must fit into 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable

push( (type dword qwordVar[4]) ); // Push H.O. dword first

push( (type dword qwordVar[0]) ); // Push L.O. dword second

call conv.qSize;

// Example where 64-bit value is held in EDX:EAX

push( edx ); // Push H.O. dword first

push( eax ); // Push L.O. dword second

call conv.qSize;

// Passing a qword constant:

pushd( <qword constant> >> 32 ); // Push H.O. dword

pushd( <qword constant> & $FFFF_FFFF ); // Push L.O. dword

call conv.qSize;

procedure conv.tbSize( tb:tbyte ); @returns( "eax" );

This function returns 20 if the internal underscores flag is false, 24 if it is true, because the "natural" size of a ten-byte word is 20 hexadecimal digits (20 4-bit nibbles) and there are five groups of four digits with underscores between them (if the underscores flag contains true).

HLA high-level calling sequence examples:

conv.tbSize( tbyteVariable );

conv.tbSize( <constant> ); // Must fit into 80 bits

HLA low-level calling sequence examples:

// Passing a tbyte variable

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVar[8]) ); // Push H.O. word

push( (type dword tbyteVar[4]) ); // Push middle dword second

push( (type dword tbyteVar[0]) ); // Push L.O. dword third

call conv.tbSize;

// Passing a tbyte constant:

pushw( 0 ); // Must pad to 12 bytes.

pushw( <tbyte constant> >> 64 ); // Push H.O. word

pushd( (<tbyte constant> >> 32) & $FFFF_FFFF ); // Push middle dword

pushd( <tbyte constant> & $FFFF_FFFF ); // Push L.O. dword

call conv.tbSize;

procedure conv.lSize( l:lword ); @returns( "eax" );

This function returns 32 if the internal underscores flag is false, 39 if it is true, because the "natural" size of an lword is 32 hexadecimal digits (32 4-bit nibbles) and there are eight groups of four digits with underscores between them (if the underscores flag contains true).

HLA high-level calling sequence examples:

conv.lSize( lwordVariable );

conv.lSize( <constant> ); // Must fit into 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable

push( (type dword lwordVar[12])); // Push H.O. dword first

push( (type dword tbyteVar[8]) );

push( (type dword tbyteVar[4]) );

push( (type dword tbyteVar[0]) ); // Push L.O. dword last

call conv.lSize;

// Passing a lword constant:

pushd( <lword constant> >> 96 ); // Push H.O. dword first

pushw( (<lword constant> >> 64) & $FFFF_FFFF );

pushd( (<lword constant> >> 32) & $FFFF_FFFF );

pushd( <lword constant> & $FFFF_FFFF ); // Push L.O. dword last

call conv.lSize;

Standard Hexadecimal Size Functions

The h8Size, h16Size, h32Size, h64Size, h80Size, and h128Size routines compute the minimum number of output hexadecimal digits (with no leading zeros). These functions return a count that includes space for underscores if the internal underscores flag contains true (see conv.setUnderscores for details).

procedure conv.h8Size( b:byte in al ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value in AL to a string of hexadecimal digits. The return value is always 1 or 2 (as a single byte never consumes more than two hexadecimal digits). Note that the internal underscores flag setting does not affect the return result because the conversion routines never inject an underscore into a hexadecimal conversion unless there are at least five output digits.

HLA high-level calling sequence examples:

conv.h8Size( byteVariable );

conv.h8Size( <byte register> ); // al, ah, bl, bh, cl, ch, dl, dh

conv.h8Size( <constant> ); // Must fit into eight bits

Because conv.h8Size passes its input parameter in the AL register, any form of the high-level calling sequence except "conv.h8Size( al );" will automatically generate an instruction of the form "mov(<operand>,al);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the AL register and pass AL as the parameter to conv.h8Size.

HLA low-level calling sequence examples:

mov( byteVariable, al );

call conv.h8Size;

mov( <byte register>, al ); // ah, bl, bh, cl, ch, dl, dh

call conv.h8Size;

mov( <constant>, al );

call conv.h8Size;

procedure conv.h16Size( w:word in ax ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value in AX to a string of hexadecimal digits. The return value is always 1, 2, 3, or 4 (as a single word never requires more than four hexadecimal digits). Note that the internal underscores flag setting does not affect the return result because the conversion routines never inject an underscore into a hexadecimal conversion unless there are at least five output digits.

HLA high-level calling sequence examples:

conv.h16Size( wordVariable );

conv.h16Size( <word register> ); // ax, bx, cx, dx, bp, sp, si, di

conv.h16Size( <constant> ); // Must fit into 16 bits

Because conv.h16Size passes its input parameter in the AX register, any form of the high-level calling sequence except "conv.h16Size( ax );" will automatically generate an instruction of the form "mov(<operand>,ax);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the AX register and pass AX as the parameter to conv.h16Size.

HLA low-level calling sequence examples:

mov( wordVariable, ax );

call conv.h16Size;

mov( <word register>, ax ); // bx, cx, dx, bp, sp, si, di

call conv.h16Size;

mov( <constant>, ax );

call conv.h16Size;

procedure conv.h32Size( s:dword in eax ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value in EAX to a string of hexadecimal digits. The return value is always in the range 1-8 if the internal underscores flag is false, it is in the range 1-9 if the internal underscores flag is true (see the discussion of conv.setUnderscores for details).

HLA high-level calling sequence examples:

conv.h32Size( dwordVariable );

conv.h32Size( <dword register> ); // eax, ebx, ecx, edx,

//ebp, esp, esi, edi

conv.h32Size( <constant> ); // Must fit into 32 bits

Because conv.h32Size passes its input parameter in the EAX register, any form of the high-level calling sequence except "conv.h32Size( eax );" will automatically generate an instruction of the form "mov(<operand>,eax);". Therefore, if at all possible, you should try to have the value whose size you wish to compute already sitting in the EAX register and pass EAX as the parameter to conv.h32Size.

HLA low-level calling sequence examples:

mov( dwordVariable, eax );

call conv.h32Size;

mov( <dword register>, eax ); // ebx, ecx, edx, ebp, esp, esi, edi

call conv.h32Size;

mov( <constant>, eax );

call conv.h32Size;

procedure conv.h64Size( q:qword ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value passed in q to a string of hexadecimal digits. The return value is always in the range 1-16 if the internal underscores flag is false, it is in the range 1-19 if the internal underscores flag is true (see the discussion of conv.setUnderscores for details).

HLA high-level calling sequence examples:

conv.h64Size( qwordVariable );

conv.h64Size( <constant> ); // Must fit into 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable

push( (type dword qwordVar[4]) ); // Push H.O. dword first

push( (type dword qwordVar[0]) ); // Push L.O. dword second

call conv.h64Size;

// Example where 64-bit value is held in EDX:EAX

push( edx ); // Push H.O. dword first

push( eax ); // Push L.O. dword second

call conv.h64Size;

// Passing a qword constant:

pushd( <qword constant> >> 32 ); // Push H.O. dword

pushd( <qword constant> & $FFFF_FFFF ); // Push L.O. dword

call conv.h64Size;

procedure conv.h80Size( tb:tbyte ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value passed in tb to a string of hexadecimal digits. The return value is always in the range 1-20 if the internal underscores flag is false, it is in the range 1-24 if the internal underscores flag is true (see the discussion of conv.setUnderscores for details).

HLA high-level calling sequence examples:

conv.h80Size( tbyteVariable );

conv.h80Size( <constant> ); // Must fit into 80 bits

HLA low-level calling sequence examples:

// Passing a tbyte variable

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVar[8]) ); // Push H.O. word

push( (type dword tbyteVar[4]) ); // Push middle dword second

push( (type dword tbyteVar[0]) ); // Push L.O. dword third

call conv.h80Size;

// Passing a tbyte constant:

pushw( 0 ); // Must pad to 12 bytes.

pushw( <tbyte constant> >> 64 ); // Push H.O. word

pushd( (<tbyte constant> >> 32) & $FFFF_FFFF ); // Push middle dword

pushd( <tbyte constant> & $FFFF_FFFF ); // Push L.O. dword

call conv.h80Size;

procedure conv.h128Size( l:lword ); @returns( "eax" );

This function returns the number of print positions required by the conversion of the value passed in l to a string of hexadecimal digits. The return value is always in the range 1-32 if the internal underscores flag is false, it is in the range 1-39 if the internal underscores flag is true (see the discussion of conv.setUnderscores for details).

HLA high-level calling sequence examples:

conv.h128Size( lwordVariable );

conv.h128Size( <constant> ); // Must fit into 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable

push( (type dword lwordVar[12])); // Push H.O. dword first

push( (type dword tbyteVar[8]) );

push( (type dword tbyteVar[4]) );

push( (type dword tbyteVar[0]) ); // Push L.O. dword last

call conv.h128Size;

// Passing a lword constant:

pushd( <lword constant> >> 96 ); // Push H.O. dword first

pushw( (<lword constant> >> 64) & $FFFF_FFFF );

pushd( (<lword constant> >> 32) & $FFFF_FFFF );

pushd( <lword constant> & $FFFF_FFFF ); // Push L.O. dword last

call conv.h128Size;

Hexadecimal Numeric to Buffer Conversions

The hexadecimal numeric to buffer conversion routines translate a numeric value to a sequence of hexadecimal characters and store those characters into memory starting at the address pointed at by the EDI register. After the conversion, the EDI register points at the first byte in memory beyond the sequence of characters these routines produce. With successive calls to these routines (or any routine that emits characters to the buffer at which EDI points) you can build up larger strings.

If the internal underscores flag is true, these routines will emit an underscore between each group of four hexadecimal digits.

Fixed Length Hexadecimal Numeric to Buffer Conversions

The fixed length hexadecimal to buffer conversion routines translate an input numeric value to a fixed-length string (depending on the data type size and the setting of the internal underscores flag). These functions emit the characters of the string (including leading zeros, as necessary) to sequential locations starting at the address held in EDI.

procedure conv.bToBuf( b:byte in al; var buffer:var in edi );

Converts the numeric value in AL to a sequence of exactly two hexadecimal digits (including a leading zero if the value is in the range $0-$f) and stores these two characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. Because the conversion is always less than five digits, the internal underscores flag does not affect the output this function produces.

HLA high-level calling sequence examples:

// The following will load "byteVariable" into AL and

// the address of "charArrayVariable" into EDI and then

// call conv.bToBuf:

conv.bToBuf( byteVariable, charArrayVariable );

// The following call will copy BH into AL and

// EDX into EDI prior to calling conv.bToBuf:

conv.bToBuf( bh, [edx] );

// The following just calls conv.bToBuf as AL and EDI

// already hold the parameter values:

conv.bToBuf( al, [edi] );

// The following loads the constant in AL and calls

// conv.bToBuf:

conv.bToBuf( <constant>, [edi] ); // <constant> must fit in 8 bits

When using the HLA high-level calling form, always keep in mind that these statements load the AL and EDI registers with their respective parameter values. In particular, you should not specify [EAX] as the buffer address because the code that HLA generates can overwrite the L.O. byte of EAX (i.e., AL) before it copies the address to the EDI register. It goes without saying that this function will overwrite the values of EAX and EDI if the original parameters are not AL and [EDI].

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable:

mov( byteVariable, al );

lea( edi, charArrayVariable );

call conv.bToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( byteVariable, al );

mov( &charArrayVariable, edi );

call conv.bToBuf;

// Passing a pair of registers (that are not

// AL and EDI):

mov( bh, al );

mov( edx, edi );

call conv.bToBuf;

// Passing a constant:

mov( <constant>, al );

call conv.bToBuf; // Assume EDI already contains buffer address.

procedure conv.wToBuf( w:word in ax; var buffer:var in edi );

Converts the numeric value in AX to a sequence of exactly four hexadecimal digits (including leading zeros, as necessary) and stores these four characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. Because the conversion is always less than five digits, the internal underscores flag does not affect the output this function produces.

HLA high-level calling sequence examples:

// The following will load "wordVariable" into AX and

// the address of "charArrayVariable" into EDI and then

// call conv.wToBuf:

conv.wToBuf( wordVariable, charArrayVariable );

// The following call will copy BX into AX and

// EDX into EDI prior to calling conv.wToBuf:

conv.wToBuf( bx, [edx] );

// The following just calls conv.wToBuf as AX and EDI

// already hold the parameter values:

conv.wToBuf( ax, [edi] );

// The following loads the constant in AX and calls

// conv.wToBuf:

conv.wToBuf( <constant>, [edi] ); // <constant> must fit in 16 bits

When using the HLA high-level calling form, always keep in mind that these statements load the AX and EDI registers with their respective parameter values. In particular, you should not specify [EAX] as the buffer address because the code that HLA generates can overwrite the L.O. word of EAX (i.e., AX) before it copies the address to the EDI register. It goes without saying that this function will overwrite the values of EAX and EDI if the original parameters are not AX and [EDI].

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable:

mov( wordVariable, ax );

lea( edi, charArrayVariable );

call conv.wToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( wordVariable, ax );

mov( &charArrayVariable, edi );

call conv.wToBuf;

// Passing a pair of registers (that are not

// AX and EDI):

mov( bx, ax );

mov( edx, edi );

call conv.wToBuf;

// Passing a constant:

mov( <constant>, ax );

call conv.wToBuf; // Assume EDI already contains buffer address.

procedure conv.dToBuf( d:dword in eax; var buffer:var in edi );

Converts the numeric value in EAX to a sequence of exactly eight hexadecimal digits (including leading zeros, as necessary) and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. If the internal underscores flag contains true, this function will emit a nine-character string with a single underscore between the fourth and fifth digits.

HLA high-level calling sequence examples:

// The following will load "dwordVariable" into EAX and

// the address of "charArrayVariable" into EDI and then

// call conv.dToBuf:

conv.dToBuf( dwordVariable, charArrayVariable );

// The following call will copy EBX into EAX and

// EDX into EDI prior to calling conv.dToBuf:

conv.dToBuf( ebx, [edx] );

// The following just calls conv.dToBuf as EAX and EDI

// already hold the parameter values:

conv.dToBuf( eax, [edi] );

// The following loads the constant in EAX and calls

// conv.dToBuf:

conv.dToBuf( <constant>, [edi] ); // <constant> must fit in 32 bits

When using the HLA high-level calling form, always keep in mind that these statements load the EAX and EDI registers with their respective parameter values. In particular, you should not specify [EAX] as the buffer address because the code that HLA generates can overwrite EAX before it copies the address to the EDI register. It goes without saying that this function will overwrite the values of EAX and EDI if the original parameters are not EAX and [EDI].

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

mov( dwordVariable, eax );

lea( edi, charArrayVariable );

call conv.dToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( dwordVariable, eax );

mov( &charArrayVariable, edi );

call conv.dToBuf;

// Passing a pair of registers (that are not

// EAX and EDI):

mov( ebx, eax );

mov( edx, edi );

call conv.dToBuf;

// Passing a constant:

mov( <constant>, eax );

call conv.dToBuf; // Assume EDI already contains buffer address.

procedure conv.qToBuf( q:qword; var buffer:var in edi );

Converts the numeric value passed in q to a sequence of exactly 16 hexadecimal digits (including leading zeros, as necessary) and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. If the internal underscores flag contains true, this function will emit a 19-character string with underscores between the 4th and 5th, 8th and 9th, and 12th and 13th digits.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.qToBuf:

conv.qToBuf( qwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.qToBuf:

conv.qToBuf( <constant>, [edi] ); // <constant> must fit in 64 bits

When using the HLA high-level calling form, always keep in mind that these statements load the EDI register with the respective parameter value. It goes without saying that this function will overwrite the value of EDI if the original parameter is not [EDI].

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.qToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.qToBuf;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.qToBuf; // Assume EDI already contains buffer address.

procedure conv.tbToBuf( tb:tbyte; var buffer:var in edi );

Converts the numeric value passed in tb to a sequence of exactly 20 hexadecimal digits (including leading zeros, as necessary) and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. If the internal underscores flag contains true, this function will emit a 24-character string with underscores between the 4th and 5th, 8th and 9th, 12th and 13th , and 16th and 17th digits.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.tbToBuf:

conv.tbToBuf( tbyteVariable, charArrayVariable );

HLA low-level calling sequence examples:

// Passing a tbyte variable and a buffer variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.tbToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.tbToBuf;

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.tbToBuf; // Assume EDI already contains buffer address.

procedure conv.lToBuf( l:lword; var buffer:var in edi );

Converts the numeric value passed in l to a sequence of exactly 32 hexadecimal digits (including leading zeros, as necessary) and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. If the internal underscores flag contains true, this function will emit a 39 character string with underscores between the 4th and 5th, 8th and 9th, 12th and 13th , 16th and 17th, 20th and 21st, 24th and 25th, and 28th and 29th digits.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.lToBuf:

conv.lToBuf( lwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.lToBuf:

conv.lToBuf( <constant>, [edi] ); // <constant> must fit in 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable and a buffer variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.lToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.lToBuf;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.lToBuf; // Assume EDI already contains buffer address.

Variable Length Hexadecimal Numeric to Buffer Conversions

The variable length hexadecimal to buffer conversion routines translate an input numeric value to a variable-length string (depending on the value, data type size, and the setting of the internal underscores flag). These functions emit the characters of the string (without leading zeros) to sequential locations starting at the address held in EDI.

procedure conv.h8ToBuf( b:byte in al; var buffer:var in edi );

Converts the numeric value in AL to a sequence of one or two hexadecimal digits and stores these two characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. Because the conversion is always less than five digits, the internal underscores flag does not affect the output this function produces.

HLA high-level calling sequence examples:

// The following will load "byteVariable" into AL and

// the address of "charArrayVariable" into EDI and then

// call conv.h8ToBuf:

conv.h8ToBuf( byteVariable, charArrayVariable );

// The following call will copy BH into AL and

// EDX into EDI prior to calling conv.h8ToBuf:

conv.h8ToBuf( bh, [edx] );

// The following just calls conv.h8ToBuf as AL and EDI

// already hold the parameter values:

conv.h8ToBuf( al, [edi] );

// The following loads the constant in AL and calls

// conv.h8ToBuf:

conv.h8ToBuf( <constant>, [edi] ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable:

mov( byteVariable, al );

lea( edi, charArrayVariable );

call conv.h8ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( byteVariable, al );

mov( &charArrayVariable, edi );

call conv.h8ToBuf;

// Passing a pair of registers (that are not

// AL and EDI):

mov( bh, al );

mov( edx, edi );

call conv.h8ToBuf;

// Passing a constant:

mov( <constant>, al );

call conv.h8ToBuf; // Assume EDI already contains buffer address.

procedure conv.h16ToBuf( w:word in ax; var buffer:var in edi );

Converts the numeric value in AX to a sequence of one to four hexadecimal digits and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. Because the conversion is always less than five digits, the internal underscores flag does not affect the output this function produces.

HLA high-level calling sequence examples:

// The following will load "wordVariable" into AX and

// the address of "charArrayVariable" into EDI and then

// call conv.h16ToBuf:

conv.h16ToBuf( wordVariable, charArrayVariable );

// The following call will copy BX into AX and

// EDX into EDI prior to calling conv.h16ToBuf:

conv.h16ToBuf( bx, [edx] );

// The following just calls conv.h16ToBuf as AX and EDI

// already hold the parameter values:

conv.h16ToBuf( ax, [edi] );

// The following loads the constant in AX and calls

// conv.h16ToBuf:

conv.h16ToBuf( <constant>, [edi] ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable:

mov( wordVariable, ax );

lea( edi, charArrayVariable );

call conv.h16ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( wordVariable, ax );

mov( &charArrayVariable, edi );

call conv.h16ToBuf;

// Passing a pair of registers (that are not

// AX and EDI):

mov( bx, ax );

mov( edx, edi );

call conv.h16ToBuf;

// Passing a constant:

mov( <constant>, ax );

call conv.h16ToBuf; // Assume EDI already contains buffer address.

procedure conv.h32ToBuf( d:dword in eax; var buffer:var in edi );

Converts the numeric value in EAX to a sequence of one to eight hexadecimal digits and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence. If the internal underscores flag contains true and the value is $1_0000 or greater, then this function will emit an underscore between the fourth and fifth digits in the output string.

HLA high-level calling sequence examples:

// The following will load "dwordVariable" into EAX and

// the address of "charArrayVariable" into EDI and then

// call conv.h32ToBuf:

conv.h32ToBuf( dwordVariable, charArrayVariable );

// The following call will copy EBX into EAX and

// EDX into EDI prior to calling conv.h32ToBuf:

conv.h32ToBuf( ebx, [edx] );

// The following just calls conv.h32ToBuf as EAX and EDI

// already hold the parameter values:

conv.h32ToBuf( eax, [edi] );

// The following loads the constant in EAX and calls

// conv.h32ToBuf:

conv.h32ToBuf( <constant>, [edi] ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

mov( dwordVariable, eax );

lea( edi, charArrayVariable );

call conv.h32ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( dwordVariable, eax );

mov( &charArrayVariable, edi );

call conv.h32ToBuf;

// Passing a pair of registers (that are not

// EAX and EDI):

mov( ebx, eax );

mov( edx, edi );

call conv.h32ToBuf;

// Passing a constant:

mov( <constant>, eax );

call conv.h32ToBuf; // Assume EDI already contains buffer address.

procedure conv.h64ToBuf( q:qword; var buffer:var in edi );

Converts the numeric value in q to a sequence of 1 to 16 hexadecimal digits and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence.

If the internal underscores flag contains true and the value is $1_0000 or greater, then this function will emit an underscore between the 4th and 5th digits in the output string.

If the value is $1_0000 or greater, then this function will emit an underscore between the 4th and 5th digits in the output string.

If the value is $1_0000_0000 or greater, then this function will emit an underscore between the 8th and 9th digits.

If the value is $1_0000_0000_0000 or greater, then this function will emit an underscore between the 12th and 13th digits.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.h64ToBuf:

conv.h64ToBuf( qwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.h64ToBuf:

conv.h64ToBuf( <constant>, [edi] ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.h64ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.h64ToBuf;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.h64ToBuf; // Assume EDI already contains buffer address.

procedure conv.h80ToBuf( tb:tbyte; var buffer:var in edi );

Converts the numeric value in tb to a sequence of 1 to 20 hexadecimal digits and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence.

If the internal underscores flag contains true, and:

If the value is $1_0000 or greater, then this function will emit an underscore between the 4th and 5th digits in the output string.

If the value is $1_0000_0000 or greater, then this function will emit an underscore between the 8th and 9th digits.

If the value is $1_0000_0000_0000 or greater, then this function will emit an underscore between the 12th and 13th digits.

If the value is $1_0000_0000_0000_0000 or greater, then this function will emit an underscore between the 16th and 17th digits.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.h80ToBuf:

conv.h80ToBuf( tbyteVariable, charArrayVariable );

HLA low-level calling sequence examples:

// Passing a tbyte variable and a buffer variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.h80ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.h80ToBuf;

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.tbToBuf; // Assume EDI already contains buffer address.

procedure conv.h128ToBuf( l:lword; var buffer:var in edi );

Converts the numeric value in l to a sequence of 1 to 32 hexadecimal digits and stores these characters at the location pointed at by EDI. This function returns EDI pointing at the first byte after the sequence.

If the internal underscores flag contains true, and:

If the value is $1_0000 or greater, then this function will emit an underscore between the 4th and 5th digits in the output string.

If the value is $1_0000_0000 or greater, then this function will emit an underscore between the 8th and 9th digits.

If the value is $1_0000_0000_0000 or greater, then this function will emit an underscore between the 12th and 13th digits.

If the value is $1_0000_0000_0000_0000 or greater, then this function will emit an underscore between the 16th and 17th digits.

If the value is $1_0000_0000_0000_0000_0000 or greater, then this function will emit an underscore between the 20th and 21st digits.

If the value is $1_0000_0000_0000_0000_0000_0000 or greater, then this function will emit an underscore between the 24th and 25th digits.

If the value is $1_0000_0000_0000_0000_0000_0000_0000 or greater, then this function will emit an underscore between the 28th and 29th digits.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.h128ToBuf:

conv.h128ToBuf( lwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.h128ToBuf:

conv.h128ToBuf( <constant>, [edi] ); // <constant> must fit in 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable and a buffer variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.h128ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.h128ToBuf;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.h128ToBuf; // Assume EDI already contains buffer address.

Hexadecimal Numeric to String Conversions

The hexadecimal numeric to string conversion routines are the general-purpose hexadecimal string conversion routines. There are two versions: one set of these routines store their string data into a preallocated string object (the unadorned versions), the other set (adorned with an "a_" prefix in their name) allocates storage for a new string on the heap and returns a pointer to that new string in the EAX register.

As for the buffer routines (e.g., conv.bToBuf and conv.h8ToBuf) there are two categories of routines based on whether the routines emit a mimimum length string or pad the string with leading zeros to the data type’s natural size. The conv.hXToStr routines emit the minimum number of hexadecimal digits in the string they create.

The conv.XToStr (X= b, w, d, q, tb, or l) functions always create a fixed length string with an appropriate number of leading zeros (b=2 digits, w=4 digits, d=8 digits, q=16 digits, tb=20 digits, and l=32 digits). If the internal underscores flag contains true, then these functions will emit an underscore between each group of four hexadecimal digits.

The conv.hXToStr functions (X=8, 16, 32,64, 80, or 128) let you specify a minimum field width and a padding character (because the conv.XToBuf routines always emit fixed-length strings, there is no need to specify a minimum field width or padding character for those strings). The absolute value of the width parameter specifies the minimum string length for the conversion. The conversion will always produce a string at least abs(width) characters long. If the conversion would require more than abs(width) print positions, then the conversion will produce a larger string, as necessary.

If the string conversion requires fewer than abs(width) characters and the width parameter is a non-negative value, these routines right justify the value in the string and pad the remaining positions with the fill character. If the conversion requires fewer than abs(width) characters and the width parameter is a negative number, then these functions will left-justify the value in the output field and pad the end of the string with the fill character.

For the unadorned functions, the destination string’s maximum length must be large enough to hold the full result (including any extra print positions needed beyond the value specified by abs(width)) or these functions will raise a string overflow exception.

If the internal underscore flag is true, then the 32-bit and larger hex to string conversion functions will emit an underscore between each set of four hexadecimal digits, starting from the least significant digit. This is true for both the conv.hXToStr and conv.XToStr routines. See the descriptions of the conv.setUnderscores and conv.getUnderscores functions for more details. Note that the hexadecimal to numeric conversion functions do not inject underscores into sequences of padding characters, only into the actual digits the conversion produces. This is true even if you specify a numeric character (such as ‘0’) as the padding character.

Fixed-Length Numeric to Hexadecimal String Conversions

The functions in this category convert an 8-bit, 16-bit, 32-bit, 64-bit, 80-bit, or 128-bit numeric value to fixed-length strings (one hexadecimal digit for each four bits, including leading zeros). If the internal underscores flag contains true, then these functions will also insert an underscore between each group of four hexadecimal digits.

conv.bToStr( b:byte; dest:string );

This function converts the 8-bit value of the b parameter to a two-byte string containing b’s hexadecimal representation. Because this conversion requires exactly two digits, the internal underscores flag setting does not affect the operation of this function. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.bToStr:

conv.bToStr( byteVariable, destStr );

// The following call will BH’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.bToStr:

conv.bToStr( bh, edx );

// The following pushes the constant and destStr and calls

// conv.bToStr:

conv.bToBuf( <constant>, destStr ); // <constant> must fit in 8 bits

When using the HLA high-level calling form, remember that string variables are dword pointers that contain the address of a string object. The destination string parameter is passed by value, not by reference; it just turns out that the value of a string is a pointer to the actual string data (confusing, isn’t it?). In any case, this is why you can pass a register value as the destination string location rather than having to pass something like "[edx]". A construct like "[edx]" would imply that EDX contains the address of the string variable, that is, a pointer to the pointer to the string.

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.bToStr;

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

push( destStr );

call conv.bToStr;

// Passing a byte variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

push( destStr );

call conv.bToStr;

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

push( edx );

call conv.bToStr;

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

push( edx );

call conv.bToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.bToStr;

conv.a_bToStr( b:byte ); @returns( "eax" );

This function converts the value of the b parameter to a two-byte string containing b’s hexadecimal representation. Because this conversion requires exactly two digits, the internal underscores flag setting does not affect the operation of this function. This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and then call conv.a_bToStr:

conv.a_bToStr( byteVariable );

mov( eax, byteStr );

// The following call will BH’s value onto the stack

// before calling conv.a_bToStr:

conv.a_bToStr( bh );

mov( eax, byteStr );

// The following pushes the constant and calls

// conv.a_bToStr:

conv.bToBuf( <constant> ); // <constant> must fit in 8 bits

mov( eax, byteStr );

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

call conv.a_bToStr;

mov( eax, destStr );

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

call conv.a_bToStr;

mov( eax, destStr );

// Passing a byte variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

call conv.a_bToStr;

mov( eax, destStr );

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

call conv.a_bToStr;

mov( eax, byteStr );

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

call conv.a_bToStr;

mov( eax, byteStr );

// Passing a constant:

pushd( <constant> );

call conv.a_bToStr;

mov( eax, byteStr );

conv.wToStr( w:word; dest:string );

Converts the 16-bit value of the w parameter to a four-byte string that is the hexadecimal representation of this value. Because this conversions requires exactly four digits, the internal underscores flag setting does not affect the operation of this function. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "wordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.wToStr:

conv.wToStr( wordVariable, destStr );

// The following call will BX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.wToStr:

conv.wToStr( bx, edx );

// The following pushes the constant and destStr and calls

// conv.wToStr:

conv.wToStr( <constant>, destStr ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.wToStr;

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

push( destStr );

call conv.wToStr;

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

push( destStr );

call conv.wToStr;

// Passing a pair of registers:

// BX = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BX

push( edx );

call conv.wToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.wToStr;

conv.a_wToStr( w:word; dest:string ); @returns( "eax" );

Converts the 16-bit value of the w parameter to a four-byte string that is the hexadecimal representation of this value. Because this conversions requires exactly four digits, the internal underscores flag setting does not affect the operation of this function. This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push "wordVariable" and then call conv.wToStr:

conv.a_wToStr( wordVariable );

mov( eax, destStr );

// The following call will BX’s value onto the stack

// before calling conv.a_wToStr:

conv.a_wToStr( bx );

// The following pushes the constant and calls

// conv.a_wToStr:

conv.a_wToStr( <constant>, destStr ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( wordVariable, eax );

push( eax );

call conv.a_wToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

call conv.wToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

call conv.wToStr;

mov( eax, destStr );

// Passing a pair of registers:

// BX = value to print.

push( ebx ); // Pushes BX

call conv.wToStr;

mov( eax, wordStr );

// Passing a constant:

pushd( <constant> );

call conv.wToStr;

mov( eax, destStr );

conv.dToStr( d:dword; dest:string );

This function converts the 32-bit value of the d parameter to an eight- or nine-byte string that is the hexadecimal representation of this value. If d’s value is greater than $FFFF and the underscores flag is true, then this function emits a nine-character string with an underscore between the fourth and fifth digits (counting from the least signficant digit). This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.dToStr:

conv.dToStr( dwordVariable, destStr );

// The following call will EBX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.dToStr:

conv.dToStr( ebx, edx );

// The following pushes the constant and destStr and calls

// conv.dToStr:

conv.dToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

push( dwordVariable );

push( destStr );

call conv.dToStr;

// Passing a pair of registers:

// EBX = value to print, EDX = pointer to string object.

push( ebx );

push( edx );

call conv.dToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.dToStr;

conv.a_dToStr( d:dword; dest:string ); @returns( "eax" );

Converts the 32-bit value of the d parameter to an eight- or nine-byte string that is the hexadecimal representation of this value. If d’s value is greater than $FFFF and the underscores flag is true, then this function emits a nine-character string with an underscore between the fourth and fifth digits (counting from the least signficant digit). This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and then call conv.a_dToStr:

conv.a_dToStr( dwordVariable );

mov( eax, destStr );

// The following call will push EBX’s value onto the stack

// before calling conv.a_dToStr:

conv.a_dToStr( ebx );

// The following pushes the constant and calls

// conv.a_dToStr:

conv.a_dToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable:

push( dwordVariable );

call conv.a_dToStr;

mov( eax, destStr );

// Passing a register:

// EBX = value to print.

push( ebx );

call conv.a_dToStr;

mov( eax, dwordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_dToStr;

mov( eax, destStr );

conv.qToStr( q:qword; dest:string );

Converts the 64-bit value of the q parameter to 16- or 19-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 19-character string). This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// and the value of the destStr string variable

// onto the stack and then call conv.qToStr:

conv.qToStr( qwordVariable, destStr );

// The following pushes the constant onto the stack along with

// the value held in the destStr variable and calls

// conv.qToStr:

conv.qToStr( <constant>, destStr ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.qToStr;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

push( destStr );

call conv.qToStr;

conv.a_qToStr( q:qword; dest:string ); @returns( "eax" );

Converts the 64-bit value of the q parameter to 16- or 19-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 19-character string). This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack and then call conv.a_qToStr:

conv.a_qToStr( qwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_qToStr:

conv.a_qToStr( <constant> ); // <constant> must fit in 64 bits

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a qword variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_qToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.a_qToStr;

mov( eax, destStr );

conv.tbToStr( tb:tbyte; dest:string );

Converts the 80-bit value of the d parameter to 20- or 24-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 24-character string). This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// and the value of destStr onto the stack

// and then call conv.tbToStr:

conv.tbToStr( tbyteVariable, destStr );

HLA low-level calling sequence examples:

// Passing a tbyte variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.tbToStr;

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( destStr );

call conv.tbToStr;

conv.a_tbToStr( tb:tbyte; dest:string ); @returns( "eax" );

Converts the 80-bit value of the d parameter to 20- or 24-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 24-character string). This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// onto the stack and then call conv.a_tbToStr:

conv.a_tbToStr( tbyteVariable );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a tbyte variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_tbToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_tbToStr;

mov( eax, destStr );

conv.lToStr( l:lword; dest:string );

Converts the 128-bit value of the l parameter to 32- or 19-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 39-character string). This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// and destStr onto the stack, and then call conv.lToStr:

conv.lToStr( lwordVariable, destStr );

// The following pushes the constant onto the stack and calls

// conv.lToStr:

conv.lToStr( <constant>, edx ); // EDX contains string pointer value.

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

push( destStr );

call conv.lToStr;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( edx ); // EDX contains string pointer value.

call conv.lToStr;

conv.a_lToStr( l:lword; dest:string ); @returns( "eax" );

Converts the 128-bit value of the l parameter to 32- or 19-byte string (based on the setting of the underscores flag) that is the hexadecimal representation of this value. If the internal underscores flag is true, then this function emits an underscore between each group of four hexadecimal digits (resulting in a 39-character string). This function allocates storage for the string on the heap and returns a pointer to that string in the EAX register.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, and then call conv.a_lToStr:

conv.a_lToStr( lwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_lToStr:

conv.a_lToStr( <constant> );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

call conv.a_lToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_lToStr;

mov( eax, destStr );

Variable-Length Numeric to Hexadecimal String Conversions

The functions in this category convert a numeric value (8, 16, 32, 64, 80, or 128 bits) to a variable-length hexadecimal string (with no leading zeros). The string will contain the minimum number of digits needed to represent the value (plus underscores between each group of four digits if the internal underscores flag contains true).

procedure conv.h8ToStr ( b:byte; width:int32; fill:char; buffer:string );

Converts the 8-bit value of the b parameter to a one or two-byte string that is the hexadecimal representation of this value. Because 8-bit hexadecimal conversions require no more than two digits, the internal underscores flag setting does not affect the operation of this function. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.h8ToStr:

conv.h8ToStr( byteVariable, destStr );

// The following call will BH’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.h8ToStr:

conv.h8ToStr( bh, edx );

// The following pushes the constant and destStr and calls

// conv.h8ToStr:

conv.h8ToBuf( <constant>, destStr ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.h8ToStr;

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

push( destStr );

call conv.h8ToStr;

// Passing a byte variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

push( destStr );

call conv.h8ToStr;

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

push( edx );

call conv.h8ToStr;

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

push( edx );

call conv.h8ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.h8ToStr;

procedure conv.a_h8ToStr( b:byte; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 8-bit value of the b parameter to a 1..2 byte string that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. Because the number of digits is always two or less, the internal underscores flag does not affect the string this function produces.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and then call conv.a_h8ToStr:

conv.a_h8ToStr( byteVariable );

mov( eax, byteStr );

// The following call will BH’s value onto the stack

// before calling conv.a_h8ToStr:

conv.a_h8ToStr( bh );

mov( eax, byteStr );

// The following pushes the constant and calls

// conv.a_h8ToStr:

conv.a_h8ToStr( <constant> ); // <constant> must fit in 8 bits

mov( eax, byteStr );

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

call conv.a_h8ToStr;

mov( eax, destStr );

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

call conv.a_h8ToStr;

mov( eax, destStr );

// Passing a byte variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

call conv.a_h8ToStr;

mov( eax, destStr );

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

call conv.a_h8ToStr;

mov( eax, byteStr );

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

call conv.a_h8ToStr;

mov( eax, byteStr );

// Passing a constant:

pushd( <constant> );

call conv.a_h8ToStr;

mov( eax, byteStr );

procedure conv.h16ToStr ( w:word; width:int32; fill:char; buffer:string );

Converts the 16-bit value of the w parameter to a 1..4 byte string that is the hexadecimal representation of this value. Because 16-bit hexadecimal conversions require no more than four digits, the internal underscores flag setting does not affect the operation of this function. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "wordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.h16ToStr:

conv.h16ToStr( wordVariable, destStr );

// The following call will BX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.h16ToStr:

conv.h16ToStr( bx, edx );

// The following pushes the constant and destStr and calls

// conv.h16ToStr:

conv.h16ToStr( <constant>, destStr ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.h16ToStr;

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

push( destStr );

call conv.h16ToStr;

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

push( destStr );

call conv.h16ToStr;

// Passing a pair of registers:

// BX = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BX

push( edx );

call conv.h16ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.h16ToStr;

procedure conv.a_h16ToStr( w:word; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 16-bit value of the w parameter to a 1..4 byte string that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. Because the number of digits is always four or less, the internal underscores flag does not affect the string this function produces.

HLA high-level calling sequence examples:

// The following will push "wordVariable" and call conv.a_h16ToStr:

conv.a_h16ToStr( wordVariable );

mov( eax, destStr );

// The following call will BX’s value onto the stack

// before calling conv.a_h16ToStr:

conv.a_h16ToStr( bx );

// The following pushes the constant and calls

// conv.a_h16ToStr:

conv.a_h16ToStr( <const>, destStr ); // <const> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( wordVariable, eax );

push( eax );

call conv.a_h16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

call conv.a_h16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

call conv.a_h16ToStr;

mov( eax, destStr );

// Passing a pair of registers:

// BX = value to print.

push( ebx ); // Pushes BX

call conv.a_h16ToStr;

mov( eax, wordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_h16ToStr;

mov( eax, destStr );

procedure conv.h32ToStr ( d:dword; width:int32; fill:char; buffer:string );

Converts the 32-bit value of the d parameter to a 1..8 byte string (1..9 bytes if the underscores flag is set) that is the hexadecimal representation of this value. If the 32-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert an underscore between the 4th and 5th digits of the string it produces. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.h32ToStr:

conv.h32ToStr( dwordVariable, destStr );

// The following call will push EBX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.h32ToStr:

conv.h32ToStr( ebx, edx );

// The following pushes the constant and destStr and calls

// conv.h32ToStr:

conv.h32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

push( dwordVariable );

push( destStr );

call conv.h32ToStr;

// Passing a pair of registers:

// EBX = value to print, EDX = pointer to string object.

push( ebx );

push( edx );

call conv.h32ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.h32ToStr;

procedure conv.a_h32ToStr( d:dword; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 32-bit value of the d parameter to a 1..8 byte string (1..9 bytes if the underscores flag is set) that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. If the 32-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces.

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and then call conv.a_h32ToStr:

conv.a_h32ToStr( dwordVariable );

mov( eax, destStr );

// The following call will push EBX’s value onto the stack

// before calling conv.a_h32ToStr:

conv.a_h32ToStr( ebx );

// The following pushes the constant and calls

// conv.a_h32ToStr:

conv.a_h32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable:

push( dwordVariable );

call conv.a_h32ToStr;

mov( eax, destStr );

// Passing a register:

// EBX = value to print.

push( ebx );

call conv.a_h32ToStr;

mov( eax, dwordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_h32ToStr;

mov( eax, destStr );

procedure conv.h64ToStr ( q:qword; width:int32; fill:char; buffer:string );

Converts the 64-bit value of the q parameter to a 1..16 byte string (1..19 bytes if the underscores flag is set) that is the hexadecimal representation of this value. If the 64-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// and the value of the destStr string variable

// onto the stack and then call conv.h64ToStr:

conv.h64ToStr( qwordVariable, destStr );

// The following pushes the constant onto the stack along with

// the value held in the destStr variable and calls

// conv.h64ToStr:

conv.h64ToStr( <constant>, destStr ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.h64ToStr;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

push( destStr );

call conv.h64ToStr;

procedure conv.a_h64ToStr( q:qword; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 64-bit value of the q parameter to a 1..16 byte string (1..19 bytes if the underscores flag is set) that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. If the 64-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack and then call conv.a_h64ToStr:

conv.a_h64ToStr( qwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_h64ToStr:

conv.a_h64ToStr( <constant> ); // <constant> must fit in 64 bits

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a qword variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_h64ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.a_h64ToStr;

mov( eax, destStr );

procedure conv.h80ToStr( tb:tbyte; width:int32; fill:char; buffer:string );

Converts the 80-bit value of the tb parameter to a 1..20 byte string (1..24 bytes if the underscores flag is set) that is the hexadecimal representation of this value. If the 80-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// and the value of destStr onto the stack

// and then call conv.h80ToStr:

conv.h80ToStr( tbyteVariable, destStr );

HLA low-level calling sequence examples:

// Passing a tbyte variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.h80ToStr;

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( destStr );

call conv.h80ToStr;

procedure conv.a_h80ToStr( tb:tbyte; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 80-bit value of the tb parameter to a 1..20 byte string (1..24 bytes if the underscores flag is set) that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. If the 80-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces.

HLA high-level calling sequence examples:

// The following will push the value of "tbyteVariable"

// onto the stack and then call conv.a_h80ToStr:

conv.a_h80ToStr( tbyteVariable );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a tbyte variable:

pushw( 0 ); // Must pad parameter to 12 bytes

push( (type word tbyteVariable[8])); // H.O. word first

push( (type dword tbyteVariable[4]));

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_h80ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 64 ); // Push H.O. word as dword, first

pushd( (<constant> >> 32) & $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_h80ToStr;

mov( eax, destStr );

procedure conv.h128ToStr ( l:lword; width:int32; fill:char; buffer:string );

Converts the 128-bit value of the l parameter to a 1..32 byte string (1..39 bytes if the underscores flag is set) that is the hexadecimal representation of this value. If the 128-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces. This function raises a string overflow error if the destination string is not large enough to hold the converted string.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// and destStr onto the stack, and then call conv.h128ToStr:

conv.h128ToStr( lwordVariable, destStr );

// The following pushes the constant onto the stack and calls

// conv.h128ToStr:

conv.h128ToStr( <constant>, edx ); // EDX contains string pointer value.

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

push( destStr );

call conv.h128ToStr;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( edx ); // EDX contains string pointer value.

call conv.h128ToStr;

conv.a_h128ToStr( l:lword; width:int32; fill:char );
@returns( "eax" );

Allocates an appropriate amount of string storage on the heap and then converts the 128-bit value of the l parameter to a 1..32 byte string (1..39 bytes if the underscores flag is set) that is the hexadecimal representation of this value. Returns a pointer to the newly allocated string in EAX. If the 128-bit value is greater than $FFFF and the internal underscores flag is true, then this function will insert underscores between each set of four digits to the left of the least significant digit in the string it produces.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, and then call conv.a_h128ToStr:

conv.a_h128ToStr( lwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_h128ToStr:

conv.a_h128ToStr( <constant> );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

call conv.a_h128ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_h128ToStr;

mov( eax, destStr );

Hexadecimal Buffer to Numeric Conversions

The hexadecimal buffer to numeric conversions ("ASCII to hexadecimal") convert a sequence of characters at some address in memory to numeric form.

These routines will skip over any leading underscore and delimiter characters (specified by the internal delimiters character set, see the discussion of conv.setDelimiters and conv.getDelimiters for details). These functions will convert all characters in the sequence until encountering a non-hexadecimal digit or underscore. If the first non-hex character is not the end of string or a delimiter character, these functions will raise a conversion exception. If the character is not a valid 7-bit ASCII character, these functions will raise an illegal character exception.

procedure conv.atoh8( var buffer:var in esi ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at character position held in ESI to an 8-bit numeric value. It raises an overflow exception if the value is outside the range $00..$FF. This function returns the result in AL, zero extended into EAX. This function returns ESI pointing at the first character after the sequence of hexadecimal characters.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AL:

conv.atoh8( [esi] );

mov( al, hexNumericResult );

// The following loads ESI with the address of

// a sequence of hexadecimal characters (held in an HLA

// string) and converts them to an 8-bit number:

conv.atoh8( sourceStr ); // Loads "sourceStr" into ESI

mov( al, byteVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoh8;

mov( al, hexNumericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoh8;

mov( al, hex12 );

procedure conv.atoh16( var buffer:var in esi ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at character position held in ESI to an 8-bit numeric value. It raises an overflow exception if the value is outside the range $0000..$FFFF. This function returns the result in AX, zero extended into EAX. This function returns ESI pointing at the first character after the sequence of hexadecimal characters.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AX:

conv.atoh16( [esi] );

mov( ax, hex16NumericResult );

// The following loads ESI with the address of

// a sequence of hexadecimal characters (held in an HLA

// string) and converts them to a 16-bit number:

conv.atoh16( sourceStr ); // Loads "sourceStr" into ESI

mov( ax, wordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoh16;

mov( ax, hex16NumericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoh16;

mov( ax, hex12 );

procedure conv.atoh32( var buffer:var in esi ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at character position held in ESI to an 8-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000..$FFFF_FFFF. This function returns the result in EAX. This function returns ESI pointing at the first character after the sequence of hexadecimal characters.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EAX:

conv.atoh32( [esi] );

mov( eax, hex32NumericResult );

// The following loads ESI with the address of

// a sequence of hexadecimal characters (held in an HLA

// string) and converts them to a 32-bit number:

conv.atoh32( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, dwordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoh32;

mov( eax, hex32NumericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoh32;

mov( eax, hex12 );

procedure conv.atoh64( var buffer:var in esi ); @returns( "edx:eax" );

This function converts the hexadecimal character sequence beginning at character position held in ESI to an 8-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000_0000_0000..$FFFF_FFFF_FFFF_FFFF. This function returns the result in EDX:EAX (H.O. double word in EDX). This function returns ESI pointing at the first character after the sequence of hexadecimal characters.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EDX:EAX:

conv.atoh64( [esi] );

mov( eax, (type dword hex64NumericResult[0]) );

mov( edx, (type dword hex64NumericResult[4]) );

// The following loads ESI with the address of

// a sequence of hexadecimal characters (held in an HLA

// string) and converts them to a 64-bit number:

conv.atoh64( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoh64;

mov( eax, (type dword hex64NumericResult[0]) );

mov( edx, (type dword hex64NumericResult[4]) );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoh64;

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

procedure conv.atoh128( var buffer:var in esi; var dest:lword );

This function converts the hexadecimal character sequence beginning at character position in the string to a 128-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000_0000_0000_0000_0000_0000_0000..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF. This function returns the result in the variable specified by the dest parameter.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and stores that value in lwordDest (passed by reference):

conv.atoh128( [esi], lwordDest );

// The following loads ESI with the address of

// a sequence of hexadecimal characters (held in an HLA

// string) and converts them to a 128-bit number that it

// stores in lwordDest:

conv.atoh128( sourceStr, lwordDest ); // Loads "sourceStr" into ESI

HLA low-level calling sequence examples:

// Option 1: lwordDest is a static object declared in a

// HLA STATIC, READONLY, or STORAGE section:

// As with the first example above, assume ESI already

// contains the address of the string to convert:

pushd( &lwordDest ); // Pass address of lwordDest as reference parm.

call conv.atoh128;

// Option 2: lwordDest is a simple automatic variable (no indexing)

// declared in a VAR section (or as a parameter). Assume that

// no 32-bit registers can be disturbed by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

push( ebp );

add( @offset( lwordDest ), (type dword [esp]));

call conv.atoh128;

// Option 3: lwordDest is a complex addressing mode and at least

// one 32-bit register is available for use by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

lea( eax, lwordDest ); // Assume EAX is the available register

push( eax );

call conv.atoh128;

// Same as second high-level example above. Assumes that

// lwordDest is a static object.

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

pushd( &lwordDest );

call conv.atoh128;

Hexadecimal String to Numeric Conversions

This functions convert a string value, that contain the hexadecimal representation of a number, into the numeric form. These functions have two parameters: a string object and an index into that string. Numeric conversion begins at the zero-based character position specified by the index parameter. For example, the invocation

conv.strToh8( someStr, 5 );

begins the conversion starting with the sixth character (index 5) in someStr. These functions will raise an "index out of range" exception if the supplied index is greater than the size of the string the first parameter specifies. They will return a null pointer reference exception if the string parameter is NULL (they will return an illegal memory access exception if the first parameter is not a valid pointer and references unpaged memory).

procedure conv.strToh8( s:string; index:dword ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at the indexth character position in the string to an 8-bit numeric value. It raises an overflow exception if the value is outside the range $00..$FF. This function returns the result in AL, zero extended into EAX.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "hexValueStr" to numeric form:

conv.strToh8( hexValueStr, 0 ); // Index=0 starts at beginning

mov( al, hexNumericResult );

// The following demonstrates using a non-zero index:

conv.strToh8( "abc12", 3 ); // "12" begins at offset 3

mov( al, hex12 );

HLA low-level calling sequence examples:

push( hexValueStr ); // Same as first example above

pushd( 0 );

call conv.strToh8;

mov( al, hexNumericResult );

// Same as second example above

static

str12 :string := "abc12";

push( str12 ); // Note that str12 points at "abc12".

pushd( 3 ); // Index to "12" in "abc12".

call conv.strToh8;

mov( al, hex12 );

procedure conv.strToh16( s:string; index:dword ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at the indexth character position in the string to a 16-bit numeric value. It raises an overflow exception if the value is outside the range $0000..$FFFF. This function returns the result in AX, zero extended into EAX.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "hexValueStr" to numeric form:

conv.strToh16( hexValueStr, 0 ); // Index=0 starts at beginning

mov( ax, wordVar );

// The following demonstrates using a non-zero index:

conv.strToh16( "abc12FF", 3 ); // "12FF" begins at offset 3

mov( ax, wordVar );

HLA low-level calling sequence examples:

push( hexValueStr ); // Same as first example above

pushd( 0 );

call conv.strToh16;

mov( ax, wordVar );

// Same as second example above

static

str12FF :string := "abc12FF";

push( str12FF ); // Note that str12FF points at "abc12FF".

pushd( 3 ); // Index to "12FF" in "abc12FF".

call conv.strToh16;

mov( ax, wordVar );

procedure conv.strToh32( s:string; index:dword ); @returns( "eax" );

This function converts the hexadecimal character sequence beginning at the indexth character position in the string to a 32-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000..$FFFF_FFFF. This function returns the result in EAX.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "hexValueStr" to numeric form:

conv.strToh32( hexValueStr, 0 ); // Index=0 starts at beginning

mov( eax, dwordVar );

// The following demonstrates using a non-zero index:

conv.strToh32( "abc12_FF00", 3 ); // "12_FF00" begins at offset 3

mov( eax, dwordVar );

HLA low-level calling sequence examples:

push( hexValueStr ); // Same as first example above

pushd( 0 );

call conv.strToh32;

mov( eax, dwordVar );

// Same as second example above

static

str12FF00 :string := "abc12_FF00";

push( str12FF00 ); // Note that str12FF00 points at "abc12_FF00".

pushd( 3 ); // Index to "12_FF00" in "abc12_FF00".

call conv.strToh32;

mov( eax, dwordVar ); // dwordVar now contains $12_FF00.

procedure conv.strToh64( s:string; index:dword ); @returns( "edx:eax" );

This function converts the hexadecimal character sequence beginning at the indexth character position in the string to a 64-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000_0000_0000..$FFFF_FFFF_FFFF_FFFF. This function returns the result in EDX:EAX (H.O. double word in EDX).

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "hexValueStr" to numeric form:

conv.strToh64( hexValueStr, 0 ); // Index=0 starts at beginning

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// The following demonstrates using a non-zero index:

conv.strToh64( "abc12", 1 ); // "bc12" begins at offset 1

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

HLA low-level calling sequence examples:

push( hexValueStr ); // Same as first example above

pushd( 0 );

call conv.strToh64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// Same as second example above

static

strabc12 :string := "abc12";

push( strabc12 ); // Note that strabc12 points at "abc12".

pushd( 1 ); // Index to "bc12" in "abc12".

call conv.strToh64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

procedure conv.strToh128( s:string; index:dword; var dest:lword );

This function converts the hexadecimal character sequence beginning at the indexth character position in the string to a 128-bit numeric value. It raises an overflow exception if the value is outside the range $0000_0000_0000_0000_0000_0000_0000_0000..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF. This function returns the result in the variable specified by the dest parameter.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "hexValueStr" (index=0) to numeric form and store the

// 128-bit result into the 1wordDest variable:

conv.strToh128( hexValueStr, 0, 1wordDest );

// The following demonstrates using a non-zero index:

conv.strToh128( "abc1234567890abcdef", 3, 1wordDest );

HLA low-level calling sequence examples:

// Option #1: lwordDest is a STATIC/READONLY/STORAGE

// variable:

push( hexValueStr ); // Same as first example above

pushd( 0 );

pushd( &lwordDest );

call conv.strToh128;

// Option #2: lwordDest is not a static object and

// a 32-bit register is available for use:

push( hexValueStr ); // Same as first example above

pushd( 0 );

lea( eax, lwordDest ); // Assuming EAX is available

push( eax );

call conv.strToh128;

// Option #3: lwordDest is an automatic (var) object and

// no 32-bit registers are available for use:

push( hexValueStr ); // Same as first example above

pushd( 0 );

push( ebp );

add( @offset( lwordDest ), (type dword [esp]) );

call conv.strToh128;

// Option #4: lwordDest is a complex addressing mode object and

// no 32-bit registers are available for use:

push( hexValueStr ); // Same as first example above

pushd( 0 );

sub( 4, esp );

push( eax );

lea( eax, lwordDest );

mov( eax, [esp+4] );

pop( eax );

call conv.strToh128;

Signed Integer Conversions

The integer conversion functions process signed integer values that are 8, 16, 32, 64, or 128 bits long. Functions in this category compute the output size (in print positions) of an integer, convert an integer to a sequence of characters, and convert a sequence of characters to an integer value.

Internal Functions

These functions are for internal use by the standard library. You should not call these functions in your own code. The internal functions in this category are conv._intToBuf32, conv._intToBuf32Size, conv._intToBuf64, conv._intToBuf64Size, conv._intToBuf128, conv._intToBuf128Size

Integer Size Calculations

These routines return the size, in screen print positions, it would take to print the signed integer passed in the specified parameter. They return their value in the EAX register (the value always fits in AL and AX, if you’d prefer to use these registes as the return value). The count includes room for a minus sign if the number is negative. Note that these routines include print positions required by underscores if you’ve enabled underscore output in values (see conv.setUnderscores and conv.getUnderscores for details).

procedure conv.i8Size( b:byte in al ); @returns( "eax" );

This function computes the number of print positions required by the 8-bit signed integer passed in the AL register. Because the number of decimal positions is always three or less, the internal underscores flag does not affect the value this function returns. This function will always return a value in the range 1..4 (e.g., four positions for a value like "-128").

HLA high-level calling sequence examples:

conv.i8Size( byteVariable );

mov( eax, numSize );

conv.i8Size( <byte register> ); // al, ah, bl, bh, cl, ch, dl, dh

mov( eax, int8Size );

conv.i8Size( <constant> ); // Must fit into eight bits

mov( al, constantsSize );

Because conv.i8Size passes its input parameter in the AL register, any form of the high-level calling sequence except "conv.i8Size( al );" will automatically generate an instruction of the form "mov(<operand>,al);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the AL register and pass AL as the parameter to conv.i8Size.

HLA low-level calling sequence examples:

mov( byteVariable, al );

call conv.i8Size;

mov( eax, numSize );

mov( <byte register>, al ); // ah, bl, bh, cl, ch, dl, dh

call conv.i8Size;

mov( ax, wordVariable );

// Explicit Examples:

mov( bh, al );

call conv.i8Size;

mov( al, bhSize );

call conv.i8Size; // Assume value is already in AL

mov( al, alSize );

mov( 123, al ); // Example of computing the size of a constant

call conv.i8Size;

mov( eax, constsSize );

It might seem silly to compute the size of a constant as this last example is doing, as the constant’s print width is known at compile time. Note, however, that this sequence could appear as part of a macro expansion and the literal constant "123" could actually be the result of expanding a macro parameter.

procedure conv.i16Size( w:word in ax ); @returns( "eax" );

This function computes the number of print positions required by the 16-bit signed integer passed in the AX register. If the internal underscores flag is set and the integer value is greater than 999 (or less than -999) then this function will account for the underscores injected by the integer to string conversion routines. This function will always return a value in the range 1..6 if the underscores flag is not set (e.g., "-12345") or a value in the range 1…7 if the internal underscores flag is set (e.g., "-12_345").

HLA high-level calling sequence examples:

conv.i16Size( wordVariable );

mov( eax, numSize );

conv.i16Size( <word register> ); // ax, bx, cx, dx, bp, sp, si, di

mov( eax, int16Size );

conv.i16Size( <constant> ); // Must fit into 16 bits

mov( al, constantsSize );

Because conv.i16Size passes its input parameter in the AX register, any form of the high-level calling sequence except "conv.i16Size( ax );" will automatically generate an instruction of the form "mov(<operand>,ax);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the AX register and pass AX as the parameter to conv.i16Size.

HLA low-level calling sequence examples:

mov( wordVariable, ax );

call conv.i16Size;

mov( eax, numSize );

mov( <word register>, ax ); // bx, cx, dx, bp, sp, si, or di

call conv.i16Size;

mov( ax, wordVariable );

// Explicit Examples:

mov( bx, ax );

call conv.i16Size;

mov( al, bxSize );

call conv.i16Size; // Assume value is already in AX

mov( al, axSize );

mov( 12345, ax ); // Example of computing the size of a constant

call conv.i16Size;

mov( eax, constsSize );

See the comment at the end of conv.i8Size about passing constants to these functions.

procedure conv.i32Size( d:dword in eax ); @returns( "eax" );

This function computes the number of print positions required by the 32-bit signed integer passed in the EAX register. If the internal underscores flag is set this function will include print positions for the underscores that the conversion routines will inject into the string. This function will always return a value in the range 1..11 if the underscores flag is not set (e.g., "-1000000000") or a value in the range 1…14 if the internal underscores flag is set (e.g., "-1_000_000_000").

HLA high-level calling sequence examples:

conv.i32Size( wordVariable );

mov( eax, numSize );

conv.i32Size( <dword register> ); // eax, ebx, ecx, edx,

mov( eax, int16Size )l // ebp, esp, esi, or edi

conv.i32Size( <constant> ); // Must fit into 32 bits

mov( al, constantsSize );

Because conv.i32Size passes its input parameter in the EAX register, any form of the high-level calling sequence except "conv.i32Size( eax );" will automatically generate an instruction of the form "mov(<operand>,eax);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the EAX register and pass EAX as the parameter to conv.i32Size.

HLA low-level calling sequence examples:

mov( dwordVariable, eax );

call conv.i32Size;

mov( eax, numSize );

mov( <dword register>, eax ); // ebx, ecx, edx,

call conv.i32Size; // ebp, esp, esi, or edi

mov( ax, wordVariable );

// Explicit Examples:

mov( ebx, eax );

call conv.i32Size;

mov( al, bxSize );

call conv.i32Size; // Assume value is already in AX

mov( al, axSize );

mov( 1234567890, eax ); // Example of computing

call conv.i32Size; // the size of a constant.

mov( eax, constsSize );

See the comment at the end of conv.i8Size about passing constants to these functions.

procedure conv.i64Size( q:qword ); @returns( "eax" );

This function computes the number of print positions required by the 64-bit signed integer passed on the stack. If the internal underscores flag is set this function will include print positions for the underscores that the conversion routines will inject into the string. This function will always return a value in the range 1..20 if the underscores flag is not set (e.g., "-9223372036854775807") or a value in the range 1..26 if the internal underscores flag is set (e.g., "-9_223_372_036_854_775_808").

HLA high-level calling sequence examples:

conv.i64Size( qwordVariable );

mov( eax, numSize );

conv.i64Size( <constant> ); // Must fit into 64 bits

mov( al, constantsSize );

HLA low-level calling sequence examples:

push( (type dword qwordVariable[4])); // Push H.O. dword first

push( (type dword qwordVariable[0])); // Push L.O. dword second

call conv.i64Size;

mov( eax, numSize );

// Compute the size of a 64-bit constant:

pushd( 12345 >> 32 ); // Push H.O. dword first

pushd( 12345 & $FFFF_FFFF ); // Push L.O. dword second

call conv.i64Size;

mov( eax, constsSize );

See the comment at the end of conv.i8Size about passing constants to these functions. If you make a habit of explicitly passing 64-bit constants to this function, you might consider writing a macro to push the 64-bit constant for you (see the chapter on "Passing Parameters to Standard Library Routines" for more details).

procedure conv.i128Size( l:lword ); @returns( "eax" );

This function computes the number of print positions required by the 128-bit signed integer passed in the EAX register. If the internal underscores flag is set this function will include print positions for the underscores that the conversion routines will inject into the string. This function will always return a value in the range 1..40 if the underscores flag is not set (e.g., "-170141183460469231731687303715884105727") or a value in the range 1…52 if the internal underscores flag is set (e.g., "-170_141_183_460_469_231_731_687_303_715_884_105_728").

HLA high-level calling sequence examples:

conv.i128Size( lwordVariable );

mov( eax, numSize );

conv.i128Size( <constant> ); // Must fit into 128 bits

mov( al, constantsSize );

HLA low-level calling sequence examples:

push( (type dword lwordVariable[12])); // Push H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // Push L.O. dword last

call conv.i64Size;

mov( eax, numSize );

// Compute the size of a 128-bit constant:

pushd( 12345 >> 96 ); // Push H.O. dword first

pushd( (12345 >> 64) & $FFFF_FFFF );

pushd( (12345 >> 32 ) & $FFFF_FFFF );

pushd( 12345 & $FFFF_FFFF ); // Push L.O. dword last

call conv.i128Size;

mov( eax, constsSize );

See the comment at the end of conv.i8Size about passing constants to these functions. If you make a habit of explicitly passing 128-bit constants to this function, you might consider writing a macro to push the 128-bit constant for you (see the chapter on "Passing Parameters to Standard Library Routines" for more details).

Signed Integer Numeric to Buffer Conversions

These routines convert the input parameter to a sequence of characters and store those characters starting at location [EDI]. They return EDI pointing at the first character beyond the converted string. Note that these functions do not zero terminate the string; if you want a zero-terminated string, then store a zero at the byte pointed at by EDI upon return from these functions.

If the internal underscores flag is set (see conv.getUnderscores and conv.setUnderscores for details), then these functions will insert an underscore between each group of three digits starting with the least significant digit.

procedure conv.i8ToBuf( i8 :int8 in al; var buf:var in edi );

This function converts the 8-bit signed integer passed in AL to a sequence of 1..4 characters. The string this function produces is always in the range -128..127. Note that because this string always contains three or fewer digits, the internal underscores flag setting does not affect this function’s output.

HLA high-level calling sequence examples:

// The following will load "byteVariable" into AL and

// the address of "charArrayVariable" into EDI and then

// call conv.i8ToBuf:

conv.i8ToBuf( byteVariable, charArrayVariable );

// The following call will copy BH into AL and

// EDX into EDI prior to calling conv.i8ToBuf:

conv.i8ToBuf( bh, [edx] );

// The following just calls conv.i8ToBuf as AL and EDI

// already hold the parameter values:

conv.i8ToBuf( al, [edi] );

// The following loads the constant in AL and calls

// conv.i8ToBuf:

conv.i8ToBuf( <constant>, [edi] ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable:

mov( byteVariable, al );

lea( edi, charArrayVariable );

call conv.i8ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( byteVariable, al );

mov( &charArrayVariable, edi );

call conv.i8ToBuf;

// Passing a pair of registers (that are not

// AL and EDI):

mov( bh, al );

mov( edx, edi );

call conv.i8ToBuf;

// Passing a constant:

mov( <constant>, al );

call conv.i8ToBuf; // Assume EDI already contains buffer address.

procedure conv.i16ToBuf( i16 :int16 in ax; var buf:var in edi )

This function converts the 16-bit signed integer passed in AX to a sequence of 1..6 characters if the internal underscores flag is false, 1..7 characters if the underscores flag contains true. The string this function produces is always in the range -32768..32767. If the internal underscores flag contains true and the value is greater than 999 or less than -999, then this function emits an underscore between the third and fourth digits (from the right) in the string.

HLA high-level calling sequence examples:

// The following will load "wordVariable" into AX and

// the address of "charArrayVariable" into EDI and then

// call conv.i16ToBuf:

conv.i16ToBuf( wordVariable, charArrayVariable );

// The following call will copy BX into AX and

// EDX into EDI prior to calling conv.i16ToBuf:

conv.i16ToBuf( bx, [edx] );

// The following just calls conv.i16ToBuf as AX and EDI

// already hold the parameter values:

conv.i16ToBuf( ax, [edi] );

// The following loads the constant in AX and calls

// conv.i16ToBuf:

conv.i16ToBuf( <constant>, [edi] ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable:

mov( wordVariable, ax );

lea( edi, charArrayVariable );

call conv.i16ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( wordVariable, ax );

mov( &charArrayVariable, edi );

call conv.i16ToBuf;

// Passing a pair of registers (that are not

// AX and EDI):

mov( bx, ax );

mov( edx, edi );

call conv.i16ToBuf;

// Passing a constant:

mov( <constant>, ax );

call conv.i16ToBuf; // Assume EDI already contains buffer address.

procedure conv.i32ToBuf( i32 :int32 in eax; var buf:var in edi )

This function converts the 32-bit signed integer passed in EAX to a sequence of 1..11 characters if the internal underscores flag is false, 1..14 characters if the underscores flag contains true. The string this function produces is always in the range -2147483648..2147483647. If the internal underscores flag contains true and the value is greater than 999 or less than -999, then this function emits an underscore between the third and fourth digits (from the right) in the string.

HLA high-level calling sequence examples:

// The following will load "dwordVariable" into EAX and

// the address of "charArrayVariable" into EDI and then

// call conv.i32ToBuf:

conv.i32ToBuf( dwordVariable, charArrayVariable );

// The following call will copy EBX into EAX and

// EDX into EDI prior to calling conv.i32ToBuf:

conv.i32ToBuf( ebx, [edx] );

// The following just calls conv.i32ToBuf as EAX and EDI

// already hold the parameter values:

conv.i32ToBuf( eax, [edi] );

// The following loads the constant in EAX and calls

// conv.i32ToBuf:

conv.i32ToBuf( <constant>, [edi] ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

mov( dwordVariable, eax );

lea( edi, charArrayVariable );

call conv.i32ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( dwordVariable, eax );

mov( &charArrayVariable, edi );

call conv.i32ToBuf;

// Passing a pair of registers (that are not

// EAX and EDI):

mov( ebx, eax );

mov( edx, edi );

call conv.i32ToBuf;

// Passing a constant:

mov( <constant>, eax );

call conv.i32ToBuf; // Assume EDI already contains buffer address.

procedure conv.i64ToBuf( q :qword; var buf:var in edi )

This function converts the 64-bit signed integer passed in q to a sequence of 1..20 characters if the internal underscores flag is false, 1..26 characters if the underscores flag contains true. The string this function produces is always in the range -9223372036854775808 .. 9223372036854775807. If the internal underscores flag contains true and the value is greater than 999 or less than -999, then this function emits an underscore between each group of three digits starting with the least significant digit.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.i64ToBuf:

conv.i64ToBuf( qwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.i64ToBuf:

conv.i64ToBuf( <constant>, [edi] ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.i64ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.i64ToBuf;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.i64ToBuf; // Assume EDI already contains buffer address.

procedure conv.i128ToBuf( l :lword; var buf:var in edi )

This function converts the 128-bit signed integer passed in l to a sequence of 1..40 characters if the internal underscores flag is false, 1..53 characters if the underscores flag contains true. The string this function produces is always in the range -170141183460469231731687303715884105728 .. 170141183460469231731687303715884105727. If the internal underscores flag contains true and the value is greater than 999 or less than -999, then this function emits an underscore between each group of three digits starting with the least significant digit.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.i128ToBuf:

conv.i128ToBuf( lwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.i128ToBuf:

conv.i128ToBuf( <constant>, [edi] ); // <constant> must fit in 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable and a buffer variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.i128ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.i128ToBuf;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.i128ToBuf; // Assume EDI already contains buffer address.

Integer Numeric to String Conversions

These routines convert a signed integer value ( 8, 16, 32, 64, or 128 bits) to a string. The standard ("unadorned") functions store the string data into a string object that you pass as a parameter to the function. That string object must be preallocated and large enough to receive the string result (else a string overflow occurs). The "adorned" functions, whose names begin with "a_" automatically allocate storage on the heap, store the converted string into that heap object, and then return a pointer to the newly allocated string in the EAX register (it is the caller’s responsibility to free the storage when it is no longer needed).

These functions let you specify a minimum field width and a fill character. If the number would require fewer than width print positions, the routines copy the fill character to the remaining positions in the destination string. If width is positive, the number is right justified in the string. If width is negative, the number is left justified in the string. If the string representation of the value requires more than width print positions, then these functions ignore the width and fill paramenters and use however many positions are necessary to properly display the value.

Here are the maximum number of print positions these routines will produce for each data type before considering the minimum field width:

Underscores flag is false:

8 bits: 4 (-128..127)

16 bits: 6 (-32768..32767)

32 bits: 11 (-2147483648..2147483647)

64 bits: 20 (-9223372036854775808..9223372036854775807)

128 bits: 40 (-170141183460469231731687303715884105728 ..

170141183460469231731687303715884105728)

Underscores flag is true:

8 bits: 4 (-128..127)

16 bits: 7 (-32_768..32_767)

32 bits: 14 (-2_147_483_648..2_147_483_647)

64 bits: 26 (-9_223_372_036_854_775_808..9_223_372_036_854_775_807)

128 bits: 52 (-170_141_183_460_469_231_731_687_303_715_884_105_728 ..

170_141_183_460_469_231_731_687_303_715_884_105_728)

procedure conv.i8ToStr ( b:int8; width:int32; fill:char; dest:string );

This function converts an 8-bit signed integer to the decimal string representation of that integer and stores the string in the preallocated string object specified by the dest paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. Note that the internal underscores flag will not affect the output because 8-bit integers are always three digits or smaller.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.i8ToStr:

conv.i8ToStr( byteVariable, destStr );

// The following call will BH’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.i8ToStr:

conv.i8ToStr( bh, edx );

// The following pushes the constant and destStr and calls

// conv.i8ToStr:

conv.bToBuf( <constant>, destStr ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.i8ToStr;

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

push( destStr );

call conv.i8ToStr;

// Passing a byte variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

push( destStr );

call conv.i8ToStr;

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

push( edx );

call conv.i8ToStr;

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

push( edx );

call conv.i8ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.i8ToStr;

procedure conv.a_i8ToStr ( b:int8; width:int32; fill:char );
@returns( "eax" );

This function converts an 8-bit signed integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. Note that the internal underscores flag will not affect the output because 8-bit integers are always three digits or smaller.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and then call conv.a_i8ToStr:

conv.a_i8ToStr( byteVariable );

mov( eax, byteStr );

// The following call will BH’s value onto the stack

// before calling conv.a_i8ToStr:

conv.a_i8ToStr( bh );

mov( eax, byteStr );

// The following pushes the constant and calls

// conv.a_i8ToStr:

conv.a_i8ToStr( <constant> ); // <constant> must fit in 8 bits

mov( eax, byteStr );

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

call conv.a_i8ToStr;

mov( eax, destStr );

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

call conv.a_i8ToStr;

mov( eax, destStr );

// Passing a byte variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

call conv.a_i8ToStr;

mov( eax, destStr );

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

call conv.a_i8ToStr;

mov( eax, byteStr );

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

call conv.a_i8ToStr;

mov( eax, byteStr );

// Passing a constant:

pushd( <constant> );

call conv.a_i8ToStr;

mov( eax, byteStr );

procedure conv.i16ToStr( w:int16; width:int32; fill:char; dest:string );

This function converts a 16-bit signed integer to its decimal string representation and stores the string in the preallocated string object specified by the dest paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "wordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.i16ToStr:

conv.i16ToStr( wordVariable, destStr );

// The following call will BX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.i16ToStr:

conv.i16ToStr( bx, edx );

// The following pushes the constant and destStr and calls

// conv.i16ToStr:

conv.i16ToStr( <constant>, destStr ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.i16ToStr;

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

push( destStr );

call conv.i16ToStr;

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

push( destStr );

call conv.i16ToStr;

// Passing a pair of registers:

// BX = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BX

push( edx );

call conv.i16ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.i16ToStr;

procedure conv.a_i16ToStr( w:int16; width:int32; fill:char );
@returns( "eax" );

This function converts a 16-bit signed integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "wordVariable" and call conv.a_i16ToStr:

conv.a_i16ToStr( wordVariable );

mov( eax, destStr );

// The following call will BX’s value onto the stack

// before calling conv.a_i16ToStr:

conv.a_i16ToStr( bx );

// The following pushes the constant and calls

// conv.a_i16ToStr:

conv.a_i16ToStr( <const>, destStr ); // <const> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( wordVariable, eax );

push( eax );

call conv.a_i16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

call conv.a_i16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

call conv.a_i16ToStr;

mov( eax, destStr );

// Passing a pair of registers:

// BX = value to print.

push( ebx ); // Pushes BX

call conv.a_i16ToStr;

mov( eax, wordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_i16ToStr;

mov( eax, destStr );

procedure conv.i32ToStr( d:int32; width:int32; fill:char; buffer:string );

This function converts a 32-bit signed integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.i32ToStr:

conv.i32ToStr( dwordVariable, destStr );

// The following call will push EBX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.i32ToStr:

conv.i32ToStr( ebx, edx );

// The following pushes the constant and destStr and calls

// conv.i32ToStr:

conv.i32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

When using the HLA high-level calling form, remember that string variables are dword pointers that contain the address of a string object. The destination string parameter is passed by value, not by reference; it just turns out that the value of a string is a pointer to the actual string data. In any case, this is why you can pass a register value as the destination string location rather than having to pass something like "[edx]". A construct like "[edx]" would imply that EDX contains the address of the string variable, that is, a pointer to the pointer to the string data.

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

push( dwordVariable );

push( destStr );

call conv.i32ToStr;

// Passing a pair of registers:

// EBX = value to print, EDX = pointer to string object.

push( ebx );

push( edx );

call conv.i32ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.i32ToStr;

procedure conv.a_i32ToStr( d:int32; width:int32; fill:char );
@returns( "eax" );

This function converts a 32-bit signed integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and then call conv.a_i32ToStr:

conv.a_i32ToStr( dwordVariable );

mov( eax, destStr );

// The following call will push EBX’s value onto the stack

// before calling conv.a_i32ToStr:

conv.a_i32ToStr( ebx );

// The following pushes the constant and calls

// conv.a_i32ToStr:

conv.a_i32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable:

push( dwordVariable );

call conv.a_i32ToStr;

mov( eax, destStr );

// Passing a register:

// EBX = value to print.

push( ebx );

call conv.a_i32ToStr;

mov( eax, dwordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_i32ToStr;

mov( eax, destStr );

procedure conv.i64ToStr( q:qword; width:int32; fill:char; buffer:string );

This function converts a 64-bit signed integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// and the value of the destStr string variable

// onto the stack and then call conv.i64ToStr:

conv.i64ToStr( qwordVariable, destStr );

// The following pushes the constant onto the stack along with

// the value held in the destStr variable and calls

// conv.i64ToStr:

conv.i64ToStr( <constant>, destStr ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.i64ToStr;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

push( destStr );

call conv.i64ToStr;

procedure conv.a_i64ToStr( q:qword; width:int32; fill:char );
@returns( "eax" );

This function converts a 64-bit signed integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack and then call conv.a_i64ToStr:

conv.a_i64ToStr( qwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_i64ToStr:

conv.a_i64ToStr( <constant> ); // <constant> must fit in 64 bits

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a qword variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_i64ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.a_i64ToStr;

mov( eax, destStr );

procedure conv.i128ToStr( l:lword; width:int32; fill:char; buffer:string );

This function converts a 128-bit signed integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion . If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// and destStr onto the stack, and then call conv.i128ToStr:

conv.i128ToStr( lwordVariable, destStr );

// The following pushes the constant onto the stack and calls

// conv.i128ToStr:

conv.i128ToStr( <constant>, edx ); // EDX contains string pointer value.

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

push( destStr );

call conv.i128ToStr;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( edx ); // EDX contains string pointer value.

call conv.i128ToStr;

procedure conv.a_i128ToStr( l:lword; width:int32; fill:char );
@returns( "eax" );

This function converts a 128-bit signed integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, and then call conv.a_i128ToStr:

conv.a_i128ToStr( lwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_i128ToStr:

conv.a_i128ToStr( <constant> );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

call conv.a_i128ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_i128ToStr;

mov( eax, destStr );

Signed Integer String to Numeric Conversions

The standard library string to integer conversion routines convert a sequence of digits, possibly prefaced by a minus sign, into the corresponding signed integer value. These routines begin by skipping over any leading delimiter characters (see the conv.getDelimiters and conv.setDelimiters functions for details), handling an optional minus sign, followed by any number of decimal digits and underscores (these routines ignore the underscores). Conversion stops at the end of the string or upon encountering a delimiter character.

These routines will raise a conversion error exception if they encounter a 7-bit ASCII character that is not a decimal digit, an underscore, or a delimiter character during the translation. These routines will raise an illegal character exception if they encounter a non-ASCII character (one with its H.O. bit set). These routines will raise a value out of range exception if the converted value will not fit in the destination data object.

There are two basic sets of string to numeric conversion routines: the conv.atoi* routines and the conv.strToi* routines. The atoi* routines process the characters pointed at by the ESI register. The strToi* routines process data in a string object, starting at an offset specified by a second parameter. For example, "conv.strToi8( "12345", 3);" returns the value 45 because it begins processing the string at (zero-based) offset 3 in the string.

procedure conv.atoi8 ( buffer:var in esi ); @returns( "al" );

This function converts the sequence of characters starting at the memory address held in ESI to an 8-bit signed integer. It returns the value (in the range -128..+127) in AL. Note that this function actually returns the sign-extended value in EAX, so you may use EAX if it is more convenient to do so. Upon successful return, ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AL:

conv.atoi8( [esi] );

mov( al, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to an 8-bit number:

conv.atoi8( sourceStr ); // Loads "sourceStr" into ESI

mov( al, byteVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoi8;

mov( al, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoi8;

mov( al, num12 );

procedure conv.atoi16 ( buffer:var in esi ); @returns( "ax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 16-bit signed integer. It returns the value (in the range -32768..+32767) in AX. Note that this function actually returns the sign-extended value in EAX, so you may use EAX if it is more convenient to do so. Upon successful return, ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AX:

conv.atoi16( [esi] );

mov( ax, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 16-bit number:

conv.atoi16( sourceStr ); // Loads "sourceStr" into ESI

mov( ax, wordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoi16;

mov( ax, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoi16;

mov( ax, num12 );

procedure conv.atoi32 ( buffer:var in esi ); @returns( "eax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 32-bit signed integer. It returns the value (in the range -2147483648..+2147483647) in EAX. ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EAX:

conv.atoi32( [esi] );

mov( eax, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 32-bit number:

conv.atoi32( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, dwordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoi32;

mov( eax, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoi32;

mov( eax, num12 );

procedure conv.atoi64 ( buffer:var in esi ); @returns( "edx:eax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 64-bit signed integer. It returns the value (in the range -9223372036854775808..+9223372036854775807) in EDX:EAX (EDX contains the H.O. dword). ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EDX:EAX:

conv.atoi64( [esi] );

mov( eax, (type dword hex64NumericResult[0]) );

mov( edx, (type dword hex64NumericResult[4]) );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 64-bit number:

conv.atoi64( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atoi64;

mov( eax, (type dword numericResult[0]) );

mov( edx, (type dword numericResult[4]) );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atoi64;

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

procedure conv.atoi128( buffer:var in esi; var l:lword );

This function converts the sequence of characters starting at the memory address held in ESI to a 128-bit signed integer. It returns the value (in the range -170141183460469231731687303715884105728..+170141183460469231731687303715884105727) in the l parameter that is passed by reference to this function. ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and stores that value in lwordDest (passed by reference):

conv.atoi128( [esi], lwordDest );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 128-bit number that it

// stores in lwordDest:

conv.atoi128( sourceStr, lwordDest ); // Loads "sourceStr" into ESI

HLA low-level calling sequence examples:

// Option 1: lwordDest is a static object declared in a

// HLA STATIC, READONLY, or STORAGE section:

// As with the first example above, assume ESI already

// contains the address of the string to convert:

pushd( &lwordDest ); // Pass address of lwordDest as reference parm.

call conv.atoi128;

// Option 2: lwordDest is a simple automatic variable (no indexing)

// declared in a VAR section (or as a parameter). Assume that

// no 32-bit registers can be disturbed by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

push( ebp );

add( @offset( lwordDest ), (type dword [esp]));

call conv.atoi128;

// Option 3: lwordDest is a complex addressing mode and at least

// one 32-bit register is available for use by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

lea( eax, lwordDest ); // Assume EAX is the available register

push( eax );

call conv.atoi128;

// Same as second high-level example above. Assumes that

// lwordDest is a static object.

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

pushd( &lwordDest );

call conv.atoi128;

procedure conv.strToi8( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to an 8-bit signed integer. It returns the value (in the range -128..+127) in AL. Note that this function actually returns the sign-extended value in EAX, so you may use EAX if it is more convenient to do so.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strToi8( decValueStr, 0 ); // Index=0 starts at beginning

mov( al, numericResult );

// The following demonstrates using a non-zero index:

conv.strToi8( "abc12", 3 ); // "12" begins at offset 3

mov( al, hex12 );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strToi8;

mov( al, decNumericResult );

// Same as second example above

static

str12 :string := "abc12";

push( str12 ); // Note that str12 points at "abc12".

pushd( 3 ); // Index to "12" in "abc12".

call conv.strToi8;

mov( al, dec12 );

procedure conv.strToi16( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 16-bit signed integer. It returns the value (in the range -32768..+32767) in AX. Note that this function actually returns the sign-extended value in EAX, so you may use EAX if it is more convenient to do so.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strToi16( hexValueStr, 0 ); // Index=0 starts at beginning

mov( ax, wordVar );

// The following demonstrates using a non-zero index:

conv.strToi16( "abc1234", 3 ); // "1234" begins at offset 3

mov( ax, wordVar );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strToi16;

mov( ax, wordVar );

// Same as second example above

static

str1200 :string := "abc1200";

push( str1200 ); // Note that str1200 points at "abc1200".

pushd( 3 ); // Index to "1200" in "abc1200".

call conv.strToi16;

mov( ax, wordVar );

procedure conv.strToi32( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 32-bit signed integer. It returns the value (in the range -2147483648..+2147483647) in EAX.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strToi32( decValueStr, 0 ); // Index=0 starts at beginning

mov( eax, dwordVar );

// The following demonstrates using a non-zero index:

conv.strToi32( "abc12_345", 3 ); // "12_345" begins at offset 3

mov( eax, dwordVar );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strToi32;

mov( eax, dwordVar );

// Same as second example above

static

str12345 :string := "abc-12_345";

push( str12345 ); // Note that str12345 points at "abc-12_345".

pushd( 3 ); // Index to "-12_345" in "abc-12_345".

call conv.strToi32;

mov( eax, dwordVar ); // dwordVar now contains -12,345.

procedure conv.strToi64( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 64-bit signed integer. It returns the value (in the range -9223372036854775808 .. +9223372036854775807) in EDX:EAX (EDX contains the H.O. dword).

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strToi64( decValueStr, 0 ); // Index=0 starts at beginning

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// The following demonstrates using a non-zero index:

conv.strToi64( "a-123", 1 ); // "-123" begins at offset 1

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strToi64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// Same as second example above

static

strabc12 :string := "a-123";

push( strabc12 ); // Note that strabc12 points at "a-123".

pushd( 1 ); // Index to "-123" in "a-123".

call conv.strToi64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

procedure conv.strToi128( s:string; index:dword; var dest:lword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 128-bit signed integer. It returns the value (in the range -170141183460469231731687303715884105728.. +170141183460469231731687303715884105727) in the parameter l that you pass by reference to this function.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" (index=0) to numeric form and store the

// 128-bit result into the 1wordDest variable:

conv.strToi128( decValueStr, 0, 1wordDest );

// The following demonstrates using a non-zero index:

conv.strToi128( "abc1234567890123456789", 3, 1wordDest );

HLA low-level calling sequence examples:

// Option #1: lwordDest is a STATIC/READONLY/STORAGE

// variable:

push( decValueStr ); // Same as first example above

pushd( 0 );

pushd( &lwordDest );

call conv.strToi128;

// Option #2: lwordDest is not a static object and

// a 32-bit register is available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

lea( eax, lwordDest ); // Assuming EAX is available

push( eax );

call conv.strToi128;

// Option #3: lwordDest is an automatic (var) object and

// no 32-bit registers are available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

push( ebp );

add( @offset( lwordDest ), (type dword [esp]) );

call conv.strToi128;

// Option #4: lwordDest is a complex addressing mode object and

// no 32-bit registers are available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

sub( 4, esp );

push( eax );

lea( eax, lwordDest );

mov( eax, [esp+4] );

pop( eax );

call conv.strToi128;

Unsigned Integer Conversions

The integer conversion function process signed integer values that are 8, 16, 32, 64, or 128 bits long. Functions in this category compute the output size (in print positions) of an integer, convert an integer to a sequence of characters, and convert a sequence of characters to an integer value.

Internal Routines

The following routines are used internally by the standard library unsigned integer code and you should not directly call them: conv._u8Size, conv._u16Size, and conv._u32Size.

Unsigned Integer Size Calculations

These routines return the size, in screen print positions, it would take to print the unsigned integer passed in the specified parameter. They return their value in the EAX register. Note that these routines include print positions required by underscores if you’ve enabled underscore output in values (see conv.setUnderscores and conv.getUnderscores for details).

It should go without saying that if you compute the size of an unsigned integer and then change the value of the internal underscores flag, the size you’ve computed may be invalid.

procedure conv.u8Size( b:byte in al ); @returns( "eax" );

Computes the output size of an 8-bit unsigned integer (passed in AL) and returns this value in EAX. The return result will always be a value in the range 1..3. The internal underscores flag does not affect the result this function returns.

HLA high-level calling sequence examples:

conv.u8Size( byteVariable );

mov( eax, numSize );

conv.u8Size( <byte register> ); // al, ah, bl, bh, cl, ch, dl, dh

mov( eax, int8Size );

conv.u8Size( <constant> ); // Must fit into eight bits

mov( al, constantsSize );

Because conv.u8Size passes its input parameter in the AL register, any form of the high-level calling sequence except "conv.u8Size( al );" will automatically generate an instruction of the form "mov(<operand>,al);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the AL register and pass AL as the parameter to conv.u8Size.

HLA low-level calling sequence examples:

mov( byteVariable, al );

call conv.u8Size;

mov( eax, numSize );

mov( <byte register>, al ); // ah, bl, bh, cl, ch, dl, dh

call conv.u8Size;

mov( ax, wordVariable );

// Explicit Examples:

mov( bh, al );

call conv.u8Size;

mov( al, bhSize );

call conv.u8Size; // Assume value is already in AL

mov( al, alSize );

mov( 123, al ); // Example of computing the size of a constant

call conv.u8Size;

mov( eax, constsSize );

procedure conv.u16Size( w:word in ax )

Computes the output size of a 16-bit unsigned integer (passed in AX) and returns this value in EAX. The return result will always be a value in the range 1..5 if the internal underscores flag contains false, 1..6 if the underscores flag contains true.

HLA high-level calling sequence examples:

conv.u16Size( wordVariable );

mov( eax, numSize );

conv.u16Size( <word register> ); // ax, bx, cx, dx, bp, sp, si, di

mov( eax, int16Size );

conv.u16Size( <constant> ); // Must fit into 16 bits

mov( al, constantsSize );

Because conv.u16Size passes its input parameter in the AX register, any form of the high-level calling sequence except "conv.u16Size( ax );" will automatically generate an instruction of the form "mov(<operand>,ax);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the AX register and pass AX as the parameter to conv.u16Size.

HLA low-level calling sequence examples:

mov( wordVariable, ax );

call conv.u16Size;

mov( eax, numSize );

mov( <word register>, ax ); // bx, cx, dx, bp, sp, si, or di

call conv.u16Size;

mov( ax, wordVariable );

// Explicit Examples:

mov( bx, ax );

call conv.u16Size;

mov( al, bxSize );

call conv.u16Size; // Assume value is already in AX

mov( al, axSize );

mov( 12345, ax ); // Example of computing the size of a constant

call conv.u16Size;

mov( eax, constsSize );

See the comment at the end of conv.i8Size about passing constants to these functions.

procedure conv.u32Size( d:dword in eax )

Computes the output size of a 32-bit unsigned integer (passed in EAX) and returns this value in EAX. The return result will always be a value in the range 1..10 if the internal underscores flag contains false, 1..11 if the underscores flag contains true.

HLA high-level calling sequence examples:

conv.u32Size( wordVariable );

mov( eax, numSize );

conv.u32Size( <dword register> ); // eax, ebx, ecx, edx,

mov( eax, int16Size )l // ebp, esp, esi, or edi

conv.u32Size( <constant> ); // Must fit into 32 bits

mov( al, constantsSize );

Because conv.u32Size passes its input parameter in the EAX register, any form of the high-level calling sequence except "conv.u32Size( eax );" will automatically generate an instruction of the form "mov(<operand>,eax);". Therefore, if possible, you should try to have the value whose size you wish to compute already sitting in the EAX register and pass EAX as the parameter to conv.u32Size.

HLA low-level calling sequence examples:

mov( dwordVariable, eax );

call conv.u32Size;

mov( eax, numSize );

mov( <dword register>, eax ); // ebx, ecx, edx,

call conv.u32Size; // ebp, esp, esi, or edi

mov( ax, wordVariable );

// Explicit Examples:

mov( ebx, eax );

call conv.u32Size;

mov( al, bxSize );

call conv.u32Size; // Assume value is already in AX

mov( al, axSize );

mov( 1234567890, eax ); // Example of computing

call conv.u32Size; // the size of a constant.

mov( eax, constsSize );

See the comment at the end of conv.u8Size about passing constants to these functions.

procedure conv.u64Size( q:qword )

Computes the output size of a 64-bit unsigned integer (passed in in q parameter) and returns this value in EAX. The return result will always be a value in the range 1..20 (e.g., "18446744073709551615") if the internal underscores flag contains false, 1..26 if the underscores flag contains true (e.g., "18_446_744_073_709_551_615").

HLA high-level calling sequence examples:

conv.u64Size( qwordVariable );

mov( eax, numSize );

conv.u64Size( <constant> ); // Must fit into 64 bits

mov( al, constantsSize );

HLA low-level calling sequence examples:

push( (type dword qwordVariable[4])); // Push H.O. dword first

push( (type dword qwordVariable[0])); // Push L.O. dword second

call conv.u64Size;

mov( eax, numSize );

// Compute the size of a 64-bit constant:

pushd( 12345 >> 32 ); // Push H.O. dword first

pushd( 12345 & $FFFF_FFFF ); // Push L.O. dword second

call conv.u64Size;

mov( eax, constsSize );

See the comment at the end of conv.u8Size about passing constants to these functions. If you make a habit of explicitly passing 64-bit constants to this function, you might consider writing a macro to push the 64-bit constant for you (see the chapter on "Passing Parameters to Standard Library Routines" for more details).

procedure conv.u128Size( l:lword )

Computes the output size of a 128-bit unsigned integer (passed in the l parameter) and returns this value in EAX. The return result will always be a value in the range 1..39 (e.g., "340282366920938463463374607431768211455") if the internal underscores flag contains false, 1..51 if the underscores flag contains true (e.g., "340_282_366_920_938_463_463_374_607_431_768_211_455").

HLA high-level calling sequence examples:

conv.u128Size( lwordVariable );

mov( eax, numSize );

conv.u128Size( <constant> ); // Must fit into 128 bits

mov( al, constantsSize );

HLA low-level calling sequence examples:

push( (type dword lwordVariable[12])); // Push H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // Push L.O. dword last

call conv.u64Size;

mov( eax, numSize );

// Compute the size of a 128-bit constant:

pushd( 12345 >> 96 ); // Push H.O. dword first

pushd( (12345 >> 64) & $FFFF_FFFF );

pushd( (12345 >> 32 ) & $FFFF_FFFF );

pushd( 12345 & $FFFF_FFFF ); // Push L.O. dword last

call conv.u128Size;

mov( eax, constsSize );

See the comment at the end of conv.u8Size about passing constants to these functions. If you make a habit of explicitly passing 128-bit constants to this function, you might consider writing a macro to push the 128-bit constant for you (see the chapter on "Passing Parameters to Standard Library Routines" for more details).

Unsigned Integer Numeric to Buffer Conversions

procedure conv.u8ToBuf( u8: uns8 in al )

This function converts the 8-bit unsigned integer passed in AL to a sequence of 1..3 characters. The string this function produces is always in the range 0..255. Note that because this string always contains three or fewer digits, the internal underscores flag setting does not affect this function’s output.

HLA high-level calling sequence examples:

// The following will load "byteVariable" into AL and

// the address of "charArrayVariable" into EDI and then

// call conv.u8ToBuf:

conv.u8ToBuf( byteVariable, charArrayVariable );

// The following call will copy BH into AL and

// EDX into EDI prior to calling conv.u8ToBuf:

conv.u8ToBuf( bh, [edx] );

// The following just calls conv.u8ToBuf as AL and EDI

// already hold the parameter values:

conv.u8ToBuf( al, [edi] );

// The following loads the constant in AL and calls

// conv.u8ToBuf:

conv.u8ToBuf( <constant>, [edi] ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable:

mov( byteVariable, al );

lea( edi, charArrayVariable );

call conv.u8ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( byteVariable, al );

mov( &charArrayVariable, edi );

call conv.u8ToBuf;

// Passing a pair of registers (that are not

// AL and EDI):

mov( bh, al );

mov( edx, edi );

call conv.u8ToBuf;

// Passing a constant:

mov( <constant>, al );

call conv.u8ToBuf; // Assume EDI already contains buffer address.

procedure conv.u16ToBuf( u16: uns16 in ax )

This function converts the 16-bit unsigned integer passed in AX to a sequence of 1..5 characters if the internal underscores flag is false, 1..6 characters if the underscores flag contains true. The string this function produces is always in the range 0..65535. If the internal underscores flag contains true and the value is greater than 999, then this function emits an underscore between the third and fourth digits (from the right) in the string.

HLA high-level calling sequence examples:

// The following will load "wordVariable" into AX and

// the address of "charArrayVariable" into EDI and then

// call conv.u16ToBuf:

conv.u16ToBuf( wordVariable, charArrayVariable );

// The following call will copy BX into AX and

// EDX into EDI prior to calling conv.u16ToBuf:

conv.u16ToBuf( bx, [edx] );

// The following just calls conv.u16ToBuf as AX and EDI

// already hold the parameter values:

conv.u16ToBuf( ax, [edi] );

// The following loads the constant in AX and calls

// conv.u16ToBuf:

conv.u16ToBuf( <constant>, [edi] ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable:

mov( wordVariable, ax );

lea( edi, charArrayVariable );

call conv.u16ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( wordVariable, ax );

mov( &charArrayVariable, edi );

call conv.u16ToBuf;

// Passing a pair of registers (that are not

// AX and EDI):

mov( bx, ax );

mov( edx, edi );

call conv.u16ToBuf;

// Passing a constant:

mov( <constant>, ax );

call conv.u16ToBuf; // Assume EDI already contains buffer address.

procedure conv.u32ToBuf( u32: uns32 in eax)

This function converts the 32-bit unsigned integer passed in EAX to a sequence of 1..10 characters if the internal underscores flag is false, 1..11 characters if the underscores flag contains true. The string this function produces is always in the range 0..4294967295. If the internal underscores flag contains true and the value is greater than 999, then this function emits an underscore between the third and fourth digits (from the right) in the string.

HLA high-level calling sequence examples:

// The following will load "dwordVariable" into EAX and

// the address of "charArrayVariable" into EDI and then

// call conv.u32ToBuf:

conv.u32ToBuf( dwordVariable, charArrayVariable );

// The following call will copy EBX into EAX and

// EDX into EDI prior to calling conv.u32ToBuf:

conv.u32ToBuf( ebx, [edx] );

// The following just calls conv.u32ToBuf as EAX and EDI

// already hold the parameter values:

conv.u32ToBuf( eax, [edi] );

// The following loads the constant in EAX and calls

// conv.u32ToBuf:

conv.u32ToBuf( <constant>, [edi] ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

mov( dwordVariable, eax );

lea( edi, charArrayVariable );

call conv.u32ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

mov( dwordVariable, eax );

mov( &charArrayVariable, edi );

call conv.u32ToBuf;

// Passing a pair of registers (that are not

// EAX and EDI):

mov( ebx, eax );

mov( edx, edi );

call conv.u32ToBuf;

// Passing a constant:

mov( <constant>, eax );

call conv.u32ToBuf; // Assume EDI already contains buffer address.

procedure conv.u64ToBuf( q:qword )

This function converts the 64-bit unsigned integer passed in q to a sequence of 1..20 characters if the internal underscores flag is false, 1..26 characters if the underscores flag contains true. The string this function produces is always in the range 0 .. 18446744073709551615. If the internal underscores flag contains true and the value is greater than 999, then this function emits an underscore between each group of three digits starting with the least significant digit.

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.u64ToBuf:

conv.u64ToBuf( qwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.u64ToBuf:

conv.u64ToBuf( <constant>, [edi] ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.u64ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.u64ToBuf;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.u64ToBuf; // Assume EDI already contains buffer address.

procedure conv.u128ToBuf( l:lword )

This function converts the 128-bit unsigned integer passed in l to a sequence of 1..39 characters if the internal underscores flag is false, 1..52 characters if the underscores flag contains true. The string this function produces is always in the range 0 .. 340282366920938463463374607431768211455. If the internal underscores flag contains true and the value is greater than 999, then this function emits an underscore between each group of three digits starting with the least significant digit.

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, load the address of "charArrayVariable"

// into EDI and then call conv.u128ToBuf:

conv.u128ToBuf( lwordVariable, charArrayVariable );

// The following pushes the constant onto the stack and calls

// conv.u128ToBuf:

conv.u128ToBuf( <constant>, [edi] ); // <constant> must fit in 128 bits

HLA low-level calling sequence examples:

// Passing an lword variable and a buffer variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

lea( edi, charArrayVariable );

call conv.u128ToBuf;

// Alternate form of above if charArrayVariable is

// a static object (STATIC, READONLY, or STORAGE):

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

mov( &charArrayVariable, edi );

call conv.u128ToBuf;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.u128ToBuf; // Assume EDI already contains buffer address.

Unsigned Integer Numeric to String Conversions

These routines convert an unsigned integer value ( 8, 16, 32, 64, or 128 bits) to a string. The standard ("unadorned") functions store the string data into a string object that you pass as a parameter to the function. That string object must be preallocated and large enough to receive the string result (else a string overflow occurs). The "adorned" functions, whose names begin with "a_" automatically allocate storage on the heap, store the converted string into that heap object, and then return a pointer to the newly allocated string in the EAX register (it is the caller’s responsibility to free the storage when it is no longer needed).

Here are the maximum number of print positions these routines will produce for each data type before considering the minimum field width:

Underscores flag is false:

8 bits: 3 (0..255)

16 bits: 5 (0..65535)

32 bits: 10 (0..4294967295)

64 bits: 20 (0..18446744073709551615)

128 bits: 39 (0 .. 340282366920938463463374607431768211455)

Underscores flag is true:

8 bits: 3 (0..255)

16 bits: 6 (0..65_535)

32 bits: 13 (0..4_294_967_295)

64 bits: 26 (0..18_446_744_073_709_551_615)

128 bits: 51 (0..340_282_366_920_938_463_463_374_607_431_768_211_455)

procedure conv.u8ToStr ( b:uns8; width:int32; fill:char; buffer:string );

This function converts an 8-bit unsigned integer to the decimal string representation of that integer and stores the string in the preallocated string object specified by the dest paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. Note that the internal underscores flag will not affect the output because 8-bit integers are always three digits or smaller.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.u8ToStr:

conv.u8ToStr( byteVariable, destStr );

// The following call will BH’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.u8ToStr:

conv.u8ToStr( bh, edx );

// The following pushes the constant and destStr and calls

// conv.u8ToStr:

conv.bToBuf( <constant>, destStr ); // <constant> must fit in 8 bits

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.u8ToStr;

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

push( destStr );

call conv.u8ToStr;

// Passing a byte variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

push( destStr );

call conv.u8ToStr;

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

push( edx );

call conv.u8ToStr;

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

push( edx );

call conv.u8ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.u8ToStr;

procedure conv.a_u8ToStr ( b:uns8; width:int32; fill:char );
@returns( "eax" );

This function converts an 8-bit unsigned integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. Note that the internal underscores flag will not affect the output because 8-bit integers are always three digits or smaller.

HLA high-level calling sequence examples:

// The following will push "byteVariable" and then call conv.a_u8ToStr:

conv.a_u8ToStr( byteVariable );

mov( eax, byteStr );

// The following call will BH’s value onto the stack

// before calling conv.a_u8ToStr:

conv.a_u8ToStr( bh );

mov( eax, byteStr );

// The following pushes the constant and calls

// conv.a_u8ToStr:

conv.a_u8ToStr( <constant> ); // <constant> must fit in 8 bits

mov( eax, byteStr );

HLA low-level calling sequence examples:

// Passing a byte variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

call conv.a_u8ToStr;

mov( eax, destStr );

// Passing a byte variable and a buffer variable, option 2

// (if byteVariable isn’t the last byte in mapped memory):

push( (type dword byteVariable));

call conv.a_u8ToStr;

mov( eax, destStr );

// Passing a byte variable, option 3

// No registers are available and we can’t guarantee that

// the three bytes following byteVariable are present in

// mapped memory:

sub( 4, esp );

push( eax );

movzx( byteVariable, eax );

mov( eax, [esp+4] );

pop( eax );

call conv.a_u8ToStr;

mov( eax, destStr );

// Passing a pair of registers (hex value in AL, BL, CL, or DL):

// BL = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BL

call conv.a_u8ToStr;

mov( eax, byteStr );

// Passing a pair of registers (hex value in AH, BH, CH, or DH):

// BH = value to print, EDX = pointer to string object.

pushd( 0 );

mov( bh, [esp] );

call conv.a_u8ToStr;

mov( eax, byteStr );

// Passing a constant:

pushd( <constant> );

call conv.a_u8ToStr;

mov( eax, byteStr );

procedure conv.u16ToStr( w:uns16; width:int32; fill:char; buffer:string );

This function converts a 16-bit unsigned integer to its decimal string representation and stores the string in the preallocated string object specified by the dest paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "wordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.u16ToStr:

conv.u16ToStr( wordVariable, destStr );

// The following call will BX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.u16ToStr:

conv.u16ToStr( bx, edx );

// The following pushes the constant and destStr and calls

// conv.u16ToStr:

conv.u16ToStr( <constant>, destStr ); // <constant> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( byteVariable, eax );

push( eax );

push( destStr );

call conv.u16ToStr;

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

push( destStr );

call conv.u16ToStr;

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

push( destStr );

call conv.u16ToStr;

// Passing a pair of registers:

// BX = value to print, EDX = pointer to string object.

push( ebx ); // Pushes BX

push( edx );

call conv.u16ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.u16ToStr;

procedure conv.a_u16ToStr( w:uns16; width:int32; fill:char );
@returns( "eax" );

This function converts a 16-bit unsigned integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "wordVariable" and call conv.a_u16ToStr:

conv.a_u16ToStr( wordVariable );

mov( eax, destStr );

// The following call will BX’s value onto the stack

// before calling conv.a_u16ToStr:

conv.a_u16ToStr( bx );

// The following pushes the constant and calls

// conv.a_u16ToStr:

conv.a_u16ToStr( <const>, destStr ); // <const> must fit in 16 bits

HLA low-level calling sequence examples:

// Passing a word variable and a buffer variable, option 1

// (if a 32-bit register is available):

movzx( wordVariable, eax );

push( eax );

call conv.a_u16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 2

// (if wordVariable isn’t the last byte in mapped memory):

push( (type dword wordVariable));

call conv.a_u16ToStr;

mov( eax, destStr );

// Passing a word variable and a buffer variable, option 3

// No registers are available and we can’t guarantee that

// the two bytes following wordVariable are present in

// mapped memory:

pushw( 0 );

push( wordVariable );

call conv.a_u16ToStr;

mov( eax, destStr );

// Passing a pair of registers:

// BX = value to print.

push( ebx ); // Pushes BX

call conv.a_u16ToStr;

mov( eax, wordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_u16ToStr;

mov( eax, destStr );

procedure conv.u32ToStr( d:uns32; width:int32; fill:char; buffer:string );

This function converts a 32-bit unsigned integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and "destStr" (which

// is a pointer to a string object) and then call conv.u32ToStr:

conv.u32ToStr( dwordVariable, destStr );

// The following call will push EBX’s value onto the stack and then

// push EDX’s value (which is the address of a string object)

// before calling conv.u32ToStr:

conv.u32ToStr( ebx, edx );

// The following pushes the constant and destStr and calls

// conv.u32ToStr:

conv.u32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

When using the HLA high-level calling form, remember that string variables are dword pointers that contain the address of a string object. The destination string parameter is passed by value, not by reference; it just turns out that the value of a string is a pointer to the actual string data. In any case, this is why you can pass a register value as the destination string location rather than having to pass something like "[edx]". A construct like "[edx]" would imply that EDX contains the address of the string variable, that is, a pointer to the pointer to the string data.

HLA low-level calling sequence examples:

// Passing a dword variable and a buffer variable:

push( dwordVariable );

push( destStr );

call conv.u32ToStr;

// Passing a pair of registers:

// EBX = value to print, EDX = pointer to string object.

push( ebx );

push( edx );

call conv.u32ToStr;

// Passing a constant:

pushd( <constant> );

push( destStr );

call conv.u32ToStr;

procedure conv.a_u32ToStr( d:uns32; width:int32; fill:char );
@returns( "eax" );

This function converts a 32-bit unsigned integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push "dwordVariable" and then call conv.a_u32ToStr:

conv.a_u32ToStr( dwordVariable );

mov( eax, destStr );

// The following call will push EBX’s value onto the stack

// before calling conv.a_u32ToStr:

conv.a_u32ToStr( ebx );

// The following pushes the constant and calls

// conv.a_u32ToStr:

conv.a_u32ToStr( <constant>, destStr ); // <constant> must fit in 32 bits

HLA low-level calling sequence examples:

// Passing a dword variable:

push( dwordVariable );

call conv.a_u32ToStr;

mov( eax, destStr );

// Passing a register:

// EBX = value to print.

push( ebx );

call conv.a_u32ToStr;

mov( eax, dwordStr );

// Passing a constant:

pushd( <constant> );

call conv.a_u32ToStr;

mov( eax, destStr );

procedure conv.u64ToStr( q:qword; width:int32; fill:char; buffer:string );

This function converts a 64-bit unsigned integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// and the value of the destStr string variable

// onto the stack and then call conv.u64ToStr:

conv.u64ToStr( qwordVariable, destStr );

// The following pushes the constant onto the stack along with

// the value held in the destStr variable and calls

// conv.u64ToStr:

conv.u64ToStr( <constant>, destStr ); // <constant> must fit in 64 bits

HLA low-level calling sequence examples:

// Passing a qword variable and a buffer variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

push( destStr );

call conv.u64ToStr;

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

push( destStr );

call conv.u64ToStr;

procedure conv.a_u64ToStr( q:qword; width:int32; fill:char );
@returns( "eax" );

This function converts a 64-bit unsigned integer to the decimal string representation of that integer and stores the string in storage it allocates on the heap. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). The caller is responsible for freeing the storage when it is no longer needed. If the conversion produces more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "qwordVariable"

// onto the stack and then call conv.a_u64ToStr:

conv.a_u64ToStr( qwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_u64ToStr:

conv.a_u64ToStr( <constant> ); // <constant> must fit in 64 bits

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing a qword variable:

push( (type dword qwordVariable[4])); // H.O. dword first

push( (type dword qwordVariable[0])); // L.O. dword last

call conv.a_u64ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 32 ); // Push H.O. dword of constant first.

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword second.

call conv.a_u64ToStr;

mov( eax, destStr );

procedure conv.u128ToStr(l:lword; width:int32; fill:char; buffer:string );

This function converts a 128-bit unsigned integer to its decimal string representation and stores the string in the preallocated string object specified by the buffer paramenter. The width and fill parameters specify the minimum field width and padding character (if the minimum field width is greater than the number of output characters needed for the string). This function will raise a string overflow exception if the destination string is not large enough to hold the conversion. If the conversion requires more than three digits and the internal underscores flag is true, then this function will insert an underscore between each group of three digits, starting with the least signficant digit (see conv.getUnderscores and conv.setUnderscores for more details).

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// and destStr onto the stack, and then call conv.u128ToStr:

conv.u128ToStr( lwordVariable, destStr );

// The following pushes the constant onto the stack and calls

// conv.u128ToStr:

conv.u128ToStr( <constant>, edx ); // EDX contains string pointer value.

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

push( destStr );

call conv.u128ToStr;

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

push( edx ); // EDX contains string pointer value.

call conv.u128ToStr;

procedure conv.a_u128ToStr( l:lword; width:int32; fill:char );
@returns( "eax" );

HLA high-level calling sequence examples:

// The following will push the value of "lwordVariable"

// onto the stack, and then call conv.a_u128ToStr:

conv.a_u128ToStr( lwordVariable );

mov( eax, destStr );

// The following pushes the constant onto the stack and calls

// conv.a_u128ToStr:

conv.a_u128ToStr( <constant> );

mov( eax, destStr );

HLA low-level calling sequence examples:

// Passing an lword variable:

push( (type dword lwordVariable[12])); // H.O. dword first

push( (type dword lwordVariable[8]));

push( (type dword lwordVariable[4]));

push( (type dword lwordVariable[0])); // L.O. dword last

call conv.a_u128ToStr;

mov( eax, destStr );

// Passing a constant:

pushd( <constant> >> 96 ); // Push H.O. dword of constant first.

pushd( (<constant> >> 64)& $FFFF_FFFF );

pushd( (<constant> >> 32)& $FFFF_FFFF );

pushd( <constant> & $FFFF_FFFF ); // Push L.O. dword last.

call conv.a_u128ToStr;

mov( eax, destStr );

Unsigned Integer String to Numeric Conversions

The standard library string to integer conversion routines convert a sequence of digits into the corresponding unsigned integer value. These routines begin by skipping over any leading delimiter characters (see the conv.getDelimiters and conv.setDelimiters functions for details) followed by any number of decimal digits and underscores (these routines ignore the underscores). Conversion stops at the end of the string or upon encountering a delimiter character.

There are two basic sets of string to numeric conversion routines: the conv.atou* routines and the conv.strTou* routines. The atou* routines process the characters pointed at by the ESI register. The strTou* routines process data in a string object, starting at an offset specified by a second parameter. For example, "conv.strTou8( "12345", 3);" returns the value 45 because it begins processing the string at (zero-based) offset 3 in the string.

procedure conv.atou8 ( buffer: var in esi ); @returns( "ax" );

This function converts the sequence of characters starting at the memory address held in ESI to an 8-bit unsigned integer. It returns the value (in the range 0..+255) in AL. Note that this function actually returns the zero-extended value in EAX, so you may use EAX if it is more convenient to do so. Upon successful return, ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AL:

conv.atou8( [esi] );

mov( al, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to an 8-bit number:

conv.atou8( sourceStr ); // Loads "sourceStr" into ESI

mov( al, byteVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atou8;

mov( al, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atou8;

mov( al, num12 );

procedure conv.atou16 ( buffer: var in esi ); @returns( "ax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 16-bit unsigned integer. It returns the value (in the range 0..65535) in AX. Note that this function actually returns the zero-extended value in EAX, so you may use EAX if it is more convenient to do so. Upon successful return, ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in AX:

conv.atou16( [esi] );

mov( ax, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 16-bit number:

conv.atou16( sourceStr ); // Loads "sourceStr" into ESI

mov( ax, wordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atou16;

mov( ax, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atou16;

mov( ax, num12 );

procedure conv.atou32 ( buffer: var in esi ); @returns( "eax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 32-bit unsigned integer. It returns the value (in the range 0..4294967295) in EAX. ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the hexadecimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EAX:

conv.atou32( [esi] );

mov( eax, numericResult );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 32-bit number:

conv.atou32( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, dwordVariable );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atou32;

mov( eax, numericResult );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atou32;

mov( eax, num12 );

procedure conv.atou64 ( buffer: var in esi ); @returns( "edx:eax" );

This function converts the sequence of characters starting at the memory address held in ESI to a 64-bit unsigned integer. It returns the value (in the range 0..18446744073709551615) in EDX:EAX (EDX contains the H.O. dword). ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and return that value in EDX:EAX:

conv.atou64( [esi] );

mov( eax, (type dword hex64NumericResult[0]) );

mov( edx, (type dword hex64NumericResult[4]) );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 64-bit number:

conv.atou64( sourceStr ); // Loads "sourceStr" into ESI

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

HLA low-level calling sequence examples:

// Same as first example above – ESI already contains

// the address of the first character to convert:

call conv.atou64;

mov( eax, (type dword numericResult[0]) );

mov( edx, (type dword numericResult[4]) );

// Same as second example above

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

call conv.atou64;

mov( eax, (type dword qwordVariable[0]) );

mov( edx, (type dword qwordVariable[4]) );

procedure conv.atou128( buffer: var in esi; var l:lword );

This function converts the sequence of characters starting at the memory address held in ESI to a 128-bit signed integer. It returns the value (in the range 0..340282366920938463463374607431768211455) in the l parameter that is passed by reference to this function. ESI is pointing at the delimiter character at the end of the sequence of digits.

HLA high-level calling sequence examples:

// The following will convert the decimal characters in memory

// at the address specified by [esi] into a numeric value

// and stores that value in lwordDest (passed by reference):

conv.atou128( [esi], lwordDest );

// The following loads ESI with the address of

// a sequence of decimal characters (held in an HLA

// string) and converts them to a 128-bit number that it

// stores in lwordDest:

conv.atou128( sourceStr, lwordDest ); // Loads "sourceStr" into ESI

HLA low-level calling sequence examples:

// Option 1: lwordDest is a static object declared in a

// HLA STATIC, READONLY, or STORAGE section:

// As with the first example above, assume ESI already

// contains the address of the string to convert:

pushd( &lwordDest ); // Pass address of lwordDest as reference parm.

call conv.atou128;

// Option 2: lwordDest is a simple automatic variable (no indexing)

// declared in a VAR section (or as a parameter). Assume that

// no 32-bit registers can be disturbed by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

push( ebp );

add( @offset( lwordDest ), (type dword [esp]));

call conv.atou128;

// Option 3: lwordDest is a complex addressing mode and at least

// one 32-bit register is available for use by this code.

// As with the first example above, assume ESI already

// contains the address of the string to convert:

lea( eax, lwordDest ); // Assume EAX is the available register

push( eax );

call conv.atou128;

// Same as second high-level example above. Assumes that

// lwordDest is a static object.

static

sourceStr :string := "12";

.
mov( sourceStr, esi );

pushd( &lwordDest );

call conv.atou128;

procedure conv.strTou8( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to an 8-bit unsigned integer. It returns the value (in the range 0..255) in AL. Note that this function actually returns the zero-extended value in EAX, so you may use EAX if it is more convenient to do so.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strTou8( decValueStr, 0 ); // Index=0 starts at beginning

mov( al, numericResult );

// The following demonstrates using a non-zero index:

conv.strTou8( "abc12", 3 ); // "12" begins at offset 3

mov( al, hex12 );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strTou8;

mov( al, decNumericResult );

// Same as second example above

static

str12 :string := "abc12";

push( str12 ); // Note that str12 points at "abc12".

pushd( 3 ); // Index to "12" in "abc12".

call conv.strTou8;

mov( al, dec12 );

procedure conv.strTou16( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 16-bit unsigned integer. It returns the value (in the range 0..65535) in AX. Note that this function actually returns the zero-extended value in EAX, so you may use EAX if it is more convenient to do so.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strTou16( hexValueStr, 0 ); // Index=0 starts at beginning

mov( ax, wordVar );

// The following demonstrates using a non-zero index:

conv.strTou16( "abc1234", 3 ); // "1234" begins at offset 3

mov( ax, wordVar );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strTou16;

mov( ax, wordVar );

// Same as second example above

static

str1200 :string := "abc1200";

push( str1200 ); // Note that str1200 points at "abc1200".

pushd( 3 ); // Index to "1200" in "abc1200".

call conv.strTou16;

mov( ax, wordVar );

procedure conv.strTou32( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 32-bit unsigned integer. It returns the value (in the range 0..4294967295) in EAX.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strTou32( decValueStr, 0 ); // Index=0 starts at beginning

mov( eax, dwordVar );

// The following demonstrates using a non-zero index:

conv.strTou32( "abc12_345", 3 ); // "12_345" begins at offset 3

mov( eax, dwordVar );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strTou32;

mov( eax, dwordVar );

// Same as second example above

static

str12345 :string := "abc012_345";

push( str12345 ); // Note that str12345 points at "abc-12_345".

pushd( 3 ); // Index to "012_345" in "abc012_345".

call conv.strTou32;

mov( eax, dwordVar ); // dwordVar now contains 12,345.

procedure conv.strTou64( s:string; index:dword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 64-bit unsigned integer. It returns the value (in the range 0.. 18446744073709551615) in EDX:EAX (EDX contains the H.O. dword).

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" to numeric form:

conv.strTou64( decValueStr, 0 ); // Index=0 starts at beginning

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// The following demonstrates using a non-zero index:

conv.strTou64( "a9123", 1 ); // "9123" begins at offset 1

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

HLA low-level calling sequence examples:

push( decValueStr ); // Same as first example above

pushd( 0 );

call conv.strTou64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

// Same as second example above

static

strabc12 :string := "a9123";

push( strabc12 ); // Note that strabc12 points at "a9123".

pushd( 1 ); // Index to "-123" in "a9123".

call conv.strTou64;

mov( eax, (type dword qwordVar[0]) );

mov( edx, (type dword qwordVar[4]) );

procedure conv.strTou128( s:string; index:dword; var dest:lword )

This function converts the sequence of characters starting at zero-based offset index within the string parameter s to a 128-bit unsigned integer. It returns the value (in the range 0.. 340282366920938463463374607431768211456) in the parameter l that you pass by reference to this function.

HLA high-level calling sequence examples:

// The following will convert the characters at the beginning

// of "decValueStr" (index=0) to numeric form and store the

// 128-bit result into the 1wordDest variable:

conv.strTou128( decValueStr, 0, 1wordDest );

// The following demonstrates using a non-zero index:

conv.strTou128( "abc1234567890123456789", 3, 1wordDest );

HLA low-level calling sequence examples:

// Option #1: lwordDest is a STATIC/READONLY/STORAGE

// variable:

push( decValueStr ); // Same as first example above

pushd( 0 );

pushd( &lwordDest );

call conv.strTou128;

// Option #2: lwordDest is not a static object and

// a 32-bit register is available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

lea( eax, lwordDest ); // Assuming EAX is available

push( eax );

call conv.strTou128;

// Option #3: lwordDest is an automatic (var) object and

// no 32-bit registers are available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

push( ebp );

add( @offset( lwordDest ), (type dword [esp]) );

call conv.strTou128;

// Option #4: lwordDest is a complex addressing mode object and

// no 32-bit registers are available for use:

push( decValueStr ); // Same as first example above

pushd( 0 );

sub( 4, esp );

push( eax );

lea( eax, lwordDest );

mov( eax, [esp+4] );

pop( eax );

call conv.strTou128;

Floating Point Conversions

These functions convert betweeen the three IEEE/Intel floating point formats and their string representation. There are two generic classes of these routines: those that convert their values to exponential/scientific notation and those that convert their string to a decimal format.

Note that the floating-point conversions do not insert underscores into the character sequences they produce. Therefore, these conversion functions ignore the internal underscores flag setting. If you wish to produce floating-point strings that have underscores between certain sets of digits, you should call one of these floating-point routines to do the basic conversion and then using other standard library routines to insert those underscores (or other character of your choosing) into the string.

FPU Note: The floating-point routines make use of the 80x86 x87 floating-point unit (FPU). Whenever you call one of these conversion routines, you must ensure that the CPU is operating in FPU mode (rather than MMX mode). If this is not the case, you should exit the MMX mode by executing an EMMS instruction prior to calling any of these conversion routines. As a general rule, you should use the SSE instructions rather than the MMX instructions and leave the CPU in FPU mode. Also note that the floating-point conversion routines make use of the FPU stack (probably as many as three elements, or so, just a guess) so you shouldn’t leave any pending operations on the FPU stack when calling these conversion routines.

Exponential Floating-Point Conversions

The exponential floating-point conversion routines include conv.e32ToBuf, conv.e64ToBuf, conv.e80ToBuf, conv.e32ToStr, conv.e64ToStr, conv.e80ToStr, conv.a_e32ToStr, conv.a_e64ToStr, and conv.a_e80ToStr. The *Buf routines write the converted sequence of characters to memory, starting at the location pointed at by EDI. The *Str routines store the converted character data into a string object.

The routines convert their values to a character sequence using scientific (exponential) notation. These routines each at least two parameters: the value to convert and the field width of the result that control how these functions format the output These routines produce a string with the following format:

The width parameter specifies the exact number of print positions the value will consume (i.e., the length of the resulting string). The first position holds the sign of the value. This is a space for positive values or a minus sign for negative values. If you do not want a leading space in front of positive values you can either store a "+" over the top of this space character (if the number is zero or positive) or you can call str.trim to remove any leading space.

The exponent field (’x’) always uses the minimum number of digits to exactly represent the exponent. If the exponent is non-negative, then these routines preface the value with a ’+’. If the exponent is negative, then these functions preface the exponent value with a ’-’ character.

The minimum field width you should specify is five. This allows one print position for the leading sign character, one digit for the mantissa, the "E", the exponent sign, and one exponent digit. Obviously, values greater than 1E+9 or less than 1E-9 will require additional print positions to handle the additional exponent digits.

The number of fractional digits this routines produce is "(width - 5) - # exponent digits". So you should choose your width according to the expected exponent size and the number of digits you would like to have to the right of the decimal point.

Floating Point Numeric to Buffer Conversions, Exponential Form

The floating point numeric to buffer conversion routines, conv.e32ToBuf, conv.e64ToBuf, and conv.e80ToBuf, translate the three different binary floating point formats to a sequence of characters that they store into sequential memory locations starting at the address held in the EDI register. They return EDI pointing at the first byte beyond the converted sequence. Note that these functions do not zero terminate the string; if you want a zero-terminated string, then store a zero at the byte pointed at by EDI upon return from these functions.

procedure conv.e80ToBuf
(

e80: real80;
width: uns32;
var buffer: var in EDI
)

This function converts the 80-bit extended precision e80 value to its character representation using exponential/scientific notation. This function stores the resulting conversion starting at the address specified in EDI. It is the caller’s responsibility to ensure that sufficient memory is avaiable at this starting address. On return, EDI will point at the first byte beyond the convered string. Note that the 80-bit extended precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits.

procedure conv.e64ToBuf
(

e64: real64;
width: uns32;
var buffer: var in EDI
)

This function converts the 64-bit extended precision e64 value to its character representation using exponential/scientific notation. This function stores the resulting conversion starting at the address specified in EDI. It is the caller’s responsibility to ensure that sufficient memory is avaiable at this starting address. On return, EDI will point at the first byte beyond the convered string. Note that the 64-bit extended precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits.

procedure conv.e32ToBuf
(

e32: real32;
width: uns32;
var buffer: var in EDI
)

This function converts the 32-bit extended precision e32 value to its character representation using exponential/scientific notation. This function stores the resulting conversion starting at the address specified in EDI. It is the caller’s responsibility to ensure that sufficient memory is avaiable at this starting address. On return, EDI will point at the first byte beyond the convered string. Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

Floating Point Numeric to String Conversions, Exponential Form

The floating point numeric to string conversion routines translate the three different binary floating point formats to their string representation. The standard ("unadorned") functions store the string data into a string object that you pass as a parameter to the function. That string object must be preallocated and large enough to receive the string result (else a string overflow occurs). The "adorned" functions, whose names begin with "a_" automatically allocate storage on the heap, store the converted string into that heap object, and then return a pointer to the newly allocated string in the EAX register (it is the caller’s responsibility to free the storage when it is no longer needed).

procedure conv.e80ToStr
(

e80: real80;
width: uns32;
buffer: string
)

This function converts the 80-bit extended precision e80 value to its string representation using exponential/scientific notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 80-bit extended precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits.

procedure conv.e64ToStr
(
e64: real64;
width: uns32;
buffer: string
)

This function converts the 64-bit double precision e64 value to its string representation using exponential/scientific notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 64-bit double precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits.

procedure conv.e32ToStr
(
e32: real32;
width: uns32;
buffer: string
)

This function converts the 32-bit single precision e32 value to its string representation using exponential/scientific notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

procedure conv.a_e80ToStr
(

e80: real80;
width: uns32
); @returns( "eax" );

This function converts the 80-bit extended precision e80 value to its string representation using exponential/scientific notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it. Note that the 80-bit extended precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits.

procedure conv.a_e64ToStr
(
e64: real64;
width: uns32
); @returns( "eax" );

This function converts the 64-bit double precision e64 value to its string representation using exponential/scientific notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it. Note that the 64-bit double precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits.

procedure conv.a_e32ToStr
(
e32: real32;
width: uns32
); @returns( "eax" );

This function converts the 32-bit single precision e32 value to its string representation using exponential/scientific notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it. Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

Floating Point Numeric to Character Conversions, Decimal Form

Although scientific (exponential) notation is the most general display format for real numbers, real numbers you display in this format are difficult to read. Therefore, the standard library conversions module also provides a set of functions that convert real values to their decimal string equivalent. Although you cannot (practically) use these decimal conversion routines for all real values, they are applicable to a wide variety of common numbers you will use in your programs.

These functions all have at least four parameters: the real value to convert, the width of the converted value, the number of digit positions to the right of the decimal point, and a padding character. These functions convert their values to the following string format:

The width parameter specifies the length of the resulting string. This value must be less than or equal to the destination string’s MaxLength value or these functions will raise an exception. The decimalpts parameter to these functions specify the number of digits to the right of the decimal point. If this parameter contains zero, then these functions display the value as an integer (no fractional digits and no decimal point). If this parameter is non-zero, then these routines produce the specified number of decimal digits along with a decimal point.

The width parameter specifies the total size of the resulting string. If decimalpts is zero, then the width value must be at least one greater than the number of digits that appear to the left of the decimal point (the extra position is for the sign character. If the decimalpts parameter is non-zero, then width must be at least (decimalpts + 2 + # integer digits ). If width is not sufficiently large, then these functions produce a string containing width "#" characters to denote a conversion error.

If the width value is sufficiently large and the decimalpts sufficiently small then these routines will fill the extra print positions using the fill character you pass as a parameter. For example, if you convert the value -1.5 with a width of six, a decimalpts value of two, and a fill character of "*" these routines produce the string "*-1.50".

The floating point numeric to buffer conversion routines, conv.r32ToBuf, conv.r64ToBuf, and conv.r80ToBuf, translate the three different binary floating point formats to a sequence of characters that they store into sequential memory locations starting at the address held in the EDI register. They return EDI pointing at the first byte beyond the converted sequence. Note that these functions do not zero terminate the string; if you want a zero-terminated string, then store a zero at the byte pointed at by EDI upon return from these functions.

procedure conv.r80ToBuf
(

r80: real80;
width: uns32;
decimalpts: uns32;
fill: char;
var buffer: var in edi
)

This function converts the 80-bit extended precision r80 value to its string representation using decimal notation. This function stores the resulting character sequence into sequential memory locations starting at the address held in the EDI register. They return EDI pointing at the first byte beyond the converted sequence. Note that these functions do not zero terminate the string; if you want a zero-terminated string, then store a zero at the byte pointed at by EDI upon return from these functions. Note that the 80-bit single precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.r64ToBuf
(
r64: real64;
width: uns32;
decimalpts: uns32;
fill: char;
var buffer: var in edi
)

This function converts the 64-bit double precision r64 value to its string representation using decimal notation. This function stores the resulting character sequence into sequential memory locations starting at the address held in the EDI register. They return EDI pointing at the first byte beyond the converted sequence. Note that these functions do not zero terminate the string; if you want a zero-terminated string, then store a zero at the byte pointed at by EDI upon return from these functions. Note that the 64-bit single precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.r32ToBuf
(

r32: real32;
width: uns32;
decimalpts: uns32;
fill: char;
var buffer: var in edi
)

This function converts the 32-bit single precision r32 value to its string representation using decimal notation. This function stores the resulting Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

Floating-Point Numeric to String Conversions, Decimal Form

procedure conv.r80ToStr
(

r80: real80;
width: uns32;
decimalpts: uns32;
fill: char;
buffer: string
)

This function converts the 80-bit extended precision r80 value to its string representation using decimal notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 80-bit single precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.r64ToStr
(
r64: real64;
width: uns32;
decimalpts: uns32;
fill: char;
buffer: string
)

This function converts the 64-bit double precision r64 value to its string representation using decimal notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 64-bit single precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.r32ToStr
(
r32: real32;
width: uns32;
decimalpts: uns32;
fill: char;
buffer: string
)

This function converts the 32-bit single precision r32 value to its string representation using decimal notation. This function stores the resulting string in the buffer variable whose MaxLength field must be at least width or this function will raise an exception. Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

procedure conv.a_r80ToStr
(
r80: real80;
width: uns32;
decimalpts: uns32;
fill: char
); @returns( "eax" );

This function converts the 80-bit extended precision r80 value to its string representation using decimal notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it.. Note that the 80-bit single precision format supports approximately 18 decimal digits of precision. Therefore, any digits beyond the 18th significant digit will contain garbage. Hence, your choice of width should not produce more than 18 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.a_r64ToStr
(
r64: real64;
width: uns32;
decimalpts: uns32;
fill: char
); @returns( "eax" );

This function converts the 64-bit double precision r64 value to its string representation using decimal notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it. Note that the 64-bit single precision format supports approximately 15 decimal digits of precision. Therefore, any digits beyond the 15th significant digit will contain garbage. Hence, your choice of width should not produce more than 15 mantissa digits. Do keep in mind that the average person has trouble comprehending value with more than six or seven digits. For values that are routinely outside this range you may want to use exponential form to display the number with a limited number of significant digits.

procedure conv.a_r32ToStr
(
r32: real32;
width: uns32;
decimalpts: uns32;
fill: char
); @returns( "eax" );

This function converts the 32-bit single precision r32 value to its string representation using decimal notation. This function stores the resulting string in storage it allocates on the heap and returns a pointer to that string in the EAX register. It is the caller’s responsibility to deallocate this storage when they are done with it. Note that the 32-bit single precision format supports approximately 6-7 decimal digits of precision. Therefore, any digits beyond the seventh significant digit will contain garbage. Hence, your choice of width should not produce more than seven mantissa digits.

Floating Point String/Buffer to Numeric Conversions

The floating-point string to numeric routines convert characters found in a character sequence to an 80-bit IEEE floating-point format. There are two versions – conv.atof and conv.strToFlt. conv.atof operates on an arbitrary sequence of characters in memory and conv.strToFlt operates on a string variable.

These routines will skip over any leading underscore and delimiter characters (specified by the internal delimiters character set, see the discussion of conv.setDelimiters and conv.getDelimiters for details). These functions will convert all characters in the sequence until encountering an illegal floating-point character (decimal digits, a decimal point, ‘e’ or ‘E’, and an optional sign for the exponent and mantissa). If the first non-acceptable character is not the end of string or a delimiter character, these functions will raise a conversion exception. If the character is not a valid 7-bit ASCII character, these functions will raise an illegal character exception.

The conv.strToFlt functions has two parameters: a string object and an index into that string. Numeric conversion because at the zero-based character position specified by the index parameter. For example, the invocation

conv.strToFlt( someStr, 5 );

These functions always convert their strings to an 80-bit floating-point value and leave that value sitting on the top of the FPU stack (ST0). If you want the conversion to a 32-bit or 64-bit floating-point format, then use the fstp instruction to store the result in whatever destination format you desire (real32, real64, or real80).

procedure conv.atof( bufptr: dword in esi ); @returns( "st0" );

This routine assumes that ESI is pointing at a sequence of characters that represents a floating point number. The characters are converted to numeric form and the result is returned in ST0. ESI is left pointing at the first character beyond the converted characters. This function raises an exception if the value begins with something other than a standard numeric, ‘-‘, or delimiter character or ends with something other than a standard delimiter character (or the end of string).

This routine accepts floating point input in either decimal or exponential form.

procedure conv.strToFlt( s:string; index:dword ); @returns( "st0" );

This function converts the sequence of characters starting at position index in s to the equivalent extended precision floating point value and it leaves the result in ST0. This function raises an exception if the value begins with something other than a standard numeric, ‘-‘, or delimiter character, or ends with something other than a standard delimiter character (or the end of string).

This routine accepts floating point input in either decimal or exponential form.

Roman Numeral Conversion

procedure conv.roman( Arabic:uns32; rmn:string )

This procedure converts the specified integer value (Arabic) into a string that contains the Roman numeral representation of the value. Note that this routine only converts integer values in the range 1..3,999 to Roman numeral form. Since ASCII text doesn’t allow overbars (that multiply roman digits by 1,000), this function doesn’t handle really large Roman numbers. A different character set would be necessary for that.

conv.a_roman( Arabic:uns32 )

Just like the routine above, but this one allocates storage for the string and returns a pointer to the string in the EAX register.

Coroutines Module (coroutines.hhf)

HLA provides a powerful coroutines class that lets you easily use coroutines in your programs. The coroutine class provides three procedures and methods you can use to initialize a coroutine, transfer control between coroutines, and free up the storage associated with a coroutine when it completes execution. The coroutine class also has several data fields, but you should treat these as private fields and never disturb their values.

In addition to these class procedures and methods, the coroutine package provides a coret procedure that is useful for returning from a coroutine to whomever "cocalled" the coroutine. This makes it very easy to implement Generators using coroutines.

Finally, the coroutine module provides a special coroutine variable, mainPgm, that you can use to cocall the "coroutine" corresponding to the main HLA program.

The Coroutine Module

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

#include( "coroutines.hhf" )

#include( "stdlib.hhf" )

The Coroutine Class Definition

Here’s the definition of the coroutine class data type:

// Note: the original declaration was "coroutine"

// but this has been deprecated. The following text

// equate is for legacy code. Someday, this declaration

// will go away.

const

coroutine :text := "coroutine_t";

type

coroutine_t:

class

var

CurrentSP: dword;

Stack: dword;

ExceptionContext: dword;

LastCaller: dword;

procedure cocall;

@external( "COR_COCALL" );

procedure create( size:uns32; theProc:procedure );

@external( "COR_CREATE" );

method cofree;

@external( "COR_COFREE" );

endclass;

The data fields are all private fields to this class, your applications should not modify these fields. In addition to the two procedures and the method in this class, the coroutines.hhf header file also defines a single external procedure and an external coroutine variable:

procedure coret; @external( "COR_CORET" );

static

mainPgm_coroutine:coroutine_t; @external( "MainPgmCoroutine__hla_" );

Coroutine Functions

procedure coroutine_t.create( size:uns32; theProc:procedure );

coroutine_t.create is the typical HLA class constructor for the coroutine class. Since this is a class procedure, you can call create one of two different ways:

(1) You can call it via the statement "coroutine_t.create( size, proc);" This form assumes that you wish to create a dynamic coroutine object on the heap. When called this way, the coroutine_t.create procedure allocates storage for a coroutine object on the heap and returns a pointer to this new coroutine object in the ESI register. Otherwise it behaves identically to the second form of the coroutine_t.create procedure.

(2) You can call coroutine_t.create using an invocation of the form "objectName.create( size, proc);" where "objectName" is the name of a coroutine_t variable or a pointer to a coroutine_t object (that, presumably, has been initialized with a valid pointer to a coroutine_t object). Do be aware that this form of the call loads ESI with the address of the coroutine_t object. On return, ESI will contain this new value.

Either form of the call to create will initialize the coroutine_t object, allowing subsequent cocalls to the coroutine_t object.

Coroutines execute using their own stack (independent of other coroutine stacks and independent of the stack the main program uses). The size parameter specifies the number of bytes of stack space to reserve for the coroutine. A good minimum value for a coroutine stack is between 256 and 1,024 bytes. If the coroutine allocates lots of local/automatic variables, or calls other procedures that allocate lots of local/automatic storage, you will need to allocate a larger stack as appropriate. Likewise, if your coroutine calls procedures that are recursive, additional stack space may be necessary.

The theProc parameter is a pointer to a procedure. This procedure is the code that will execute when you cocall this coroutine. The only thing special about the procedure is that it should never be possible to return to the procedure’s caller by executing a RET instruction. You exit coroutine using the coroutine_t.cocall procedure or the coroutine_t.coret procedure. If your code accidentally "falls off the end of the procedure" or otherwise attempts to return to the caller via a RET instruction, the coroutine will go into a special state in which any attempt to cocall it forces an immediate return by the coroutine to the cocaller.

Object declarations for examples:

static

ptrToCoroutine :pointer to coroutine;

staticCoroutine :coroutine_t;

HLA high-level calling sequence examples:

coroutine_t.create( 1024, &myCoroutineProc );

mov( esi, ptrToCoroutine );

staticCoroutine.create( 1024, &anotherProc );

HLA low-level calling sequence examples:

pushd( 1024 );

pushd( &myCoroutineProc );

mov( NULL, esi ); // Tells create to allocate storage

call coroutine_t.create;

mov( esi, ptrToCoroutine );

pushd( 1024 );

pushd( &anotherProc );

lea( esi, staticCoroutine );

call coroutine.create;

procedure coroutine_t.cocall();

coroutine_t.cocall is the mechanism you use to invoke a coroutine. Note that this is a procedure for performance reasons. You should never invoke the static procedure coroutine_t.cocall as this will raise a run-time exception. Instead, you should always invoke this procedure using an object invocation of the form "objectName.cocall();" This will switch the thread of execution from the current coroutine (or the main program) to the coroutine code associated with "objectName". Note that coroutines rarely begin execution at the first statement of the procedure associated with the coroutine (in fact, this happens exactly once, when you invoke the coroutine for the very first time).

The cocall mechanism provides the standard way of leaving a coroutine. Cocalling some other coroutine switches the execution context from the current coroutine to that other coroutine. The next time some code cocalls a coroutine that leaves via cocall, execution continues with the first statement following the cocall (it’s almost as though you had called that other coroutine using a CALL instruction).

HLA high-level calling sequence examples:

ptrToCoroutine.cocall();

staticCoroutine.cocall();

HLA low-level calling sequence examples:

mov( ptrToCoroutine, esi );

call coroutine_t.cocall;

lea( esi, staticCoroutine );

call coroutine_t.cocall;

method coroutine_t.cofree();

When you are done with a coroutine, you should call the coroutine_t.cofree method to free up the stack space associated with that coroutine. You must not call coroutine_t.cofree from inside the coroutine you’re cleaning up since it still needs its stack to transfer control to some other coroutine.

HLA high-level calling sequence examples:

ptrToCoroutine.cofree();

staticCoroutine.cofree();

HLA low-level calling sequence examples:

mov( ptrToCoroutine, esi );

mov( [esi], edi );

call( [edi+@offset(coroutine_t.cofree)] );

lea( esi, staticCoroutine );

mov( [esi], edi );

call( [edi+@offset(coroutine_t.cofree)] );

method coret();

coret is nearly identical to coroutine_t.cocall with two major exceptions. First, note that this procedure is not a member of the coroutine_t class. Therefore, you do not specify an object name in front of the call to the coret procedure. Second, coret returns control to whomever cocalled the current coroutine. The current coroutine does not have to know who called it; coret figures this out and cocalls the appropriate coroutine.

Note that coret is not a "return" in the usual sense that the coroutine completes execution upon calling coret. coret is identical to a coroutine_t.cocall to the coroutine that called the current coroutine. In particular, after a coroutine returns to another, any future cocalls to this coroutine will continue execution with the first statement following the coret call.

HLA high-level calling sequence examples:

coret();

HLA low-level calling sequence examples:

call coret;

static mainPgm:coroutine_t;

This is a special coroutine_t variable that contains the control information for the main program. If, inside a coroutine, you wish to cocall the main program, just use a cocall of the form "MainPgm.cocall();" and control in the main program will continue at the point of the last cocall executed in the main program. (Note: the term "main program" here does not imply that the cocall has to be in the actual main program of an HLA program, it simply refers to the thread of execution that starts in the main program. Your main program can call a procedure that transfers control to some coroutine via cocall. MainPgm.cocall will transfer control back into that procedure.)

Character Sets (cset.hhf)

The HLA Standard Library contains several routines that provide the power of the HLA compile-time character set facilities at run-time (i.e., within your programs).

HLA uses a 128-bit bitmap (16 consecutive bytes) to implement sets of seven-bit ASCII characters. This has a very important implication: you cannot pass byte values greater than $7F to a character set function. Currently, the HLA Standard Library routines do not check for values out of range (for performance reasons). In the future, this checking may be added as a compilable option. For the time being, however, it is your responsibility to verify that all character values are in the range #$0..#$7F (and, in general, #$0 is an exceeding bad value to specify in many cases since the null character terminates strings).

The bitmap consists of 128 consectutive bits numbered 0..127. If a bit in a character set is one, then the corresponding character (whose ASCII code matches the bit number) is a member of the character set. Conversely, if a bit is zero, the corresponding character is not a member of the set.

Note that many routines pass character sets by value. This means you can pass HLA character set constants as parameters to these procedures/functions. HLA emits four MOV (doubleword) instructions to copy a character set by value, so passing character sets by value is not horribly inefficient (though not quite as fast as a 32-bit integer!).

Warning: All of the character set routines are members of the cs namespace. This means you cannot use the name cs within your programs. ( cs is a common character set name that lazy programmers use; sorry, it’s already been taken!)

The following sections describe each of the character set routines in the HLA Standard Library.

A Note About Thread Safety: The routines in this module are all thread safe.

Predicates (tests)

Although the "returns" value for each of the following functions is "AL", these tests always set EAX to zero or one. Therefore, you may refer to the AL or EAX register after these tests, whichever is more convenient for you. If you use instruction composition and bury one of these function calls in another statement, that statement will use the AL register as the operand.

Note that these functions generally pass their character set parameters by value. This involves pushing 16 bytes on the stack for each cset parameter (typically four push instructions). Keep this in mind if efficiency is your utmost concern. Be sure to read the section on "Passing CSET Parameters on the Stack" in the chapter on "Passing Parameters to Standard Library Routines".

procedure cs.IsEmpty( src: cset ); @returns( "AL" );

This function returns true (1) in the AL register if the specified character set is empty (has no members). It returns false (0) in AL/EAX otherwise.

HLA high-level calling sequence examples:

cs.IsEmpty( csetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

// cs.IsEmpty is really intended to be used as a high-level

// type function. It’s actually just as easy to compute the

// function manually as it is to call it. Here’s the low-level

// calling sequence:

push( (type dword csetVar[12]));

push( (type dword csetVar[8]));

push( (type dword csetVar[4]));

push( (type dword csetVar[0]));

call cs.IsEmpty;

mov( al, booleanResult;

// Here’s the same thing using bare machine instructions:

mov( (type dword csetVar[0]), eax );

or( (type dword csetVar[4]), eax );

or( (type dword csetVar[8]), eax );

or( (type dword csetVar[12]), eax );

setz( al );

mov( al, booleanResult );

procedure cs.member( c:char; theSet:cset ); @returns( "AL" );

This function returns true (1) or false (0) in AL/EAX if the specified character is a member of the specified character set.

HLA high-level calling sequence examples:

cs.member( charVar, csetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

// cs.member is really intended to be used as a high-level

// type function. It’s actually just as easy to compute the

// function manually as it is to call it. Here’s the low-level

// calling sequence:

movzx( charVar, eax );

push( eax );

push( (type dword csetVar[12]));

push( (type dword csetVar[8]));

push( (type dword csetVar[4]));

push( (type dword csetVar[0]));

call cs.member;

mov( al, booleanResult;

// Here’s the same thing using bare machine instructions:

movzx( charVar, eax );

bt( eax, csetVar );

setc( al );

mov( al, booleanResult );

procedure cs.subset( src1:cset; src2:cset ); @returns( "AL" );

The cs.subset function returns true in AL/EAX if src1 <= src2 (that is, all of src1 ’s members are also members of src2 ).

HLA high-level calling sequence examples:

cs.subset( subsetVar, supersetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword subsetVar[12]));

push( (type dword subsetVar[8]));

push( (type dword subsetVar[4]));

push( (type dword subsetVar[0]));

push( (type dword supersetVar [12]));

push( (type dword supersetVar [8]));

push( (type dword supersetVar [4]));

push( (type dword supersetVar [0]));

call cs.subset;

mov( al, booleanResult );

procedure cs.superset( src1:cset; src2:cset ); @returns( "AL" );

The cs.superset function returns true in AL/EAX if src1 >= src2 (that is, all of src2 ’s members are members of src1 ).

HLA high-level calling sequence examples:

cs.superset( supersetVar, subsetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword supersetVar[12]));

push( (type dword supersetVar[8]));

push( (type dword supersetVar[4]));

push( (type dword supersetVar[0]));

push( (type dword subsetVar[12]));

push( (type dword subsetVar[8]));

push( (type dword subsetVar[4]));

push( (type dword subsetVar[0]));

call cs.superset;

mov( al, booleanResult );

procedure cs.psubset( src1:cset; src2:cset ); @returns( "AL" );

The cs.psubset (proper subset) function returns true in AL/EAX if src1 < src2 (that is, all of src1 ’s members are members of src2 but src1 <> src2 ).

HLA high-level calling sequence examples:

cs.psubset( subsetVar, supersetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword subsetVar[12]));

push( (type dword subsetVar[8]));

push( (type dword subsetVar[4]));

push( (type dword subsetVar[0]));

push( (type dword supersetVar [12]));

push( (type dword supersetVar [8]));

push( (type dword supersetVar [4]));

push( (type dword supersetVar [0]));

call cs.psubset;

mov( al, booleanResult );

procedure cs.psuperset( src1:cset; src2:cset ); @returns( "AL" );

The cs.spsuperset (proper superset) function returns true in AL/EAX if src1 > src2 (that is, all of src2 ’s members are members of src1 but src2 <> src1 ).

HLA high-level calling sequence examples:

cs.psuperset( supersetVar, subsetVar );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword supersetVar[12]));

push( (type dword supersetVar[8]));

push( (type dword supersetVar[4]));

push( (type dword supersetVar[0]));

push( (type dword subsetVar[12]));

push( (type dword subsetVar[8]));

push( (type dword subsetVar[4]));

push( (type dword subsetVar[0]));

call cs.psuperset;

mov( al, booleanResult );

procedure cs.eq( src1:cset; src2:cset ); @returns( "AL" );

The cs.eq function compares the two sets and returns true/false in AL/EAX; true if the two sets are equal, false if they are not.

HLA high-level calling sequence examples:

cs.eq ( src1, src2 );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword src1[12]));

push( (type dword src1[8]));

push( (type dword src1[4]));

push( (type dword src1[0]));

push( (type dword src2[12]));

push( (type dword src2[8]));

push( (type dword src2[4]));

push( (type dword src2[0]));

call cs.eq ;

mov( al, booleanResult );

procedure cs.ne( src1:cset; src2:cset ); @returns( "AL" );

The cs.eq function compares the two sets and returns true/false in AL/EAX; true if the two sets are not equal, false if they are equal.

HLA high-level calling sequence examples:

cs.ne ( src1, src2 );

mov( al, booleanResult );

HLA low-level calling sequence examples:

push( (type dword src1[12]));

push( (type dword src1[8]));

push( (type dword src1[4]));

push( (type dword src1[0]));

push( (type dword src2[12]));

push( (type dword src2[8]));

push( (type dword src2[4]));

push( (type dword src2[0]));

call cs.ne ;

mov( al, booleanResult );

Character Set Construction and Manipulation

The functions in this group create character set objects, extract data from character set objects, or transfer data between character set objects.

procedure cs.empty( var dest:cset );

This function clears all the bits in a character set to create the empty set. Note that the single character set parameter is passed by reference.

HLA high-level calling sequence examples:

cs.empty ( csetVar );

HLA low-level calling sequence examples:

// cset_s is a variable declared in the static/storage section:

pushd( &cset_s );

call cs. empty ;

// cset_v is a variable declared in the var section or

// is a parameter:

lea( eax, cset_v );

push( eax );

call cs. empty ;

// Alternative call passing cset_v if no 32-bit registers

// are available (this code assumes that EBP points at the current

// activation record/stack frame that contains cset_v):

push( ebp );

add( @offset( cset_v ), (type dword [esp] ));

call cs. empty ;

// Low-level call assuming a 32-bit register (esi in this case)

// contains the address of the cset:

push( esi );

call cs. empty ;

// Low-level call assuming a dword or pointer variable contains the

// address of the cset that will receive the delimiter character set:

push( ptrToDelims );

call cs. empty ;

procedure cs.cpy( src:cset; var dest:cset );

This routine copies the data from the source character set ( src ) to the destination character set ( dest ). Note that the dest set is passed by reference. Although this routine is convenient, you should consider writing a macro to do this same function (copy 16 bytes from src to dest ) if you call this function in time critical sections of your code.

HLA high-level calling sequence examples:

cs.cpy ( csetSrc, csetDest );

cs.cpy( {‘a’..’z’}, lowerCaseCset );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( (type dword csetSrc_s[12]));

push( (type dword csetSrc_s[8]));

push( (type dword csetSrc_s[4]));

push( (type dword csetSrc_s[0]));

pushd( &csetDest_s );

call cs. cpy ;

// csetDest_v is a variable declared in the var section or

// is a parameter:

push( (type dword csetSrc_v[12]));

push( (type dword csetSrc_v[8]));

push( (type dword csetSrc_v[4]));

push( (type dword csetSrc_v[0]));

lea( eax, csetDest_v );

push( eax );

call cs. cpy ;

// Alternative call passing csetDest_v if no 32-bit registers

// are available (this code assumes that EBP points at the current

// activation record/stack frame that contains csetDest_v):

push( (type dword csetSrc_v[12]));

push( (type dword csetSrc_v[8]));

push( (type dword csetSrc_v[4]));

push( (type dword csetSrc_v[0]));

push( ebp );

add( @offset( csetDest_v ), (type dword [esp] ));

call cs. cpy ;

// Low-level call assuming a 32-bit register (edi in this case)

// contains the address of the destination cset:

push( (type dword csetSrc_v[12]));

push( (type dword csetSrc_v[8]));

push( (type dword csetSrc_v[4]));

push( (type dword csetSrc_v[0]));

push( edi );

call cs. cpy ;

// Low-level call assuming a dword or pointer variable contains the

// address of the destination cset:

push( (type dword csetSrc[12]));

push( (type dword csetSrc[8]));

push( (type dword csetSrc[4]));

push( (type dword csetSrc[0]));

push( ptrTodest );

call cs. cpy ;

procedure cs.charToCset( c:char; var dest:cset );

The cs.charToCset procedure takes the character passed as a parameter and creates a singleton set containing that character (a singleton is a set with exactly one member). The resulting set is stored into the destination parameter (which is passed by reference).

HLA high-level calling sequence examples:

cs.charToCset ( ‘c’, csetDest );

cs. charToCset ( charVar, lowerCaseCset );

cs. charToCset ( (type char [esi]), (type cset [edi]));

HLA low-level calling sequence examples:

// The following low-level examples all assume that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

// Passing a single character constant:

pushd( ‘c’ );

pushd( &csetDest_s );

call cs. charToCset ;

// Passing a character variable, assuming a 32-bit register is

// available or one of the 8-bit register: AL, BL, CL, or DL

mov( charVar, al );

push( eax );

pushd( &csetDest_s );

call cs. charToCset ;

// If the character variable is guaranteed not to be in the last

// three bytes of allocated storage, you could also do this:

push( type dword charVar );

pushd( &csetDest_s );

call cs. charToCset ;

// If the character is in one of the 8-bit registers: AH, BH, CH, DH

sub( 4, esp );

mov( ah, [esp] );

pushd( &csetDest_s );

call cs. charToCset ;

procedure cs.rangeChar( first:char; last:char; var dest:cset );

This function creates a set whose member range between the first character specified and the last character specified. For example, cs.rangeChar ( ’A’, ’Z’, UpperCaseSet) will create a character set whose members are the upper case alphabetic characters. Any previous members in the destination set are lost.

HLA high-level calling sequence examples:

cs.rangeChar ( ‘a’, ‘z’, csetDest );

cs. rangeChar ( charVar, endCharVal, lowerCaseCset );

cs. rangeChar ( (type char [esi]), ‘0’, (type cset [edi]));

HLA low-level calling sequence examples:

// The following low-level examples all assume that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

// Also note that both the "first" and "last" parameters are

// character objects that you pass the same way. For brevity,

// the following examples only demonstrate variations on the

// "first" parameter; the same principles apply to the "last"

// parameter.

// Passing two character constants:

pushd( ‘a’ );

pushd( ‘z’ );

pushd( &csetDest_s );

call cs. rangeChar ;

// Passing a character variable, assuming a 32-bit register is

// available or one of the 8-bit register: AL, BL, CL, or DL

mov( charVar, al );

push( eax );

pushd( ‘z’ );

pushd( &csetDest_s );

call cs. rangeChar ;

// If the "first" character variable is guaranteed not to be in the

// last three bytes of allocated storage, you could also do this:

push( type dword charVar );

pushd( ‘z’ );

pushd( &csetDest_s );

call cs. rangeChar ;

// If the "first" character is in one of the 8-bit

// registers: AH, BH, CH, DH

sub( 4, esp );

mov( ah, [esp] );

pushd( ‘z’ );

pushd( &csetDest_s );

call cs. rangeChar ;

procedure cs.strToCset( s:string; var dest:cset );

This function first sets the destination character set to the empty set. Then it "unions in" all the characters found in the string parameter to the destination set.

HLA high-level calling sequence examples:

cs.strToCset ( strSrc, csetDest );

cs. strToCset ( "ABCDEFabcdef", hexCset );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( &csetDest_s );

call cs.strtoCset;

// You could pass a string literal thusly (though there is

// no benefit to doing this over creating a statically

// initialized string variable and passing that string variable).

lea( eax, "abcdefABCDEF" );

push( eax );

pushd( &csetDest_s );

call cs.strtoCset;

procedure cs.strToCset2( s:string; offs:uns32; var dest:cset );

This function first sets the destination character set to the empty set. Then it "unions in" all the characters starting at offset offs in the string parameter to the destination character set.

HLA high-level calling sequence examples:

cs.strToCset2 ( strSrc, 2, csetDest );

cs. strToCset2 ( "ABCDEF", offsetIntoStr, partialHexCset );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( 2 )

pushd( &csetDest_s );

call cs. strToCset2 ;

// Assume the offset is in the variable "offsetIntoStr":

push( strSrc );

push( offsetIntoStr );

pushd( &csetDest_s );

call cs. strToCset2 ;

procedure cs.extract( var dest:cset ); @returns( "EAX" );

This function removes a single character from the character set and returns that character in the AL register. Currently, this function removes characters by order of their ASCII character codes (that is, each call returns the character in the set with the lowest ASCII code). However, you should not make this assumption. You should assume that this function could return the characters in an arbitrary order. If the specified character set is empty, this routine returns -1 ($FFFF_FFFF) in the EAX register; in all other cases the H.O. three bytes of EAX contain zero upon return.

Note: unlike the HLA compile-time function "@extract", this function actually removes the character from the character set ("@extract" leaves the character in the set). Keep this in mind. (In the future, the name of the HLA @extract function will probably be changed to something else to clean up this conflict.)

HLA high-level calling sequence examples:

cs.extract ( csetVar );

if( eax <> -1 ) then

mov( al, charExtracted );

endif;

HLA low-level calling sequence example:

// The following low-level example assumes that cset_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

pushd( &cset_s );

call cs. extract ;

cmp( eax, -1 );

je noCharExtracted;

mov( al, charExtracted;

noCharExtracted:

Set Operations

The following set functions perform what is generally considered to be set arithmetic: operations like set union, intersection, difference, and so on.

procedure cs.setunion( src:cset; var dest:cset );

This function computes the union of two sets, storing the result back into the destination set. Note that the destination set parameter is passed by reference.

Note: The name " setunion " was used rather than the more obvious choice of "union" because "union" is an HLA reserved word.

HLA high-level calling sequence examples:

cs.setunion ( csetSrc, csetDest );

cs. setunion ( {‘a’..’z’}, lowerCaseUnion );

HLA low-level calling sequence example:

// The following low-level example assumes that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

push( (type dword csetSrc_s[12]));

push( (type dword csetSrc_s[8]));

push( (type dword csetSrc_s[4]));

push( (type dword csetSrc_s[0]));

pushd( &csetDest_s );

call cs. setunion ;

procedure cs.intersection( src:cset; var dest:cset );

This function computes the set intersection of the two sets passed as parameters and stores the result back into the destination set. Note that the dest parameter is passed by reference.

HLA high-level calling sequence examples:

cs. intersection( csetSrc, csetDest );

cs.intersection( {‘a’..’z’}, lowerCaseUnion );

HLA low-level calling sequence example:

// The following low-level example assumes that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

push( (type dword csetSrc_s[12]));

push( (type dword csetSrc_s[8]));

push( (type dword csetSrc_s[4]));

push( (type dword csetSrc_s[0]));

pushd( &csetDest_s );

call cs.intersection;

procedure cs.difference( src:cset; var dest:cset );

This function computes the set difference of two sets (i.e., the members in the destination set that are not also members of the source set). It stores the result back into the dest set (which is passed by reference).

HLA high-level calling sequence examples:

cs. difference( csetSrc, csetDest );

cs.difference( {‘a’..’z’}, csetWithoutLowerCase );

HLA low-level calling sequence example:

// The following low-level example assumes that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

push( (type dword csetSrc_s[12]));

push( (type dword csetSrc_s[8]));

push( (type dword csetSrc_s[4]));

push( (type dword csetSrc_s[0]));

pushd( &csetDest_s );

call cs.difference;

procedure cs.complement( src:cset; var dest:cset );

This function computes the set complement of a set (i.e., the members in the destination set are those elements that are not in the source set.). It stores the complemented version of the set in the destination operand (which is passed by reference).

HLA high-level calling sequence examples:

cs. complement( csetSrc, negatedCsetDest );

cs.complement( {‘a’..’z’}, allButLowercase );

HLA low-level calling sequence example:

// The following low-level example assumes that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

push( (type dword csetSrc_s[12]));

push( (type dword csetSrc_s[8]));

push( (type dword csetSrc_s[4]));

push( (type dword csetSrc_s[0]));

pushd( &csetDest_s );

call cs.complement;

procedure cs.unionChar( c:char; var dest:cset );

The cs.unionChar function adds the character (supplied as a parameter) to the specified destination character set (passed by reference). If the character was already a member of the set, this function does not affect the character set.

HLA high-level calling sequence examples:

cs. unionChar( ‘c’, csetDest );

cs.unionChar( charVar, lowerCaseCset );

cs.unionChar( (type char [esi]), (type cset [edi]));

HLA low-level calling sequence examples:

// The following low-level examples all assume that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

// Passing a single character constant:

pushd( ‘c’ );

pushd( &csetDest_s );

call cs.unionChar;

// Passing a character variable, assuming a 32-bit register is

// available or one of the 8-bit register: AL, BL, CL, or DL

mov( charVar, al );

push( eax );

pushd( &csetDest_s );

call cs.unionChar;

// If the character variable is guaranteed not to be in the last

// three bytes of allocated storage, you could also do this:

push( type dword charVar );

pushd( &csetDest_s );

call cs.unionChar;

// If the character is in one of the 8-bit registers: AH, BH, CH, DH

sub( 4, esp );

mov( ah, [esp] );

pushd( &csetDest_s );

call cs.unionChar;

procedure cs.removeChar( c:char; var dest:cset );

This function removes a single character from the specified destination set (passed by reference). If the character was not previously a member of the destination set, this function does not affect that set.

HLA high-level calling sequence examples:

cs. removeChar( ‘c’, csetDest );

cs.removeChar( charVar, lowerCaseCset );

cs.removeChar( (type char [esi]), (type cset [edi]));

HLA low-level calling sequence examples:

// The following low-level examples all assume that csetDest_s is

// a statically-declared object (static or storage section). For

// examples of additional ways to pass the destination cset by

// reference, please see the examples for cs.cpy given earlier.

// Passing a single character constant:

pushd( ‘c’ );

pushd( &csetDest_s );

call cs.removeChar;

// Passing a character variable, assuming a 32-bit register is

// available or one of the 8-bit register: AL, BL, CL, or DL

mov( charVar, al );

push( eax );

pushd( &csetDest_s );

call cs.removeChar;

// If the character variable is guaranteed not to be in the last

// three bytes of allocated storage, you could also do this:

push( type dword charVar );

pushd( &csetDest_s );

call cs.removeChar;

// If the character is in one of the 8-bit registers: AH, BH, CH, DH

sub( 4, esp );

mov( ah, [esp] );

pushd( &csetDest_s );

call cs.removeChar;

procedure cs.unionStr( s:string; var dest:cset );

This function will union in all the characters in a string to the destination set. Unlike the cs.strToCset function, this function does not clear the destination character set before processing the characters in the string.

HLA high-level calling sequence examples:

cs. unionStr( strSrc, csetDest );

cs.unionStr( "ABCDEFabcdef", csetPlusHexChars );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( &csetDest_s );

call cs.unionStr;

// You could pass a string literal thusly (though there is

// no benefit to doing this over creating a statically

// initialized string variable and passing that string variable).

lea( eax, "abcdefABCDEF" );

push( eax );

pushd( &csetDest_s );

call cs.unionStr;

procedure cs.unionStr2( s:string; offs:uns32; offs:uns32; var dest:cset );

This function will union in all the characters in a string to the destination set. Unlike the cs.unionStr function, this function starts at character position offs in s rather than at character position zero.

HLA high-level calling sequence examples:

cs. unionStr2( strSrc, 2, csetDest );

cs.unionStr2( "ABCDEF", offsetIntoStr, partialHexUnion );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( 2 )

pushd( &csetDest_s );

call cs.unionStr2;

// Assume the offset is in the variable "offsetIntoStr":

push( strSrc );

push( offsetIntoStr );

pushd( &csetDest_s );

call cs.unionStr2;

procedure cs.removeStr( s:string; var dest:cset );

This function removes characters found in the string from the specified character set. If a character in the string was not previously a member of the character set, the specified character has no effect on the destination set.

HLA high-level calling sequence examples:

cs. removeStr( strSrc, csetDest );

cs.removeStr( "ABCDEFabcdef", csetMinusHexChars );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( &csetDest_s );

call cs.removeStr;

// You could pass a string literal thusly (though there is

// no benefit to doing this over creating a statically

// initialized string variable and passing that string variable).

lea( eax, "abcdefABCDEF" );

push( eax );

pushd( &csetDest_s );

call cs.removeStr;

procedure cs.removeStr2( s:string; offs:uns32; var dest:cset );

This function removes characters found in the string at character position offs and beyond from the specified character set. If a character in the string was not previously a member of the character set, the specified character has no effect on the destination set.

HLA high-level calling sequence examples:

cs. removeStr2( strSrc, 2, csetDest );

cs.removeStr2( "ABCDEF", offsetIntoStr, csetMinusSomeHexChars );

HLA low-level calling sequence examples:

// csetDest_s is a variable declared

// in the static/storage section:

push( strSrc );

pushd( 2 )

pushd( &csetDest_s );

call cs.removeStr2;

// Assume the offset is in the variable "offsetIntoStr":

push( strSrc );

push( offsetIntoStr );

pushd( &csetDest_s );

call cs.removeStr2;

Date Functions (datetime.hhf)

HLA contains a set of procedures and functions that simplify correct date calculations. There are actually two modules: a traditional set of date functions and, for those who prefer an object-oriented approach, a date class module.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

A Note About Thread Safety: The date and time routines maintain a couple of static global variables that track the output format and output separate characters for dates. Currently, these values apply to all threads in a process. You should take care when changing these values in threads. When the process module is added to the standard library, these values will be placed in a per-thread data structure. Until then, you should set the format/separator character before starting any other threads and avoid changing their values once other threads (that might use the date/time library module) begin execution.

Note about function overloading: the functions in the date/time module use function overloading in order to allow you to specify the parameter lists in different ways. The macro that handles the overloading generally coerces the possible parameter types into a single object that it passes to the underlying function. The documentation for the specific functions will tell you whether a symbol is a macro or a function. For the most part, this should matter to you unless you are taking the address of a function (which you cannot do with a macro). See the HLA documentation for more details on function overloading via macros.

The Date Module

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

#include( "datetime.hhf" )

#include( "stdlib.hhf" )

Date Data Types

The date namespace defines the following useful data types:

date.daterec

Date representation. This is a dword object containing m , d , and y fields holding the obvious values. The y field is a 16-bit quantity supporting years 0..9,999. No Y2K problems here! (Of course, it does suffer from Y10K, but that’s probably okay.) Since the Gregorian calendar began use in Oct, 1582, there is really no need to represent dates any earlier than this. In fact, most date calculations in the HLA stdlib will not allow dates earlier than Jan 1, 1600 for this very reason. The limitation of year 9999 is an arbitrary limit set in the library to help catch wild values. If you really need dates beyond 9999, feel free to modify the date validation code. The m and d fields are both byte objects. The date validation routines enforce the month limits of 1..12 and appropriate day limits (depending on the month and year).

Here is the current data type definition for the daterec data type:

type

daterec:

record

day :uns8;

month :uns8;

year :uns16;

endrecord;

Because of the way the fields are defined, you may compare two dates as 32-bit values and test the result using unsigned conditional branch instructions.

date.outputFormat

This is an enumerated data type that defines the following constants:

mdyy, mdyyyy, mmddyy, mmddyyyy, yymd, yyyymd, yymmdd, yyyymmdd, MONdyyyy , and MONTHdyyyy . These constants control the date output format in the (mostly) obvious way. Note that mdyy can output one digit for the day and month while mmddyy always inputs two digits for each field. The MONdyyyy format outputs dates in the form "Jan 1, 2000" while the MONTHdyyyy outputs the dates using the format "January 1, 2000".

type

OutputFormat:

enum

{

mdyy,

mdyyyy,

mmddyy,

mmddyyyy,

yymd,

yyyymd,

yymmdd,

yyyymmdd,

MONdyyyy,

MONTHdyyyy,

badDateFormat

};

Date Tables

The date/time module includes several date/time-related data objects that may be of interest to an application programmer. Here are the declarations found in the datetime.hhf header file:

DaysToMonth :uns32[13];

DaysInMonth :uns32[13];

DaysFromMonth :uns32[13];

Months :string[13];

shortMonths :string[13];

You must treat these tables as read-only objects. Changing their values will cause the date/time routines to produce incorrect results. Each of these tables is indexed by a month value in the range 1..12. Zero is an illegal value and the value found at index 0 in these tables is undefined. Obviously, accessing any data beyond index 12 is also undefined. The first three functions return some number of days relative to the month whose index you’ve supplied. These day values are relative to the first day of the specified month. The values in these tables are for non-leap years. If your date calculation is for a leap year, you must add one to the value found in these tables, as appropriate for the month you specify; details appear in the discussion of each function.

DaysToMonth contains the number of days from January 1 to the first of the month you specify as the index. For example, index 1 contains zero, index 2 contains 31, index 3 contains 59 (31+28), etc. For leap years, you will need to add one to the table entry if the index is in the range 3..12.

DaysInMonth contains the number of days in the month specified by the index. For example, DaysInMonth[1] contains 31, DaysInMonth[2] contains 28, and DaysInMonth[3] contains 31. For leap years, you need to add one to the value appearing at index 2 (of course, it’s probably just easier to explicitly set the value to 29 for February in leap years).

DaysFromMonth contains the number of days from the first day of the month specified by the index to the first day of January in the following year. For example, DaysFromMonth[1] will contain 365, DaysFromMonth[2] will contain 334 (365-31), and so on. For leap years, you will want to add one to the value if the month index is less than 3.

Months is an array of strings, indexed by the month value, that contain the month’s name. For example, Month[1] is the string "January" and Month[2] is the string "February".

shortMonths is an array of strings that contain shortened versions of the month names (the first three characters of each of the month names found in the Months array).

Date Predicates

The date module provides many functions that test date values. This section details those functions.

#macro date.isLeapYear( y:uns32 ); @returns( "al" );
#macro date.isLeapYear( dr:date.daterec ); @returns( "al" );
procedure date._isLeapYear( Year:word ); @returns( "al" );

This is an overloaded function. You may either pass it an unsigned integer containing the year or a date.daterec value specifying a m/d/y value (the overloading function will simply pick out the year value and pass it on to the underlying date._isLeapYear function). These functions return true or false in the AL register depending upon whether the parameter is a leap year (true if it is a leap year). Note that this function will be correct until sometime between the years 3000 and 4000, at which point people will probably have to agree upon adding an extra leap day in at some point (no such agreement has been made today, hence the absence from this function); currently, HLA date routines do not allow dates beyond the year 2999, so this won’t be a problem unless you modify the maximum year value in the date/time header files. Note that these functions return the boolean result zero-extended into EAX. The @returns("al") declarations exist so that these functions will be type-compatible with boolean objects.

HLA high-level calling sequence examples:

date.isLeapYear( someDateVar );

mov( al, someDateVar_is_leap_year );

if( date.isLeapYear( aYearValue )) then

// Do something if aYearValue is a leap year

endif;

mov( &date._isLeapYear( ebx ), ptrToIsLeapYearFunction );

HLA low-level calling sequence examples:

movzx( someDateVar.year, eax );

push( eax );

call date._isLeapYear;

mov( al, someDateVar_is_leap_year );

movzx( aYearValue, eax );

push( eax );

call date._isLeapYear;

test( al, al );

jz notALeapYear;

// Do something if aYearValue is a leap year

notALeapYear:

#macro date.validate( m:byte; day:byte; year:word );
#macro date.validate( dr:date.daterec );
date._validate( dr:daterec );

These two functions check the date passed as a parameter and raise an ex.InvalidDate exception if the data in the fields (or the m/d/y ) parameter is not a valid date between 1/1/1600 and 12/31/2999.

HLA high-level calling sequence examples:

try

date.validate( someDateVar );

anyexception

// Do something if the date is invalid

endtry;

try

date.validate( someMonth, someDay, someYear );

anyexception

// Do something if the date is invalid

endtry;

try

date._validate( someDateVar );

anyexception

// Do something if the date is invalid

endtry;

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._validate;

#macro date.isValid( m:byte; day:byte; year:word ); @returns( "al" );
#macro date.isValid( dr:date.daterec ); @returns( "al" );
date._isValid( dr:daterec ); @returns( "al" );

Similar to the date.validate procedures, except these functions return true/false in the AL register if the date is valid/invalid. They do not raise an exception. Note that these functions return the boolean result zero-extended into EAX. The @returns("al") declarations exist so that these functions will be type-compatible with boolean objects.

Date Conversions

The functions (and macros) in this category convert dates from one format to another. Specifically, there are conversions to and from Julian day numbers, conversions to days into year, computation of week day (Sunday through Saturday), and conversions to days left in year.

#macro date.pack( m, d, y, dr );

date.pack is a macro that accepts year (y), month (m), and day (d) values (presumably dwords), and a date.daterec (dr) object. It converts the three values to date.daterec form and stores the result in the specified destination. If the y, m, or d values are constants, this macro checks them to ensure they are somewhat reasonable (days are only checked for the range 1..31, years are checked for the range 1600..2999). If m or d are memory objects, then they are coerced to a byte before use. If y is a memory object, it is coerced to a word before use. You may use registers for y, m, and d; if you do, the m and d values must be passed in 8-bit registers and the y value must be passed in a 16-bit register. This macro works best if all three operands are constants. If you take a look at the macro definition in the datetime.hhf header file, you’ll discover that this macro efficiently translates a constant date into a single machine instruction. The macro attempts to generate good code for other operand types, but if efficiency is your primary concern, you may want to consider manually moving the data into the fields of the daterec object if the d, m, and y values are memory operands.

Because this is a macro, there are no parameters passed on the stack (hence, no stack diagram). Do note, however, that this macro preserves the value in EAX on the stack if it needs to use EAX. As such you should not specify an ESP-relative memory operand as one of the parameters to this macro. In some cases the macro will push EAX on the stack during conversion, in other cases it will not. As such, ESP-relative memory addresses may be rendered incorrect when this macro preserves EAX on the stack.

Other than a mild check for constant operands, this macro does not validate the date you pack into the dr argument. No checking is done because this macro is primarily intended for moving constant values into a daterec object (and you should be able to verify the value manually when writing the macro invocation). If you need to verify the date packed into the dr parameter, use the date.validate or date.isValid functions.

Macro invocation example:

date.pack( 6, 21, 2007, drDateVar );

#macro date.unpack( dr, m, d, y );

date.unpack is a macro that accepts a daterec object (dr) and converts this to three dword values (m, d, and y) by zero-extending the values before storing them into the destination locations. The m, d, and y operands must be 32-bit memory locations or registers (except EAX, which this macro uses for the zero extension operation).

Macro invocation example:

date.unpack( drDateVar, monthVar32, dayVar32, yearVar32 );

#macro date.toJulian( m:byte; d:byte; y:word ); @returns( "eax" );
#macro date.toJulian( dr:date.daterec ); @returns( "eax" );
date._toJulian( dr:daterec ); @returns( "eax" );

These functions convert the Gregorian (i.e., standard) date passed as a parameter into a "Julian day number." A Julian day number treats Jan 1, 4713 as day zero and simply numbers dates forward from that point. For example, Oct 9, 1995 is JD 2,450,000. Jan 1, 2000 is JD 2,452,545. Julian dates make date calculations of the form "what date is it X days from now?" trivial. You just compute JD+X to get the new date.

A Julian Day begins at 12:00 noon (compared with Gregorian days, that begin at 12:00 midnight). Because these functions do not have a time parameter, they assume that the time is between 12:00 noon on the specified date you pass as a parameter and 11:59:59 of the next day. If the current time is before 12:00 noon, you should subtract one from the Julian day number these functions return. If you would like a true ‘toJulian’ function, you can easily write one thusly:

procedure toJulian( dr:date.daterec; tm:time.timerec );

begin toJulian;

date.toJulian( dr );

if( tm.hour < 12 ) then

dec( eax );

endif;

end toJulian;

date.toJulian is actual a macro that handles the parameter overloading. It reformats the parameters (as necessary) and calls the date._toJulian function to do the actual work. You would not normally call the date._toJulian function as the date.toJulian macro with a single argument makes this call for you. You would normally use the date._toJulian function in your applications if you need to pass the address of a function as a parameter to some other function (you cannot take the address of a macro).

Note: a "Julian Date" is not the same thing as a "Julian Day Number". A Julian date is based on the Julian Calendar created by Julius Caesar in about 45 BC. It was very similar to our current calendar except they didn’t get the leap years quite right. Julian Day numbers are a different calendar system that, as explained above, number days consecutively after Jan 1 4713 BC (resetting to day one 7980 years later). Out of sheer laziness, this document will use the term "Julian Date" as a description of the calendar based on Julian day numbers despite that fact that this is technically incorrect.

HLA high-level calling sequence examples:

date.toJulian( someDateVar );

mov( eax, JulianDayNumber );

date.toJulian( month, day, year );

mov( eax, JulianDayNumber2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._toJulian;

mov( eax, JulianDayNumber );

date.fromJulian( jd:uns32; var gd:date.daterec );

This procedure converts a Julian date to a Gregorian date. The Julian date is the first parameter, the second (reference) parameter is a Gregorian date variable ( data.daterec ). See the note above about adding some number of days to a Gregorian date via translation to Julian. Note that adding months or years to a Julian date is a real pain in the rear. It’s generally easier and faster to convert the Julian date to a Gregorian date, add the months and/or years to the Gregorian date (which is relatively easy), and then convert the whole thing back to a Julian day number.

HLA high-level calling sequence examples:

date.fromJulian( JulianDayNumber, someDateVar );

HLA low-level calling sequence examples:

// Assume someDateVar is a static variable:

push( JulianDayNumber );

pushd( &someDateVar );

call date.fromJulian;

// Assume someDateVar is not a static object

push( JulianDayNumber );

lea( eax, someDateVar );

push( eax );

call date.fromJulian;

#macro date.dayNumber( m:byte; d:byte; y:word ); @returns( "eax" );
#macro date.dayNumber( dr:date.daterec ); @returns( "eax" );
date._dayNumber( dr:daterec ); @returns( "eax" );

These functions convert the Gregorian date passed as a parameter into a day number into the current year (often erroneously called a "Julian Date" since NASA adopted this terminology in the late sixties). These functions return a value between 1 and 365 or 366 (for leap years) in the EAX register. Jan 1 is day 1, Dec 31 is day 365 or day 366.

HLA high-level calling sequence examples:

date.dayNumber( someDateVar );

mov( eax, dayNumber1 );

date.dayNumber( month, day, year );

mov( eax, dayNumber2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._dayNumber;

mov( eax, dayNumber1 );

#macro date.daysLeft( m:byte; d:byte; y:word ); @returns( "eax" );
#macro date.daysLeft( dr:date.daterec ); @returns( "eax" );
date._daysLeft( dr:daterec ); @returns( "eax" );

These functions return the number of days left in the current year counting the date passed as a parameter (hence Dec 31, yyyy always returns one).

HLA high-level calling sequence examples:

date.daysLeft( someDateVar );

mov( eax, daysLeft1 );

date.daysLeft( month, day, year );

mov( eax, daysLeft2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._daysLeft;

mov( eax, daysLeft1 );

#macro date.dayOfWeek( m:byte; d:byte; y:word ); @returns( "eax" );
#macro date.dayOfWeek( dr:date.daterec ); @returns( "eax" );
date._dayOfWeek( dr:daterec ); @returns( "eax" );

These functions return, in EAX, a value between zero and six denoting the day of the week of the given Gregorian date (0=sun, 1=mon, etc.)

HLA high-level calling sequence examples:

date.dayOfWeek( someDateVar );

mov( eax, dayOfWeek1 );

date.dayOfWeek( month, day, year );

mov( eax, dayOfWeek2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._dayOfWeek;

mov( eax, dayOfWeek1 );

Date Arithmetic

The functions in this category perform date arithmetic – adding integer (day) values to dates, subtracting integer (day) values, adding integer month or year values to a date, and computing the number of days between two dates.

#macro date.daysBetween
(
m1:byte;
d1:byte;
y1:word;
m2:byte;
d2:byte;
y2:word
); @returns( "eax" );

#macro date.daysBetween
(
m1:byte;
d1:byte;
y1:word;
dr:date.daterec
); @returns( "eax" );

#macro date.daysBetween
(
dr:date.daterec;
m:byte;
d:byte;
y:word
); @returns( "eax" );

#macro date.daysBetween
(
dr1:date.daterec;
dr2:date.daterec
); @returns( "eax" );

date._daysBetween( first:daterec; last:daterec ); @returns( "eax" );

These functions return an uns32 value in EAX that gives the number of days between the two specified dates. These functions work directly on the Gregorian dates.

HLA high-level calling sequence examples:

date.daysBetween( dateVar1, dateVar2 );

mov( eax, daysBetweenD1D2 );

date.daysBetween( m1, d1, y1, m2, d2, y2 );

mov( eax, daysBetween2 );

date.daysBetween( dateVar3, m4, d4, y4 );

mov( eax, daysBetween3 );

date.daysBetween( m5, d5, y5, dateVar6, );

mov( eax, daysBetween4 );

HLA low-level calling sequence examples:

push( dateVar1.date );

push( dateVar2.date );

call date._daysBetween;

mov( eax, daysBetween5 );

date.addDays( days:uns32; var dr:date.daterec );

This procedure adds the first parameter (in days) directly to the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.addDays( days, someDateVar );

HLA low-level calling sequence example:

push( days );

push( someDateVar.date );

call date.addDays;

date.addMonths( months:uns32; var dr:date.daterec );

This procedure adds the first parameter (in months) directly to the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.addMonths( months, someDateVar );

HLA low-level calling sequence example:

push( months);

push( someDateVar.date );

call date.addMonths;

date.addYears( years:uns32; var dr:date.daterec );

This procedure adds the first parameter (in years) directly to the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.addYears( years, someDateVar );

HLA low-level calling sequence example:

push( years);

push( someDateVar.date );

call date.addYears;

date.subDays( days:uns32; var dr:date.daterec );

This procedure subtracts the first parameter (in days) directly from the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.subDays( days, someDateVar );

HLA low-level calling sequence example:

push( days );

push( someDateVar.date );

call date.subDays;

date.subMonths( months:uns32; var dr:date.daterec );

This procedure subtracts the first parameter (in months) directly from the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.subMonths( months, someDateVar );

HLA low-level calling sequence example:

push( months);

push( someDateVar.date );

call date.subMonths;

date.subYears( years:uns32; var dr:date.daterec );

This procedure subtracts the first parameter (in years) directly from the Gregorian date variable passed by reference as the second parameter.

HLA high-level calling sequence example:

date.subYears( years, someDateVar );

HLA low-level calling sequence example:

push( years);

push( someDateVar.date );

call date.subYears;

Reading the Current System Date

The functions in this category read the current date from the system.

date.today( var dr:date.daterec );

Stores the local date (today’s date) into the specified parameter. Warning: some systems may not provide a localized date and time, if this is the case then this function will return the UTC/GMT date. If this would cause your application to fail, then you should read both the local and UTC dates and times and, if they are not different, apply an application-defined time zone difference to the local date value.

HLA high-level calling sequence example:

date.today( someDateVar );

HLA low-level calling sequence example:

// Assume that "someDateVar" is a static object:

pushd( &someDateVar );

call date.today;

// If someDateVar is not a static object:

lea( eax, someDateVar );

push( eax );

call date.today;

date.utc( var dr:date.daterec );

Stores the UTC date (today’s GMT date) into the specified parameter. Of course, the difference between the local and GMT date depend entirely upon which time zone you’re in.

HLA high-level calling sequence example:

date.utc( someDateVar );

HLA low-level calling sequence example:

// Assume that "someDateVar" is a static object:

pushd( &someDateVar );

call date.utc;

// If someDateVar is not a static object:

lea( eax, someDateVar );

push( eax );

call date.utc;

Date Output and String Conversion

The date module contains several functions that let you choose a date output format, convert a date to a string, and output dates (to the standard output device). This section describes those functions.

date.setFormat( fmt : OutputFormat );

This sets the internal format variable to the date.OutputFormat value you specify. This constant must be one of the date.OutputFormat enumerated constants (given earlier) or date.SetFormat will raise an ex.InvalidDateFormat exception.

HLA high-level calling sequence example:

date.setFormat( date.mmddyyyy );

date.setFormat( dateFmtVariable );

HLA low-level calling sequence example:

// If the parameter is a constant:

pushd( date.mmddyyyy );

call date.setFormat;

// If someFmtVar is byte variable and the

// three bytes following it are in paged memory:

push( (type dword someFmtVar) );

call date.setFormat;

// If you cannot access the three bytes beyond someFmtVar:

movzx( someFmtVar, eax );

push( eax );

call date.setFormat;

date.setSeparator( chr:char );

This procedure sets the internal date separator character (default is ’/’) to the character you pass as a parameter. This is used when printing dates and converting dates to strings.

HLA high-level calling sequence example:

date.setSeparator( ‘-‘ );

date.setSeparator( someCharVar );

HLA low-level calling sequence example:

// If the parameter is a constant:

pushd( ‘/’ );

call date.setSeparator;

// If someFmtVar is byte variable and the

// three bytes following it are in paged memory:

push( (type dword someCharVar) );

call date.setSeparator;

// If you cannot access the three bytes beyond someFmtVar:

movzx( someCharVar, eax );

push( eax );

call date.setSeparator;

#macro date.toString( m:byte; d:byte; y:word; s:string );
#macro date.toString( dr:date.daterec; s:string);
date._toString( dr:daterec; s:string );

These functions will convert the specified date to a string (using the output format specified by date.SetFormat and the separator character specified by date.SetSeparator ) and store the result in the specified string. An ex.StringOverflow exception occurs if the destination string’s MaxStrLen field is too small (generally, 20 characters handles all string formats).

HLA high-level calling sequence examples:

date.toString( someDateVar, dateString1 );

date.toString( month, day, year, dateString2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

push( dateString3 );

call date._toString;

#macro date.a_toString( m:byte; d:byte; y:word ); @returns( "eax" );
#macro date.a_toString( dr:date.daterec ); @returns( "eax" );
date._a_toString( dr:daterec ); @returns( "eax" );

These procedures are similar to the date.toString procedures above except they automatically allocate the storage for the string and return a pointer to the string object in the EAX register. You should free the string storage with str.free with you are done with this string.

HLA high-level calling sequence examples:

date.a_toString( someDateVar );

mov( eax, dateStr1 );

date.a_toString( month, day, year );

mov( eax, dateStr2 );

HLA low-level calling sequence examples:

push( someDateVar.date );

call date._a_toString;

mov( eax, dateStr3 );

Date Class Types

For those who prefer an object-oriented programming approach, the Standard Library provides the ability to create date class data types. To use one of the date class data types, you must include the following statement at the beginning of your HLA program:

#include( "dtClass.hhf" )

Note that stdlib.hhf does not include dtClass.hhf, so you must explicitly include the dtClass.hhf header file if you intend to use any of the date class functions or data types.

The Standard Library provides two predefined date class types: dateClass_t and virtualDateClass. The difference between these two types is that the dateClass_t type uses static procedures for all the date functions whereas virtualDateClass_t uses virtual methods for all the date functions. In certain cases, using the dateClass_t data type is more efficient than using virtualDateClass_t because you only link in the class functions you actually call. However, you lose the object-oriented method inheritence/override ability when using the dateClass_t type rather than the virtualDateClass_t type. For more details on the differences between these two class types, please see the discussion of the dtClass.make_dateClass macro appearing later in this section. This section will use the phrase "date class" to mean any class created by the make.dateClass_t macro, including the dateClass_t and virtualDateClass_t data types.

The date class types provide three data fields:

var

theDate: date.daterec;

OutFmt: date.OutputFormat;

Separator: char;

The first field, theDate, holds the date value associated with the date object. This is the standard date.daterec date type described earlier in this document. Note that you can pass this field to any of the standard date and time functions that expect a date.daterec value.

The second field, OutFmt, specifies the output format when using the date class string conversion routines. Note that only the date class string conversion routines respect the value of this field; if you pass theDate directly to a date function that takes a date.daterec argument, that function will use the system-wide global date format rather than the object’s OutFmt value.

Thread Safety Issue: Although each date object has its own OutFmt field, this does not make the use of date class objects thread safe. When converting theDate to a string, the date class functions save the global format value, copy OutFmt to the global format value, call the date functions to do the string conversion, and then restore the original global value. If a thread is suspended during this activity then any date/string conversions during this suspension may use an incorrect format value. This issue will be corrected in a later version of the Standard Library. For now, you must manually protect all date/string conversions if you perform such conversions in multiple threads in your application.

The third field, Separator, holds the character that is used to separate the months, days, and years fields during a string conversion. The dateClass_t and virtualDateClass_t constructors initialize this field with a slash character (‘/’).

Of course, you may create a derived class from either dateClass_t or virtualDateClass_t (or create a brand new date class using the dtClass.make_dateClass macro) and add any other fields you like to that new date class. One suggestion for such a class is to pad the data fields to a multiple of four bytes. Currently, the dateClass_t and virtualDateClass_t objects consumes ten bytes of storage (six bytes for the three fields above plus four bytes for the VMT pointer). For performance reasons, you might want to extend the size of the data storage to 12 or even 16 bytes.

Date Class Methods/Procedures

In most HLA classes, there are two types of functions: (static) procedures and (dynamic) methods (there are also iterators, but the date classes do not use iterators so we will ignore that here). The only difference between a method and a procedure is how the program actually calls the function: the program calls procedures directly, it calls methods indirectly through an entry in the virtual method table (VMT). Static procedure calls are very efficient, but you lose the benefits of inheritence and functional polymorphism when you define a function as a static procedure in a class. Methods, on the other hand, fully support polymorphic calls, but introduce some efficiency issues.

The second effiency issue concerning method calls is that they use the EDI register to make the indirect call (static procedure calls do not disturb the value in EDI). Therefore, you must ensure that EDI is free and available before making a virtual method call, or take the effort to preserve EDI’s value across such a call.

A third, though exteremely minor, efficiency issue concerning methods is that the class’ VMT will need an extra entry in the virtual method table. As this is only four bytes per class (not per object), this probably isn’t much of a concern.

The predefined dateClass_t and virtualDateClass_t classes differ in how they define the functions appearing in the class types. The dateClass_t type uses static procedures for all functions, the virtualDateClass_t type uses methods for all class functions. Therefore, dateClass_t date types will make direct calls to all the functions (and only link in the procedures you actually call); however, dateClass_t objects do not support function polymorphism in derived classes. The virtualDateClass_t type does support polymorphism for all the class methods, but whenever you use this data type you will link in all the methods (even if you don’t call them all) and calls to these methods will require the use of the EDI register.

It is important to understand that dateClass_t and virtualDateClass_t are two separate types. Neither is derived from the other. Nor are the two types compatible with one another. You should take care not to confuse objects of these two types if you’re using both types in the same program.

Creating New Date Class Types

As it turns out, the only difference between a method and a procedure (in HLA) is how that method/procedure is called. The actual function code is identical regardless of the declaration (the reason HLA supports method and procedure declarations is so that it can determine how to populate the VMT and to determine how to call the function). By pulling some tricks, it’s quite possible to call a procedure using the method invocation scheme or call a method using a direct call (like a static procedure). The Standard Library date class module takes advantage of this trick to make it possible to create new date classes with a user-selectable set of procedures and methods. This allows you to create a custom date type that uses methods for those functions you want to override (as methods) and use procedures for those functions you don’t call or will never override (as virtual methods). Indeed, the dateClass_t and virtualDateClass_t date types were created using this technique. The dateClass_t data type was created specifying all functions as procedures, the virtualDateClass_t data type was created specifying all functions as methods. By using the dtClass.make_dateClass macro, you can create new date data types that have any combination of procedures and methods.

dtClass.make_dateClass( className, "<list of methods>" )

dtClass.make_dateClass is a macro that generates a new data type. As such, you should only invoke this macro in an HLA type declaration section. This macro requires two arguments: a class name and a string containing the list of methods to use in the new data type. The method list string must contain a sequence of method names (typically separated by spaces, though this isn’t strictly necessary) from the following list:

today

utc

isLeapYear

isValid

validate

a_toString

toString

setSeparator

setFormat

addDays

subDays

addMonths

subMonths

addYears

subYears

fromJulian

toJulian

dayOfWeek

dayNumber

daysLeft

daysBetween

difference

Here is dtClass.make_dateClass macro invocation that creates the virtualDateClass_t type:

type

dtClass.make_dateClass

(

virtualDateClass,

"today"

"isLeapYear"

"isValid"

"a_toString"

"toString"

"setSeparator"

"setFormat"

"addDays"

"subDays"

"addMonths"

"addYears"

"fromJulian"

"toJulian"

"dayOfWeek"

"dayNumber"

"daysLeft"

"daysBetween"

);

(For those unfamiliar with the syntax, HLA automatically concatenates string literals that are separated by nothing but whitespace; therefore, this macro contains exactly two arguments, the virtualDateClass_t name and a single string containing the concatenation of all the strings above.)

From this macro invocation, HLA creates a new data type using methods for each of the names appearing in the string argument. If a particular date function’s name is not present in the dtClass.make_dateClass macro invocation, then HLA creates a static procedure for that function. As a second example, consider the declaration of the dateClass_t data type (which uses static procedures for all the date functions):

type

dtClass.make_dateClass( dateClass_t, " " );

Because the function string does not contain any of the date function names, the dtClass.make_dateClass macro generates static procedures for all the date functions.

The dateClass_t type is great if you don’t need to create a derived date class that allows you to polymorphically override any of the date functions. If you do need to create methods for certain functions and you don’t mind linking in all the date class functions (and you don’t mind the extra overhead of a method call, even for those functions you’re not overloading), the virtualDateClass_t is convenient to use because it makes all the functions virtual (that is, methods). Probably 99% of the time you won’t be calling the date functions very often, so the overhead of using method invocations for all date functions is irrelevant. In those rare cases where you do need to support polymorphism for a few date functions but don’t want to link in the entire set of date functions, or you don’t want to pay the overhead for indirect calls to functions that are never polymorphic, you can create a new date class type that specifies exactly which functions require polymorphism.

For example, if you want to create a date class that overrides the definition of the fromJulian and toJulian functions, you could declare that new type thusly:

type

dtClass.make_dateClass

(

myDateClass,

"fromJulian"

"toJulian"

);

This new class type (myDateClass) has two methods, fromJulian and toJulian, and all the other date functions are static procedures. This allows you to create a derived class that overloads the fromJulian and toJulian methods and access those methods when using a generic myDateClass pointer, e.g.,

type

derivedMyDateClass :

class inherits( myDateClass );

override method fromJulian;

override method toJulian;

endclass;

It is important for you to understand that types created by dtClass.make_dateClass are base types. They are not derived from any other class (e.g., virtualDateClass_t is not derived from dateClass_t or vice-versa). The types created by the dtClass.make_dateClass macro are independent and incompatible types. For this reason, you should avoid using different base date class types in your program. Pick (or create) a base date class and use that one exclusively in an application. You’ll avoid confusion by following this rule.

For the sake of completeness, here are the macros that the Standard Library uses to create date data types:

namespace dtClass;

// The following macro allows us to turn a class function

// into either a method or a procedure based on the

// presence of "funcName" within a list of method names

// passed to the class generating macro.

#macro function( funcName );

#if( @index( methods, 0, @string:funcName) = -1 )

procedure funcName

#else

method funcName

#endif

#endmacro

#macro make_dateClass( className, methods );

className:

class

var

theDate: date.daterec;

OutFmt: date.OutputFormat;

Separator: char;

procedure create;

@external( "DATECLASS_CREATE");

dtClass.function( today );

@external( "DATECLASS_TODAY");

dtClass.function( utc );

@external( "DATECLASS_UTC");

dtClass.function( isLeapYear );

@returns( "al" );

@external( "DATECLASS_ISLEAPYEAR");

dtClass.function( isValid );

@returns( "al" );

@external( "DATECLASS_ISVALID");

dtClass.function( validate );

@returns( "al" );

@external( "DATECLASS_VALIDATE");

dtClass.function( a_toString );

@returns( "eax" );

@external( "DATECLASS_A_TOSTRING");

dtClass.function( toString )( dest:string );

@external( "DATECLASS_TOSTRING");

dtClass.function( setSeparator )( c:char );

@external( "DATECLASS_SETSEPARATOR");

dtClass.function( setFormat )( f:date.OutputFormat );

@external( "DATECLASS_SETFORMAT");

dtClass.function( addDays )( days:uns32 );

@external( "DATECLASS_ADDDAYS");

dtClass.function( subDays )( days:uns32 );

@external( "DATECLASS_SUBDAYS");

dtClass.function( addMonths )( months:uns32 );

@external( "DATECLASS_ADDMONTHS");

dtClass.function( subMonths )( days:uns32 );

@external( "DATECLASS_SUBMONTHS");

dtClass.function( addYears )( years:uns32 );

@external( "DATECLASS_ADDYEARS");

dtClass.function( subYears )( days:uns32 );

@external( "DATECLASS_SUBYEARS");

dtClass.function( fromJulian )( Julian:uns32 );

@external( "DATECLASS_FROMJULIAN");

dtClass.function( toJulian );

@returns( "eax" );

@external( "DATECLASS_TOJULIAN");

dtClass.function( dayOfWeek );

@returns( "eax" );

@external( "DATECLASS_DAYOFWEEK");

dtClass.function( dayNumber );

@returns( "eax" );

@external( "DATECLASS_DAYNUMBER");

dtClass.function( daysLeft );

@returns( "eax" );

@external( "DATECLASS_DAYSLEFT");

dtClass.function( daysBetween )

(

otherDate:date.daterec

);

@returns( "eax" );

@external( "DATECLASS_DAYSBETWEEN");

dtClass.function( difference )

(

var otherDate:className in eax

);

@returns( "eax" );

@external( "DATECLASS_DIFFERENCE");

endclass

#endmacro

end dtClass;

If you look closely at the make_dateClass macro, you’ll notice that it maps all the functions, be they methods or procedures, to the dateClass_t names (which are all procedures, if you look at the source code for these functions). As noted earlier, the function code for methods and procedures is exactly the same, only the call to a given function is different based on whether it is a method or a procedure. Therefore, the dtClass.make_dateClass macro maps all functions to the same set of procedures. Therefore, if you do create and use multiple date classes in the same application, the linker will only link in one set of routines (unless, of course, you overload some methods, in which case the linker will link in your new functions as well as the original dateClass_t set).

Date Class Functions

The date class type supports most of the functions associated with the date type. The main difference is that the date class functions operate directly on the date object rather than on a date value you pass as a parameter. For this reason, there aren’t any macros that overload the date function parameter lists.

The following sections do not include sample code demonstrating the calling sequences for a couple of reasons:

For high level calls, the syntax deponds on the object name and type.

Low-level calling sequences don’t appear here because it doesn’t really make sense to make a low-level object invocation; people wanting to make low-level calls will probably use the standard date procedures rather than the object-oriented ones.

These functions are really intended for use by programmers experienced with HLA’s Object-oriented assembly facilities. Note that the dtClass.hhf header file is not automatically included by stdlib.hhf; this reflects the more advanced nature of the date class module.

For the same reasons, there are no stack diagrams for these function calls. If you want more information on making calls to HLA class methods and procedures, please consult the HLA documentation.

In the following function descriptions, the symbol <object> is used to specify a date class object or a pointer to a date class object. Note that class invocations of static procedures (e.g., "dateClass_t.isLeapYear") are illegal with the single exception of the constructor (the create procedure). If you call a date class procedure directly, the system will raise an exception (as ESI, which should be pointing at the object’s data, will contain NULL).

<object>.create();

The <name>.create procedure is the object constructor. This is the only function that you may call using a class name rather than an object name. For example, dateClass_t.create(); is a perfectly legitimate constructor call. As is the convention for HLA class constructors, if you call a class constructor directly (using the class name rather than an object name), the date class constructor will allocate storage for a new date class object on the heap and return a pointer to the new object in ESI. Once the storage is allocated (or if you specify the name of a previously-allocated object rather than the class name), the date class constructor will initialize all the fields of the object to reasonable values (in particular, the constructor initializes the VMT pointer, initializes theDate to a valid date, and sets up the OutFmt and Separator fields with default values).

If you create a derived date class and add new data fields to the data type, you should override the create procedure and initialize those new fields in the overridden procedure. See the HLA documentation or The Art of Assembly Language for more details on derived classes and overriding constructors.

This function returns true or false in the AL register depending upon whether the object’s theDate field is a leap year (true if it is a leap year). See the discussion of date.isLeapYear for more details.

This function checks the object’s theDate field and raises an ex.InvalidDate exception if the date is not a valid date between 1/1/1600 and 12/31/2999. See the discussion of date.validate for more details.

This function checks the object’s theDate field and returns false in EAX if the date is not a valid date between 1/1/1600 and 12/31/2999 (it returns true otherwise). See the discussion of date.isValid for more details.

This function converts the Gregorian (i.e., standard) date found in the object’s theDate field into a Julian day number. See the discussion of date.toJulian for more details.

This function converts the Julian Day Number passed as the argument to a Gregorian (i.e., standard) date and stores the result the object’s theDate field. See the discussion of date.fromJulian for more details. This function will raise an ex.InvalidDate exception if the Julian Day Number conversion produces a date outside the range 1/1/1600 to 12/31/2999. See the discussion of date.fromJulian for more details.

This function converts the Gregorian date found in the objects theDate field into a day number into the current year. It returns the day number in the EAX register. See the discussion of date.dayNumber for more details.

This function returns the number of days left in the current year counting the object’s theDate field. See the discussion of date.daysLeft for more details.

These functions return, in EAX, a value between zero and six denoting the day of the week of theDate. See the discussion of date.dayOfWeek for more details.

This function returns an uns32 value in EAX that gives the number of days between object’s date and the daterec value passed as a parameter dates. See the discussion of date.daysBetween for more details.

This function returns an uns32 value in EAX that gives the number of days between object’s date and the date class object value passed as a parameter. The parameter type ("<classType>") must be the same type as <object>. See the discussion of date.daysBetween for more details.

This procedure adds the parameter value (in days) directly to the object’s theDate field. See the discussion of date.addDays for more details.

This procedure adds the parameter value (in months) directly to the object’s theDate field. See the discussion of date.addMonths for more details.

This procedure adds the parameter value (in years) directly to the object’s theDate field. See the discussion of date.addYears for more details.

This procedure subtracts the parameter value (in days) directly from the object’s theDate field. See the discussion of date.subDays for more details.

This procedure subtracts the parameter value (in months) directly from the object’s theDate field. See the discussion of date.subMonths for more details.

This procedure subtracts the parameter value (in years) directly from the object’s theDate field. See the discussion of date.subYears for more details.

<object>.today();

Stores the local date (today’s date) into the object’s theDate field. See the discussion of date.today for more details.

Stores the UTC date (today’s GMT date) into the object’s theDate field. See the discussion of date.utc for more details.

This function converts the object’s theDate field to a string (using the output format specified by the object’s theDate field and the separator character specified by the object’s OutFmt field) and stores the result in the specified string. See the discussion of date.toString for more details.

This function converts the object’s theDate field to a string (using the output format specified by the object’s theDate field and the separator character specified by the object’s OutFmt field) and stores the result in storage it allocates on the heap. This function returns a pointer to the new string in the EAX register. See the discussion of date.a_toString for more details.

Environment Variables Module (env.hhf)

The env module contains a couple of functions that fetch environment strings from the operating system. These functions can be used to test global values set by the user in the environment space inherited by your processes.

The Env Module

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

#include( "env.hhf" )

#include( "stdlib.hhf" )

Retrieving Environment Strings

The env module contains two functions for retrieving environment string data. To each of these functions you must pass the name of an environment variable (in the envVar string parameter). These functions will locate the specified environment variable in the system (if it is present) and return the associated string value.

procedure env.get( envVar:string; dest:string );

env.get copies the environment string data to the (preallocated) string variable you specify via the dest parameter. Note that the dest parameter must contain the address of a value HLA string object or this function may fail (or raise an exception). If the allocated storage isn’t large enough to hold the string data, or the environment variable’s string is greater than 4095 characters long, this function will raise an exception. This function returns true in EAX if it locates the environment variable in the environment space and successfully returns the environment variable’s data. This function returns false in EAX if it cannot locate the environment variable in the environment space.

HLA high-level calling sequence examples:

env.get( envVarName, envData );

if( eax ) then

// process the environment data in envData

endif;

HLA low-level calling sequence examples:

push( envVarName ); // Assumption: envVarName is a string variable

call env.get;

procedure env.a_get( envVar:string );

env.a_get also returns the value of an environment variable; however, it allocates storage for the result and returns a pointer to the string result (on the heap) in the EAX register, if such an environment variable exists. This function returns NULL in EAX if the environment variable does not exist. This function raises an exception if the environment variable’s data is greater than 4095 characters long. The caller is responsible for freeing the storage allocated on the heap by this function.

HLA high-level calling sequence examples:

env.a_get( envVarName );

mov( eax, envData );

if( eax <> NULL ) then

// process the environment data pointed at by envData

endif;

str.free( envData );

HLA low-level calling sequence examples:

push( envVarName ); // Assumption: envVarName is a string variable

call env.get;

mov( eax, envData );

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

#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. Note that the following numeric constants for the exception names are subject to change.

/* 0 */ UnknownException,

// String related exceptions:

/* 1 */ StringOverflow,

/* 2 */ StringIndexError,

/* 3 */ StringOverlap,

/* 4 */ StringMetaData,

/* 5 */ StringAlignment,

/* 6 */ StringUnderflow,

/* 7 */ IllegalStringOperation,

// General exceptions:

/* 8 */ ValueOutOfRange,

/* 9 */ IllegalChar,

/* 10 */ AttemptToDerefNULL,

/* 11 */ TooManyCmdLnParms,

/* 12 */ AssertionFailed,

/* 13 */ ExecutedAbstract,

/* 14 */ BadObjPtr,

/* 15 */ InvalidAlignment,

/* 16 */ InvalidArgument,

/* 17 */ BufferOverflow,

/* 18 */ BufferUnderflow,

/* 19 */ IllegalSize,

// Formatting and conversion errors:

/* 20 */ ConversionError,

/* 21 */ WidthTooBig,

/* 22 */ FractionTooBig,

// File-related exceptions:

/* 23 */ BadFileHandle,

/* 24 */ FileNotFound,

/* 25 */ FileOpenFailure,

/* 26 */ FileCloseError,

/* 27 */ FileWriteError,

/* 28 */ FileReadError,

/* 29 */ FileSeekError,

/* 30 */ DiskFullError,

/* 31 */ AccessDenied,

/* 32 */ EndOfFile,

// FileSys-related exceptions:

/* 33 */ CannotCreateDir,

/* 34 */ CannotRemoveDir,

/* 35 */ CannotRemoveFile,

/* 36 */ CDFailed,

/* 37 */ CannotRenameFile,

// Memory management exceptions:

/* 38 */ MemoryAllocationFailure,

/* 39 */ MemoryFreeFailure,

/* 40 */ MemoryAllocationCorruption,

/* 41 */ AttemptToFreeNULL,

/* 42 */ BlockAlreadyFree,

/* 43 */ CannotFreeMemory,

/* 44 */ PointerNotInHeap,

// Array exceptions:

/* 45 */ ArrayShapeViolation,

/* 46 */ ArrayBounds,

// Time/date exceptions:

/* 47 */ InvalidDate,

/* 48 */ InvalidDateFormat,

/* 49 */ TimeOverflow,

/* 50 */ InvalidTime,

/* 51 */ InvalidTimeFormat,

// Socket Errors:

/* 52 */ SocketError,

// Thread Errors:

/* 53 */ ThreadError,

// Hardware/OS related exceptions

/* 54 */ AccessViolation,

/* 55 */ InPageError,

/* 56 */ NoMemory,

/* 57 */ InvalidHandle,

/* 58 */ ControlC,

/* 59 */ StackOverflow,

/* 60 */ Breakpoint,

/* 61 */ SingleStep,

/* 62 */ PrivInstr,

/* 63 */ IllegalInstr,

/* 64 */ BoundInstr,

/* 65 */ IntoInstr,

/* 66 */ DivideError,

/* 67 */ fDivByZero,

/* 68 */ fInexactResult,

/* 69 */ fInvalidOperation,

/* 70 */ fOverflow,

/* 71 */ fUnderflow,

/* 72 */ fStackCheck,

/* 73 */ fDenormal,

// Blob related exceptions

/* 74 */ BlobOverflow

ex.UnknownException

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

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

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

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

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

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

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

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

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

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

ex.InvalidAlignment

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

ex.ConversionError

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

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

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

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

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

ex.FileCloseError

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

ex.FileWriteError

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

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

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

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

ex.AccessDenied

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

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

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

ex.CannotRemoveDir

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

ex.CannotRemoveFile

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

ex.CDFailed

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

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

ex.MemoryAllocationFailure

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

ex.MemoryFreeFailure

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

ex.MemoryFreeFailure

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

ex.AttemptToFreeNULL

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

ex.BlockAlreadyFree

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

ex.CannotFreeMemory

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

ex.PointerNotInHeap

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

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

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

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

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

ex.TimeOverflow

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

ex.InvalidTime

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

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

ex.AccessViolation

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

ex.InPageError

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

ex.NoMemory

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

ex.InvalidHandle

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

ex.ControlC

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

ex.StackOverflow

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

ex.Breakpoint

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

ex.SingleStep

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

ex.PrivInstr

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

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

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

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

ex.DivideError

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

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

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

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

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

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

ex.fStackCheck

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

ex.fDenormal

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

File Class Module (fileclass.hhf)

The HLA Standard Library provides an object-oriented file access mechanism implemented via the file_t and virtualfile_t classes. Unless otherwise specified, this document will use the term "file class" to describe the generic file class rather than the specific instance of the file_t class (which uses static linking for all functions).

Note: HLA also provides a fileio library module that does file I/O using traditional procedures rather than class objects. If you’re more comfortable using such a programming paradigm, or you prefer your code to be a bit more efficient, you should use the fileio module.

Note: Currently, the file_t class is implemented as a thin layer over the fileio module. That is, functions in the file class simply pass their parameters on to the corresponding functions in the fileio module. The ultimate intent, however, is for the file_t class to implement buffered I/O to improve performance. Because of the wide variety of operating systems that the HLA Standard Library supports (and will support), this may lead to some functionality limitations in future versions of the file_t class. In particular, you should only use file_t class objects to access files on block structured (disk) devices and avoid accessing character-oriented or other device types. Also, file_t objects will provide the best performance for sequential files. Though the intent is to fully support random-access to file data via file_t objects, you may get better performance by using the traditional file I/O functions in the fileio module.

Note: the virtualFile_t class is completely different from the file_t class. In particular, it is not a thin layer over the fileio module. All of the functions in the virtualFile_t class ultimately call the virtualFile_t.read and virtualFile_t.write functions to do file I/O. If you override these two functions (read and write), you will override the behavior of all methods in the virtualFile_t class. Note that this is not true for file_t objects.

Warning: Don’t forget that HLA objects modify the values in the ESI and EDI registers whenever you call a class procedure, method, or iterator. Do not leave any important values in either of these register when making calls to the following routines. If the use of ESI and EDI is a problem for you, you might consider using the fileio module that does not suffer from this problem.

A Note About Thread Safety: The file class functions and the operating system maintain system-wide values to track things like file position within a file. Currently, these values apply to all threads in a process (and, in the case of the OS, all processes in the system). When accessing the same file object from different threads, you should use synchronization to serialize access to the file object.

Note about function overloading: the functions in the file classes use function overloading in order to allow you to specify the parameter lists in different ways. The macro that handles the overloading generally coerces the possible parameter types into a single object that it passes to the underlying function. The documentation for the specific functions will tell you whether a symbol is a macro or a function. For the most part, this should matter to you unless you are taking the address of a function (which you cannot do with a macro). See the HLA documentation for more details on function overloading via macros.

File Class Methods/Procedures

In most HLA classes, there are three types of functions: (static) procedures, (dynamic) methods, and dynamic iterators. The only difference between a method and a procedure is how the program actually calls the function: the program calls procedures directly, it calls methods indirectly through an entry in the virtual method table (VMT). The system always calls iterators indirectly through the VMT, so we will not consider them further. Static procedure calls are very efficient, but you lose the benefits of inheritence and functional polymorphism when you define a function as a static procedure in a class. Methods, on the other hand, fully support polymorphic calls, but introduce some efficiency issues.

The second efficiency issue concerning method calls is that they use the EDI register to make the indirect call (static procedure calls do not disturb the value in EDI). Therefore, you must ensure that EDI is free and available before making a virtual method call, or take the effort to preserve EDI’s value across such a call.

A third, though extremely minor, efficiency issue concerning methods is that the class’ VMT will need an extra entry in the virtual method table. As this is only four bytes per class (not per object), this probably isn’t much of a concern.

The predefined file_t and virtualFile_t objects differ in how they define the functions appearing in the class types. The file_t type uses static procedures for all functions, the virtualFile_t type uses methods for all class functions. Therefore, file_t object types will make direct calls to all the functions (and only link in the procedures you actually call); however, file_t objects do not support function polymorphism in derived classes. The virtualFile_t type does support polymorphism for all the class methods, but whenever you use this data type you will link in all the methods (even if you don’t call them all) and calls to these methods will require the use of the EDI register.

It is important to understand that file_t and virtualFile_t are two separate types. Neither is derived from the other. Nor are the two types compatible with one another. You should take care not to confuse objects of these two types if you’re using both types in the same program.

A Quick Note

The following sections do not include sample code demonstrating the calling sequences for a couple of reasons:

For high level calls, the syntax depends on the object name and type.

Low-level calling sequences don’t appear here because it doesn’t really make sense to make a low-level object invocation; people wanting to make low-level calls will probably use the standard

fileio procedures rather than the object-oriented ones.

These functions are really intended for use by programmers experienced with HLA’s Object-oriented assembly facilities.

For the same reasons, there are no stack diagrams for these function calls. If you want more information on making calls to HLA class methods and procedures, please consult the HLA documentation.

In the following function descriptions, the symbol <object> is used to specify a file class object or a pointer to a file_t class object. This wherever this document uses the name "file_t", you may substitute (as appropriate) "virtualFile_t". Note that class invocations of static procedures (e.g., "file_t.open") are illegal with the single exception of the constructor (the create procedure). If you call a file class procedure directly, the system will raise an exception (as ESI, which should be pointing at the object’s data, will contain NULL).

General File Operations

The functions in this category let you initialize file objects, access fields of the file objects, and perform other housekeeping tasks.

The file class provides a file_t.create or virtualFile_t.create constructor which you should always call before making use of a file variable. For file variables (as opposed to file pointer variables), you should call this routine specifying the name of the file variable. For file pointer variables, you should call this routine using the class name and store the pointer returned in EAX into your file variable. For example, to initialize the two following two file objects, you would use code like the following:

var

MyOutputFile: file_t;

filePtr: pointer to file_t;

MyOutputFile.create();

file_t.create();

mov( eax, filePtr );

Note that the file_t.create constructor simply initializes the virtual method table pointer and does other necessary internal initialization. The constructor does not open a file or perform other file-related activities.

This function returns the file handle in the EAX register. The returned value is invalid if you have not opened the file. You can pass this handle value to any of the Standard Library file routines (e.g., fileio.putc ) that expect a handle. You may also pass this value to OS API functions that expect a file handle.

HLA high-level calling sequence examples:

filePtr.handle();

mov( eax, fileHandle );

Opening and Closing Files

This method opens an existing file. The filename parameter is a string specifying the name of the file you wish to open. The access parameter is one of the following:

fileio.r
fileio.w
fileio.rw
fileio.a

The fileio.r constant tells <object>.open to open the file for read-only access. The fileio.w constant tells <object>.open to open the file for writing. Using the fileio.rw constant tells <object>.open to open the file for reading and writing. The fileio.a option tells the <object>.open function to open the file for writing and append all written data to the end of the file.

Before accessing the data in a file, you must open the file (which initializes the file handle). The <object>.open and <object>.openNew methods are excellent tools for this purpose. You may also open the file using direct calls to the OS API, but you must initialize the <object>.fileHandle field of the class variable before making any other method calls in the file class.

HLA high-level calling sequence examples:

filePtr.open( "myfile.txt", fileio.r );

// Note: the Access parameter is almost always a constant in

// calls to fileio.open. However, if you want to pass a variable

// value or a register value in this parameter, you may certainly

// do so:

MyOutputFile.open( filenameStr, accessVarByte );

filePtr.open( someStr, al );

This function opens a new file for writing (if the file already exists, it is first deleted and then a new file is opened for writing). The file is given the "normal" attribute.

HLA high-level calling sequence examples:

filePtr.openNew( "myfile.txt" );

// If the filename string pointer is in a register (EAX):

MyOutputFile.openNew( eax );

<object>.close;

This method closes a file opened via <object>.open or <object>.openNew and flushes any buffered data to the disk.

HLA high-level calling sequence examples:

filePtr.close();

MyOutputFile.close();

File Predicates

The functions in this category test conditions associated with the file.

This function returns true in the AL register if the file pointer is at the end of the file. It returns false if the program can read additional data from the file.

Warning: <object>.eof only functions properly for actual disk files. If you attempt to read data from an interactive device like the system console (keyboard) or a serial port, <object>.eof ’s behavior is incorrect (it will wind up eating a character from the interactive input stream every time you call it). Unfortunately, none of the Oses that HLA supports provide a way to test for EOF until after you’ve actually read a character from the input stream. A better solution, which works fine with both interactive input streams and file data is to use HLA’s try..endtry statement to trap and EOF error when it occurs. For example, rather than writing the following:

while( !filePtr.eof( someHandle )) do

endwhile;

You should write the following:

try

forever

endfor;

exception( ex.EndOfFile );

endtry;

Note: under Windows, <object>.eof always returns false for character device files (e.g., keyboard input) and it returns false for all other non-disk file device types. Note that if the user presses ctrl-Z on the keyboard, <object>.eof will not return true, but the system will return an ex.endOfFile exception. If there is any chance you’ll be reading data from a device file rather than a disk file, always use the try..endtry block to test for EOF.

HLA high-level calling sequence examples:

while( !filePtr.eof( fileHandle ) ) do

<<something while not at EOF>>

endwhile;

This function returns true in AL if the file pointer is currently pointing at the OS’ end-of-line sequence in the file (carriage return/line feed for Windows, linefeed for other operating systems).

HLA high-level calling sequence examples:

filePtr.eoln();

Miscellaneous Output

The following file output routines all assume that you’ve opened the <object> file variable via a call to <object>.open and you’ve successfully opened the file for output.

This method writes the number of bytes specified by the count parameter to the file. The bytes starting at the address of the buffer byte are written to the file. No range checking is done on the buffer, it is your responsibility to ensure that the buffer contains at least count valid data bytes.

Note: Notice that the buffer parameter is an untyped reference parameter. Untyped reference parameters have special properties, so be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) if you are not absolutely sure you understand how untyped reference parameters operate.

HLA high-level calling sequence examples:

filePtr.write( buffer, count );

// If bufPtr is a dword object containing the

// address of the buffer whose data you wish to

// write to the file:

filePtr.write( val bufPtr, count );

// The following writes the four-byte value of

// the bufPtr variable to the file (an unusual

// operation):

filePtr.write( bufPtr, 4 );

This procedure writes the string "true" or "false" to the <object> output file depending on the value of the b parameter.

HLA high-level calling sequence examples:

filePtr.putbool( boolVar );

// If the boolean is in a register (AL):

MyOutputFile.putbool( al );

<object>.newln( );

This function writes a newline sequence (carriage return/line feed under Windows, linefeed under other operating systems) to the specified output file ( <object> ).

HLA high-level calling sequence examples:

filePtr.newln();

MyOutputFile.newln();

Character, Character Set, and String Output

The following file output routines all assume that you’ve opened the <object> file variable via a call to <object>.open and you’ve successfully opened the file for output.

<object>. putc( c:char )

Writes the character specified by the c parameter to the file.

HLA high-level calling sequence examples:

filePtr.putc( charVar );

// If the character is in a register (AL):

MyOutputFile.putc( al );

<object>. putcSize( c:char; width:int32; fill:char )

Outputs the character c to the file filevar using at least width output positions. If the absolute value of width is greater than one, then this function writes fill characters as padding characters during the output. If width is a positive value greater than one, then <object>.putcSize writes c left justfied in a field of width characters; if width is a negative value less than one, then <object>.putcSize writes c right justified in a field of width characters.

HLA high-level calling sequence examples:

filePtr.putcSize( charVar, width, padChar );

<object>. putcset( cst:cset );

This function writes all the members of the cst character set parameter to the specified file variable.

HLA high-level calling sequence examples:

filePtr.putcset( csVar );

MyOutputFile.putcset( [ebx] ); // EBX points at the cset.

<object>. puts( s:string );

This procedure writes the value of the string parameter to the file.

HLA high-level calling sequence examples:

filePtr.puts( strVar );

filePtr.puts( ebx ); // EBX holds a string value.

MyOutputFile.puts( "Hello World" );

<object>. putsSize( s:string; width:int32; fill:char )

This function writes the s string to the file using at least width character positions. If the absolute value of width is less than or equal to the length of s , then this function behaves exactly like <object>.puts . On the other hand, if the absolute value of width is greater than the length of s , then <object>.putsSize writes width characters to the output file. This procedure emits the fill character in the extra print positions. If width is positive, then <object>.putsSize right justifies the string in the print field. If width is negative, then <object>.putsSize left justifies the string in the print field. Generally, people expect the string to be left justified, so you should ensure that this value is negative to achieve this.

HLA high-level calling sequence examples:

filePtr.putsSize( strVar, width, ‘ ‘ );

// For the following, EBX holds the string value,

// ECX contains the width, and AL holds the pad

// character:

MyOutputFile.putsSize( ebx, ecx, al );

filePtr.putsSize( "Hello World", 25, padChar );

Hexadecimal Numeric Output

The following file output routines all assume that you’ve opened the <object> file variable via a call to <object>.open and you’ve successfully opened the file for output.

<object>. putb( b:byte );

This procedure writes the value of b to the file using exactly two hexadecimal digits (including a leading zero if necessary).

HLA high-level calling sequence examples:

filePtr.putb( byteVar );

// If the character is in a register (AL):

MyOutputFile.putb( al );

<object>. puth8( b:byte );

This procedure writes the value of b to the file using one or two hexadecimal digits (the minimum necessary).

HLA high-level calling sequence examples:

filePtr.puth8( byteVar );

// If the character is in a register (AL):

MyOutputFile.puth8( al );

<object>. puth8Size( b:byte; width:dword; fill:char )

This procedure writes the value of b to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence examples:

filePtr.puth8Size( byteVar, width, padChar );

<object>. putw( w:word );

This procedure writes the value of w to the file using exactly four hexadecimal digits (including leading zeros if necessary).

HLA high-level calling sequence examples:

filePtr.putw( wordVar );

// If the word is in a register (AX):

MyOutputFile.putw( ax );

<object>. puth16( w:word );

This procedure writes the value of w to the file using 1-4 hexadecimal digits (the minimum necessary).

HLA high-level calling sequence examples:

filePtr.puth16( wordVar );

// If the word is in a register (AX):

MyOutputFile.puth16( ax );

<object>. puth16Size( w:word; width:dword; fill:char )

This procedure writes the value of w to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence examples:

filePtr.puth16Size( wordVar, width, padChar );

<object>. putd( dw:dword );

This procedure writes the value of d to the file using exactly eight hexadecimal digits (including leading zeros if necessary). If the stdlib global underscores value (see the conversions module for details) contains true, then this function will also print an underscore between the fourth and fifth digits.

HLA high-level calling sequence examples:

filePtr.putd(dwordVar );

// If the dword value is in a register (EAX):

MyOutputFile.putd( eax );

<object>. puth32( dw:dword );

This procedure writes the value of d to the file using the minimum number of hexadecimal required. If the stdlib global underscores value (see the conversions module for details) contains true, then this function will also print an underscore between the fourth and fifth digits (if there are at least five digits in the number).

HLA high-level calling sequence examples:

filePtr.puth32( dwordVar );

// If the dword is in a register (EAX):

MyOutputFile.puth32( eax );

<object>. puth32Size( d:dword; width:dword; fill:char )

This procedure writes the value of d to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence examples:

filePtr.puth32Size( dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

MyOutputFile.puth32Size( eax, width, cl );

<object>. putq( q:qword );

This procedure writes the value of q to the file using exactly 16 hexadecimal digits (including leading zeros if necessary). If the stdlib global underscores value (see the conversions module for details) contains true, then this function will also print an underscore between each group of four digits.

HLA high-level calling sequence example:

filePtr.putq( qwordVar );

<object>. puth64( q:qword );

This procedure writes the value of q to the file using 1-16 hexadecimal digits (the minimum necessary). If the stdlib global underscores value (see the conversions module for details) contains true, then this function will also print an underscore between each group of four digits.

HLA high-level calling sequence example:

MyOutputFile.puth64( qwordVar );

<object>. puth64Size( q:qword; width:dword; fill:char )

This procedure writes the value of q to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence example:

MyOutputFile.puth64Size( qwordVar, width, ‘ ‘ );

<object>. puttb( tb:tbyte )

This procedure writes the value of tb to the file using exactly 20 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

filePtr.puttb( tbyteVar );

<object>. puth80( tb:tbyte )

This procedure writes the value of tb to the file using 1-20 hexadecimal digits (the minimum necessary) and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

filePtr.puth80( tbyteVar );

<object>. puth80Size( tb:tbyte; width:dword; fill:char )

This procedure writes the value of tb to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence examples:

filePtr.puth80Size( tbyteVar, width, ‘ ‘ );

<object>. putl( l:lword )

This procedure writes the value of l to the file using exactly 32 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

MyOutputFile.putl( lwordVar );

<object>. puth128( l:lword )

This procedure writes the value of l to the file using 1-32 hexadecimal digits (the minimum necessary) and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

filePtr.puth128( lwordVar );

<object>. puth128Size( l:lword; width:dword; fill:char )

This procedure writes the value of l to the file using a minimum field width and a fill character. See the discussion of width and fill in the description of the <object>.putcSize function for more details on their behavior.

HLA high-level calling sequence examples:

MyOutputFile.puth128Size( tbyteVar, width, ‘ ‘ );

Signed Integer Numeric Output

The following file output routines all assume that you’ve opened the <object> file variable via a call to <object>.open and you’ve successfully opened the file for output.

These routines convert signed integer values to string format and write that string to the filevar file. The <object>.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

If the absolute value of width is greater than the number of print positions the value requires, then these functions output width characters to the output file. If width is non-negative, then these functions right-justify the value in the output field; if value is negative, then these functions left-justify the value in the output field.

These functions print the fill character as the padding value for the extra print positions.

This function converts the eight-bit signed integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.puti8( byteVar );

// If the character is in a register (AL):

MyOutputFile.puti8( al );

This function writes the eight-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.puti8Size( byteVar, width, padChar );

This function converts the 16-bit signed integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

MyOutputFile.puti16( wordVar );

// If the word is in a register (AX):

filePtr.puti16( ax );

This function writes the 16-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.puti16Size( wordVar, width, padChar );

This function converts the 32-bit signed integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.puti32( dwordVar );

// If the dword is in a register (EAX):

MyOutputFile.puti32( eax );

This function writes the 32-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

MyOutputFile.puti32Size( dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

filePtr.puti32Size( eax, width, cl );

This function converts the 64-bit signed integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

MyOutputFile.puti64( qwordVar );

This function writes the 64-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.puti64Size( qwordVar, width, ‘ ‘ );

This function converts the 128-bit signed integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

MyOutputFile.puti128( lwordVar );

This function writes the 128-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.puti128Size( lwordVar, width, ‘ ‘ );

Unsigned Integer Numeric Output

These routines convert unsigned integer values to string format and write that string to the file. The <object>.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

These functions print the fill character as the padding value for the extra print positions.

This function converts theeight-bit unsigned integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.putu8( byteVar );

// If the character is in a register (AL):

MyOutputFile.putu8( al );

This function writes the unsigned eight-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.putu8Size( byteVar, width, padChar );

This function converts the 16-bit unsigned integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.putu16( wordVar );

// If the word is in a register (AX):

MyOutputFile.putu16( ax );

This function writes the unsigned 16-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

filePtr.putu16Size( wordVar, width, padChar );

This function converts the 32-bit unsigned integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.putu32( dwordVar );

// If the dword is in a register (EAX):

MyOutputFile.putu32( eax );

This function writes the unsigned 32-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

MyOutputFile.putu32Size( dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

filePtr.putu32Size( eax, width, cl );

This function converts the 64-bit unsigned integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.putu64( qwordVar );

This function writes the unsigned 64-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

MyOutputFile.putu64Size( qwordVar, width, ‘ ‘ );

This function converts the 128-bit unsigned integer you pass as a parameter to a string and writes this string to the file using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

filePtr.putu128( lwordVar );

This function writes the unsigned 128-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

MyOutputFile.putu128Size( lwordVar, width, ‘ ‘ );

Floating-Point Numeric Output Using Scientific Notation

The floating point numeric output routines translate the three different binary floating point formats to their string representation and then write this string to the file that filevar specifies. There are two generic classes of these routines: those that convert their values to exponential/scientific notation and those that convert their string to a decimal form.

The <object>.pute80 , <object>.pute64 , and <object>.pute32 routines convert their values to a string using scientific notation. These three routines each have two parameters: the value to output and the field width of the result. These routines produce a string with the following format:

This function writes the 32-bit single precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 32-bit extended precision floating point values support about 6-7 significant digits. So a width value that yeilds more than seven mantissa digits will produce garbage output in the low order digits of the number.

HLA high-level calling sequence examples:

MyOutputFile.pute32( r32Var, width );

// If the real32 value is in an FPU register (ST0):

var

r32Temp :real32;

fstp( r32Temp );

filePtr.pute32( r32Temp, 12 );

This function writes the 64-bit double precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 64-bit double precision floating point values support about 15 significant digits. So a width value that yeilds more than 15 mantissa digits will produce garbage output in the low order digits of the number.

HLA high-level calling sequence examples:

filePtr.pute64( r64Var, width );

// If the real64 value is in an FPU register (ST0):

var

r64Temp :real64;

fstp( r64Temp );

filePtr.pute64( r64Temp, 12 );

This function writes the 80-bit extended precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 80-bit extended precision floating point values support about 18 significant digits. So a width value that yeilds more than 18 mantissa digits will produce garbage output in the low order digits of the number.

HLA high-level calling sequence examples:

filePtr.pute80( r80Var, width );

// If the real80 value is in an FPU register (ST0):

var

r80Temp :real80;

fstp( r80Temp );

MyOutputFile.pute80( r80Temp, 12 );

Floating-Point Numeric Output Using Decimal Notation

Although scientific (exponential) notation is the most general display format for real numbers, real numbers you display in this format are very difficult to read. Therefore, the HLA file class module also provides a set of functions that output real values using the decimal representation. Although you cannot (practically) use these decimal output routines for all real values, they are applicable to a wide variety of common numbers you will use in your programs.

These functions come in two varieties. The first variety requires four parameters: the real value to convert, the width of the converted value, the number of digit positions to the right of the decimal point, and a padding character. The second variety only requires the first three parameters and assumes the padding character is a space. These functions write their values using the following string format:

This procedure writes a 32-bit single precision floating point value to the file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the fill value as the padding character to fill the output with width characters.

HLA high-level calling sequence examples:

filePtr.putr32( r32Var, width, decpts, fill );

filePtr.putr32( r32Var, 10, 2, ‘*’ );

// If the real32 value is in an FPU register (ST0):

var

r32Temp :real32;

fstp( r32Temp );

filePtr.putr32( r32Temp, 12, 2, al );

This procedure writes a 64-bit double precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of fill as the padding character to fill the output with width characters.

HLA high-level calling sequence examples:

MyOutputFile.putr64( r64Var, width, decpts, fill );

MyOutputFile.putr64( r64Var, 10, 2, ‘*’ );

// If the real64 value is in an FPU register (ST0):

var

r64Temp :real64;

fstp( r64Temp );

MyOutputFile.putr64( r64Temp, 12, 2, al );

This procedure writes an 80-bit extended precision floating point value to the file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of fill as the padding character to fill the output with width characters.

HLA high-level calling sequence examples:

filePtr.putr80( r80Var, width, decpts, fill );

filePtr.putr80( r80Var, 10, 2, ‘*’ );

// If the real80 value is in an FPU register (ST0):

var

r80Temp :real80;

fstp( r80Temp );

filePtr.putr80( r80Temp, 12, 2, al );

Generic File Output

<object>.put is a macro that automatically invokes an appropriate <object> output routine based on the type of the parameter(s) you pass it. This is a very convenient output routine and is probably the file class output call you will use most often in your programs. Keep in mind that this macro is not a single function call; instead, HLA translates this macro into a sequence of calls to procedures like <object>.puti32 , <object>.puts , etc.

<object>.put is a macro that provides a flexible syntax for outputting data to the standard output device. This macro allows a variable number of parameters. For each parameter present in the list, <object>.put will call the appropriate routine to emit that data, according to the type of the parameter. Parameters may be constants, registers, or memory locations. You must separate each macro parameter with a comma.

Here is an example of a typical invocation of an <object>.put :

The above is roughly equivalent to

<object>.newln();

This assumes, of course, that i and j are int32 variables.

The <object>. put macro also lets you specify the minimum field width for each parameter you specify. To print a value using a minimum field width, follow the object you wish to print with a colon and the value of the minimum field width. The previous example, using field widths, could look like the following:

Although this example used the literal decimal constants two and five for the field widths, keep in mind that register values and memory value (integers, anyway) are prefectly legal here.

For floating point numbers you wish to display in decimal form, you can specify both the minimum field width and the number of digits to print to the right of the decimal point by using the following syntax:

The <object>. put macro can handle all the basic primitive types, including boolean, unsigned (8, 16, 32, 64, 128), signed (8, 16, 32, 64, 128), character, character set, real (32, 64, 80), string, and hexadecimal (byte, word, dword, qword, tbyte, lword).

If you specify a class variable (object) and that class defines a toString method, the <object>. put macro will call the associated toString method and output that string to the file. Note that the toString method must dynamically allocate storage for the string by calling str.alloc . This is because <object>. put will call str.free on the string once it outputs the string.

There is a known "design flaw" in the <object>. put macro. You cannot use it to print HLA intermediate variables (i.e., non-local VAR objects). The problem is that HLA’s syntax for non-local accesses takes the form "reg32:varname" and <object>. put cannot determine if you want to print reg32 using varname print positions versus simply printing the non-local varname object. If you want to display non-local variables you must copy the non-local object into a register, a static variable, or a local variable prior to using <object>. put to print it. Of course, there is no problem using the other <object>.putXXXX functions to display non-local VAR objects, so you can use those as well.

Important(!), don’t forget that method calls (e.g., the routines that <object>. put translates into) modify the values in the ESI and EDI registers. Therefore, it never makes any sense to attempt to print the values of ESI and EDI within the parameter list. All you will wind up doing is printing the address of the file variable (ESI) or the address of its virtual method table (EDI). If you need to write these two values to a file, move them to another register or a memory location first.

Generic File Input

The following file input routines behave just like their standard input and file input counterparts (unless otherwise noted):

This function reads count bytes from the file and stores them into memory starting with the first byte of the buffer variable. This routine does not do any range checking. It is your responsibility to ensure that buffer is large enough to hold the data read.

HLA high-level calling sequence examples:

MyInputFile.read( buffer, count );

MyInputFile.read( [eax], 1024 );

<object>.readln;

This function reads and discards all characters up to and including the newline sequence in the file.

HLA high-level calling sequence examples:

filePtr.readLn();

Character and String Input

The following functions read character data from an input file. Note that HLA’s file class module does not provide the ability to read character set data directly from the user. However, you can always read a string and then convert that string to a character set using the appropriate function in the cset module.

This function reads a single character from the file and returns that chraacter in the AL register. This function assumes that the file you’ve opened is a text file. Note that <object>.getc does not return the end of line sequence as part of the input stream. Use the <object>..eoln function to determine when you’ve reached the end of a line of text. Because <object>..getc preprocesses the text file (removing end of line sequences) you should not use it to read binary data, use it only to read text files.

HLA high-level calling sequence examples:

filePtr.getc();

mov( al, charVar );

This function reads a sequence of characters from the current file position through to the next end of line sequence and stores these characters (without the end of line sequence) into the string variable you pass as a parameter. Before calling this routine, you must allocate sufficient storage for the string. If <object>.gets attempts to read a larger string than the string’s MaxLen value, <object>.gets raises a string overflow exception.

Note that this function does not store the end of line sequence into the string, though it does consume the end of line sequence. The next character a file class function will read from the file will be the first character of the following line.

If the current file position is at the end of some line of text, then <object>.gets consumes the end of line and stores the empty string into the s parameter.

HLA high-level calling sequence examples:

filePtr.gets( inputStr );

filePtr.gets( eax ); // EAX contains string value

Like <object>.gets , this function also reads a string from the file. However, rather than storing the string data into a string you supply, this function allocates storage for the string on the heap and returns a pointer to this string in the EAX register. You code should call str.free to release this storage when you’re done with the string data.

The <object>.a_gets function imposes a line length limit of 4,096 characters. If this is a problem, you should modify the source code for this function to raise the limit. This functions raises an exception if you attempt to read a line longer than this internal limit.

HLA high-level calling sequence examples:

MyInputFile.a_gets();

mov( eax, inputStr );

Signed Integer Input

The functions in this group read numeric values from the file using a signed decimal integer format. These functions read the string data, translate it to numeric form, and return that numeric data in an appropriate location.

This function reads a signed eight-bit decimal integer in the range -128..+127 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.geti8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -128..+127. This function returns the binary form of the integer in the AL register.

HLA high-level calling sequence examples:

filePtr.geti8();

mov( al, i8Var );

This function reads a signed 16-bit decimal integer in the range -32768..+32767 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.geti16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -32768..+32767. This function returns the binary form of the integer in the AX register.

HLA high-level calling sequence examples:

filePtr.geti16();

mov( ax, i16Var );

This function reads a signed 32-bit decimal integer in the (approximate) range ±2 Billion from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.geti32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range plus or minus two billion. This function returns the binary form of the integer in the EAX register.

HLA high-level calling sequence examples:

filePtr.geti32();

mov( eax, i32Var );

This function reads a signed 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.geti64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 64-bit signed integer. This function returns the 64-bit result in the EDX:EAX register pair (it returns the H.O. dword in EDX and the L.O. dword in EAX).

HLA high-level calling sequence examples:

filePtr.geti64();

mov( edx, (type dword i64Var[4]) );

mov( eax, (type dword i64Var[0]) );

This function reads a signed 128-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.geti128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 128-bit signed integer. This function stores the 128-bit result into the lword you pass as a reference parameter.

HLA high-level calling sequence examples:

filePtr.geti128( lwordVar );

Unsigned Integer Input

This function reads an unsigned eight-bit decimal integer in the range 0..+255 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.getu8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..255. This function returns the binary form of the integer in the AL register.

HLA high-level calling sequence examples:

MyInputFile.getu8();

mov( al, u8Var );

This function reads an unsigned 16-bit decimal integer in the range 0..+65535 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.getu16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..65535. This function returns the binary form of the integer in the AX register.

HLA high-level calling sequence examples:

filePtr.getu16();

mov( ax, u16Var );

This function reads an unsigned 32-bit decimal integer in the range 0..+4,294,967,295 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.getu32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..4,294,967,295. This function returns the binary form of the integer in the EAX register.

HLA high-level calling sequence examples:

filePtr.getu32();

mov( eax, u32Var );

This function reads an unsigned 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.getu64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..264-1. This function returns the binary form of the integer in EDX:EAX register pair (EDX contains the H.O. dword, EAX holds the L.O. dword).

HLA high-level calling sequence examples:

filePtr.getu32();

mov( eax, (type dword u64Var) );

mov( edx, (type dword u64Var[4]) );

This function reads an unsigned 128-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>.getu64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..2128-1. This function returns the binary form of the integer in the lword parameter you pass by reference.

HLA high-level calling sequence examples:

fileio.getu128( u128Var );

Hexadecimal Input

This function reads an eight-bit hexadecimal integer in the range 0..$FF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>. geth8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FF. This function returns the binary form of the value in the AL register.

HLA high-level calling sequence examples:

filePtr.geth8();

mov( al, h8Var );

This function reads a 16-bit hexadecimal integer in the range 0..$FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>. geth16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF. This function returns the binary form of the value in the AX register.

HLA high-level calling sequence examples:

MyInputFile.geth16();

mov( ax, h16Var );

This function reads a 32-bit hexadecimal integer in the range 0..$FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>. geth32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF. This function returns the binary form of the value in the EAX register.

HLA high-level calling sequence examples:

filePtr.geth32();

mov( eax, h32Var );

This function reads a 64-bit hexadecimal integer in the range 0..$FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>. geth64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF. This function returns the 64-bit result in the EDX:EAX register pair (EDX contains the H.O. dword, EAX contains the L.O. dword).

HLA high-level calling sequence examples:

MyInputFile.geth64();

mov( edx, (type dword h64Var[4]) );

mov( eax, (type dword h64Var[0]) );

This function reads a 128-bit hexadecimal integer in the range 0..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The <object>. getq function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF . This function stores the 128-bit result into the variable you pass as a reference parameter.

HLA high-level calling sequence examples:

filePtr.geth128( lwordVar );

Floating-Point Input

This function reads an 80-bit floating point value in either decimal or scientific from from the file and leaves the result sitting on the FPU stack. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a sequence of characters that represent a floating point value. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. This function raises an appropriate exception if an error occurs.

HLA high-level calling sequence examples:

filePtr.getf();

fstp( fpVar );

Generic File Input

This is a macro that allows you to specify a list of variable names as parameters. The <object>.get macro reads an input value for each item in the list and stores the resulting value in each corresponding variable. This macro determines the type of each variable that you pass it and emits a call to the appropriate <object>.getxxx function to read the actual value. As an example, consider the following call to <object>.get :

filePtr.get( i32, charVar, u16, strVar );

The macro invocation above expands into the following:

push( eax );

filePtr.geti32( i32 );

filePtr.getc();

mov( al, charVar );

filePtr.geti16();

mov( ax, u16 );

filePtr.gets( strVar );

pop( eax );

Notice that <object>.get preserves the value in the EAX register even though various <object>.getxxx functions use this register. Note that <object>.get automatically handles the case where you specify EAX as an input variable and writes the value to [esp] so that in properly modifies EAX upon completion of the macro expansion.

Note that <object>.get only supports eight-, sixteen-, and thirty-two bit integer input. If you need to read 64-bit or 128-bit values, you must use the appropriate <object>.getx64 or <object>.getx128 function to achieve this.

The File I/O Module (fileio.hhf)

This unit contains routines that read data from and write data to files. The fileio functions can be broken down into four generic categories: general functions that open and close files, file position functions that get or set the current file position (or test the file position), output functions that write data to a file, and input functions that read data from a file.

Note to stdlib v1.x users: Several routines originally found in the fileio package have been moved to the new filesys package. The affected routines did not operate on file data, but on the file system itself. Examples include file deletion, get working directory, and change directory. Please see the filesys.rtf documentation for a description of those routines.

Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter.

A Note About the FPU: The Standard Library code makes occasional use of the FPU, particularly when converting between real and string formats and when computung certain mathematical functions. You should exercise caution when using MMX instructions in a program that makes use of the Standard Library. In particular, you should ensure that you are always in FPU mode (by executing an EMMS instruction) after you are finished using MMX instructions. Better yet, you should avoid the MMX instruction set altogether and use the improved SSE instruction set that accomplishes the same tasks (and doesn’t disturb the FPU).

Conversion Format Control

The fileio output functions that convert numeric values to hexadecimal, unsigned decimal, and signed decimal output provide the ability to inject underscores between groups of three (decimal) or four (hexadecimal) digits to make it easier to read large numbers. You enable and disable underscore output using the conv.setUnderscores and conv.getUnderscores functions. Please refer to their documentation in the conv.rtf file for more details.

When reading numeric data from a text file, the fileio functions use an internal delimiters character set to determine which characters may legally end a sequence of numeric digits. You can change the complexion of this character set using the conv.getDelimiters and conv.setDelimiters functions. Please refer to their documentation in the conv.rtf file for more details.

When converting numeric values to string form for output, the fileio routines call the conversion functions found in the conv (conversions) module. For detailed information on the actual conversions, please consult the conv.rtf document.

General File I/O Functions

Here are the file output routines provided by the HLA fileio unit:

Note: fileio.open is part of the os_fileio module in v2.0 of the HLA stdlib. This function has not been updated yet and the semantics may change during the conversion to v2.0.

fileio.open( FileName: string; Access:dword ); @returns( "eax" );

The fileio.open routine opens the file by the specified name. The Access parameter is one of the following:

fileio.r
fileio.w
fileio.rw
fileio.a

The fileio.r constant tells HLA to open the file for read-only access. The fileio.w constant tells HLA to open the file for writing. Using the fileio.rw constant tells fileio.open to open the file for reading and writing. The fileio.a option tells the fileio.open function to open the file for writing and append all written data to the end of the file.

This routine raise an exception if there is a problem opening the file (e.g., the file does not exist). If the file is successfully opened, this function returns the file handle in the EAX register.

HLA high-level calling sequence examples:

fileio.open( "myfile.txt", fileio.r );

mov( eax, fileHandle );

// Note: the Access parameter is almost always a constant in

// calls to fileio.open. However, if you want to pass a variable

// value or a register value in this parameter, you may certainly

// do so:

fileio.open( filenameStr, accessVarByte );

mov( eax, fileHandle );

fileio.open( someStr, al );

mov( eax, fileHandle );

HLA low-level calling sequence examples:

// Constant Access value:

push( filenameStr );

pushd( fileio.r );

call fileio.open;

mov( eax, fileHandle );

// Access value in register (AL in this example)

push( filenameStr );

push( eax );

call fileio.open;

mov( eax, fileHandle );

// Access value is in a (byte) variable

push( filenameStr );

push( (type dword accessValue)); //Not always safe!

call fileio.open;

mov( eax, fileHandle );

// Solution if accessing accessValue as a dword

// might cause a memory access error (last three

// bytes on a 4K page in memory, etc.):

push( filenameStr );

sub( 4, esp );

push( eax );

movzx( accessValue, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.open;

mov( eax, fileHandle );

// Note: If you want to use a string literal, the best solution is

// to create a string object in the readonly section, e.g.,

// readonly

// filenameStr :string := "myfile.txt";

// and just use the "filenameStr" object you’ve created. You may also

// do the following if you have a register available:

lea( eax, "myfile.txt" );

push( eax );

pushd( fileio.r );

call fileio.open;

mov( eax, fileHandle );

fileio.openNew( FileName: string ); @returns( "eax" );

This function opens a new file for writing. The single parameter specifies the file’s (path) name. This function raises an exception if there is an error opening the file. If the file is opened successfully, this function returns the file handle in the EAX register. If the file already exists, this function will successfully open the file and delete any existing data in the file.

HLA high-level calling sequence examples:

fileio.openNew( "myfile.txt" );

mov( eax, fileHandle );

// If the filename string pointer is in a register (EAX):

fileio.openNew( eax );

mov( eax, fileHandle );

HLA low-level calling sequence examples:

push( filenameStr );

call fileio.openNew;

mov( eax, fileHandle );

// If the string pointer value is in a register (EAX

// in this example):

push( eax );

call fileio.openNew;

mov( eax, fileHandle );

// Note: If you want to use a string literal, the best solution is

// to create a string object in the readonly section, e.g.,

// readonly

// filenameStr :string := "myfile.txt";

// and just use the "filenameStr" object you’ve created. You may also

// do the following if you have a register available:

lea( eax, "myfile.txt" );

push( eax );

call fileio.openNew;

mov( eax, fileHandle );

fileio.close( Handle:dword );

This function closes the file specfied by the handle passed as the parameter. You should close all files as soon as you are done using them. Note that successful program termination automatically closes all files, but it is exceeding poor programming practice to rely on the operating system to close any files you’ve left open. Were the machine to crash, data could be lost; for this reason, you should close all files as soon as you are finished reading and writing data.

HLA high-level calling sequence examples:

fileio.close( fileHandle );

// If the file handle is in a register (EAX):

fileio.close( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.close;

// If the file handle is in a register (EAX):

push( eax );

call fileio.close;

fileio.flush( Handle:dword );

This function flushes all pending data to the file (same operation as closing the file, without actually closing it). Note that successful program termination automatically closes all files, but were a crash to occur, some data might be lost. Flushing the file on a periodic basis can help prevent file data loss.

HLA high-level calling sequence examples:

fileio.flush( fileHandle );

// If the file handle is in a register (EAX):

fileio.flush( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.flush;

// If the file handle is in a register (EAX):

push( eax );

call fileio.flush;

fileio.eof( Handle:dword ); @returns( "al" );

This function returns true (1) in AL if the specified file is at the end of file. It returns false (0) otherwise. Note that this function actually returns true/false in EAX even though the "returns" value is "AL". So don’t count on it preserving the value in AH or the upper 16 bits of EAX.

Warning: fileio.eof only functions properly for actual disk files. If you attempt to read data from an interactive device like the system console (keyboard) or a serial port, fileio.eof’s behavior is incorrect (it will wind up eating a character from the interactive input stream every time you call it). Unfortunately, neither Windows nor Linux provides a way to test for EOF until after you’ve actually read a character from the input stream. A better solution, which works fine with both interactive input streams and file data is to use HLA’s try..endtry statement to trap and EOF error when it occurs. For example, rather than writing the following:

while( !fileio.eof( someHandle )) do

endwhile;

You should write the following:

try

forever

endfor;

exception( ex.EndOfFile );

endtry;

Note: under Windows, fileio.eof always returns false for character device files (e.g., keyboard input) and it returns false for all other non-disk file device types. Note that if the user presses ctrl-Z on the keyboard, fileio.eof will not return true, but the system will return an ex.endOfFile exception. If there is any chance you’ll be reading data from a device file rather than a disk file, always use the try..endtry block to test for EOF.

HLA high-level calling sequence examples:

while( !fileio.eof( fileHandle ) ) do

<<something while not at EOF>>

endwhile;

HLA low-level calling sequence examples:

whileNotEOF:

push( fileHandle );

call fileio.flush;

cmp( al, true );

jne atEOF;

<< something while not at EOF>>

jmp whileNotEOF;

atEOF:

fileio.rewind( Handle:dword ); @returns( "eax" );

The Handle parameter specifies the handle of an open file. This function positions the file pointer to the beginning of the file (file position zero). This function returns the error code in EAX.

HLA high-level calling sequence examples:

fileio.rewind( fileHandle );

// If the file handle is in a register (EAX):

fileio.rewind( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.rewind;

// If the file handle is in a register (EAX):

push( eax );

call fileio.rewind;

fileio.append( handle:dword ); @returns( "eax" );

This function positions the file pointer of the file specified by the handle parameter to the end of that file. The file should have been opened for writing.

HLA high-level calling sequence examples:

fileio.append( fileHandle );

// If the file handle is in a register (EAX):

fileio.append( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.append;

// If the file handle is in a register (EAX):

push( eax );

call fileio.append;

fileio.position( Handle:dword ); @returns( "eax" );

This function returns the file position (in bytes) of the file specified by the handle parameter. It returns the file position offset in the EAX register.

HLA high-level calling sequence examples:

fileio.position( fileHandle );

mov( eax, (type dword filePosition));

// If the file handle is in a register (EAX):

fileio.position( eax );

mov( eax, (type dword filePosition));

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.position;

mov( eax, (type dword filePosition));

// If the file handle is in a register (EAX):

push( eax );

call fileio.position;

mov( eax, (type dword filePosition));

fileio.seek( Handle:dword; offset:qword ); @returns( "eax" );

This function sets the file position in the file specified by the Handle parameter to the position specified by the offset parameter. The offset parameter specifies the file position in bytes from the beginning of the file. It returns the error status in EAX.

HLA high-level calling sequence examples:

fileio.seek( fileHandle, qwordOffsetVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordOffsetVar[4]));

push( (type dword qwordOffsetVar));

call fileio.seek;

// If the file handle is in a register (EAX):

push( eax );

push( (type dword qwordOffsetVar[4]));

push( (type dword qwordOffsetVar));

call fileio.seek;

// If the offset is in a register pair (EDX:EAX):

push( fileHandle );

push( edx ); // H.O. dword of offset

push( eax ); // L.O. dword of offset

call fileio.seek;

fileio.rSeek( Handle:dword; offset:qword ); @returns( "eax" );

This function sets the file position in the file specified by the Handle parameter to the position specified by the offset parameter. The offset parameter specifies the file position in bytes from the end of the file. It returns the error status in EAX.

HLA high-level calling sequence examples:

fileio.rSeek( fileHandle, qwordOffsetVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordOffsetVar[4]));

push( (type dword qwordOffsetVar));

call fileio.rSeek;

// If the file handle is in a register (EAX):

push( eax );

push( (type dword qwordOffsetVar[4]));

push( (type dword qwordOffsetVar));

call fileio.rSeek;

// If the offset is in a register pair (EDX:EAX):

push( fileHandle );

push( edx ); // H.O. dword of offset

push( eax ); // L.O. dword of offset

call fileio.rSeek;

fileio.truncate( Handle:dword ); @returns( "eax" );

This function deletes all bytes in the file specified by the Handle parameter from the current file position to the end of the file. It returns the error status in EAX.

HLA high-level calling sequence examples:

fileio.truncate( fileHandle );

// If the file handle is in a register (EAX):

fileio.truncate( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.truncate;

// If the file handle is in a register (EAX):

push( eax );

call fileio.truncate;

fileio.size( Handle:dword ); @returns( "eax" );

This function returns the current size of an open file whose handle you pass as a parameter. It returns the size in the EAX register. Note the overloaded version below.

HLA high-level calling sequence examples:

fileio.size( fileHandle );

mov( eax, fileSize );

// If the file handle is in a register (EAX):

fileio.size( eax );

mov( eax, fileSize );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.size;

mov( eax, fileSize );

// If the file handle is in a register (EAX):

push( eax );

call fileio.size;

mov( eax, fileSize );

File Output Routines

The file output routines in the fileio module are very similar to the file output routines in the file class module as well as the output routines in the standard output library module. In general, these routines require (at least) two parameters; the first is the file handle that you obtain via the fileio.open or fileio.openNew call, the second parameter is usually the value to write to the file. Some function contain additional parameters that provide formatting information. Note that these functions require that you’ve opened the file for writing, reading and writing, for for appending. If the file is not open or you’ve only opened it for reading, these routines will raise an appropriate exception.

Miscellaneous Output Routines

fileio.write( Handle:dword; var buffer:var; count:uns32 );

This procedure writes the number of bytes specified by the count variable to the file. The bytes starting at the address of the buffer byte are written to the file. No range checking is done on the buffer, it is your responsibility to ensure that the buffer contains at least count valid data bytes. Note that buffer is an untyped reference parameter. This means that fileio.write will take the address of whatever object you provide as this parameter (including pointer variables, which may not be what you want). If you want to pass the value of a pointer variable as the buffer address (rather than the address of the pointer variable) when using the high-level style calling syntax, use the VAL keyword as a prefix to the parameter (see the following examples).

HLA high-level calling sequence examples:

fileio.write( fileHandle, buffer, count );

// If bufPtr is a dword object containing the

// address of the buffer whose data you wish to

// write to the file:

fileio.write( fileHandle, val bufPtr, count );

// The following writes the four-byte value of

// the bufPtr variable to the file (an unusual

// operation):

fileio.write( fileHandle, bufPtr, 4 );

HLA low-level calling sequence examples:

// Assumes buffer is a static object at a fixed

// address in memory:

push( fileHandle );

pushd( &buffer );

push( count );

call fileio.write;

// If a 32-bit register is available and buffer

// isn’t at a fixed, static, address:

push( fileHandle );

lea( eax, buffer );

push( eax );

push( count );

call fileio.write;

// If a 32-bit register is not available and buffer

// isn’t at a fixed, static, address:

push( fileHandle );

sub( 4, esp );

push( eax );

lea( eax, buffer );

mov( eax, [esp+4] );

pop( eax );

push( count );

call fileio.write;

// If bufPtr points at the buffer to write,

// then use code like this:

push( fileHandle );

push( bufPtr);

push( count );

call fileio.write;

// To write the 4 bytes at bufPtr to

// the file (unusual), you could use

// code like this:

push( fileHandle );

lea( eax, bufPtr );

push( eax );

pushd( 4 );

call fileio.write;

fileio.newln( Handle:dword )

This function writes a newline sequence (e.g., carriage return/line feed under Windows or line feed under Linux) to the specified output file.

HLA high-level calling sequence examples:

fileio.newln( fileHandle );

// If the file handle is in a register (EAX):

fileio.newln( eax );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.newln;

// If the file handle is in a register (EAX):

push( eax );

call fileio.newln;

fileio.putbool( Handle:dword; b:boolean )

This procedure writes the string "true" or "false" to the output file depending on the value of the b parameter.

HLA high-level calling sequence examples:

fileio.putbool( fileHandle, boolVar );

// If the boolean is in a register (AL):

fileio.putbool( fileHandle, al );

HLA low-level calling sequence examples:

// If "boolVar" is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword boolVar ) );

call fileio.putbool;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( boolVar , eax ); // Assume EAX is available

push( eax );

call fileio.putbool;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( boolVar , eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putbool;

// If the boolean value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume boolVar is in AL

call fileio.putbool;

// If the Boolean value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume boolVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.putbool;

Character, String, and Character Set Output Routines

fileio.putc( Handle:dword; c:char )

Writes the character specified by the c parameter to the file specified by the Handle parameter.

HLA high-level calling sequence examples:

fileio.putc( fileHandle, charVar );

// If the character is in a register (AL):

fileio.putc( fileHandle, al );

HLA low-level calling sequence examples:

// If "charVar" is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword charVar) );

call fileio.putc;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( charVar, eax ); // Assume EAX is available

push( eax );

call fileio.putc;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( charVar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putc;

// If the character value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume charVar is in AL

call fileio.putc;

// If the character value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume charVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.putc;

fileio.putcSize( Handle:dword; c:char; width:int32; fill:char )

Outputs the character c to the file using at least width output positions. If the absolute value of width is greater than one, then this function writes fill characters as padding characters during the output. If width is a positive value greater than one, then fileio.putcSize writes c left justfied in a field of width characters; if width is a negative value less than one, then fileio.putcSize writes c right justified in a field of width characters.

HLA high-level calling sequence examples:

fileio.putcSize( fileHandle, charVar, width, padChar );

HLA low-level calling sequence examples:

// If "charVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword charVar) );

push( width );

push( (type dword padChar) );

call fileio.putcSize;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( charVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putcSize;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( charVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putcSize;

// If "charVar" or "padChar" are in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume charVar is in AL

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.putcSize;

// Do the following if the characters are

// in AH, BH, CH, or DH:

push( fileHandle );

xchg( al, ah ); // Assume charVar is in AH

xchg( bl, bh ); // Assume padChar is in BH

push( eax );

push( width );

push( ebx );

xchg( al, ah );

xchg( bl, bh );

call fileio.putcSize;

fileio.putcset( Handle:dword; cst:cset )

This function writes all the members of the cst character set parameter to the file specified by the Handle variable.

HLA high-level calling sequence examples:

fileio.putcset( fileHandle, csVar );

fileio.putcset( fileHandle, [ebx] ); // EBX points at the cset.

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword csVar[12]) ); // Push H.O. dword first

push( (type dword csVar[8]) );

push( (type dword csVar[4]) );

push( (type dword csVar) ); // Push L.O. dword last

call fileio.putcset;

fileio.puts( Handle:dword; s:string )

This procedure writes the value of the string parameter to the specified file. Remember, string values are actually 4-byte pointers to the string’s character data.

HLA high-level calling sequence examples:

fileio.puts( fileHandle, strVar );

fileio.puts( fileHandle, ebx ); // EBX holds a string value.

fileio.puts( fileHandle, "Hello World" );

HLA low-level calling sequence examples:

// For string variables:

push( fileHandle );

push( strVar );

call fileio.puts;

// For string values held in registers:

push( fileHandle );

push( ebx ); // Assume EBX holds the string value

call fileio.puts;

// For string literals, assuming a 32-bit register

// is available:

push( fileHandle );

lea( eax, "Hello World" ); // Assume EAX is available.

push( eax );

call fileio.puts;

// If a 32-bit register is not available:

readonly

literalString :string := "Hello World";

push( fileHandle );

push( literalString );

call fileio.puts;

fileio.putsSize( Handle:dword; s:string; width:int32; fill:char )

This function writes the s string to the file using at least width character positions. If the absolute value of width is less than or equal to the length of s , then this function behaves exactly like fileio.puts . On the other hand, if the absolute value of width is greater than the length of s , then fileio.putsSize writes width characters to the output file. This procedure emits the fill character in the extra print positions. If width is positive, then fileio.putsSize right justifies the string in the print field. If width is negative, then fileio.putsSize left justifies the string in the print field. Generally, people expect the string to be left justified, so you should ensure that this value is negative to achieve this.

HLA high-level calling sequence examples:

fileio.putsSize( fileHandle, strVar, width, ‘ ‘ );

// For the following, EBX holds the string value,

// ECX contains the width, and AL holds the pad

// character:

fileio.putsSize( fileHandle, ebx, ecx, al );

fileio.putsSize( fileHandle, "Hello World", 25, padChar );

HLA low-level calling sequence examples:

// For string variables:

push( fileHandle );

push( strVar );

push( width );

pushd( ‘ ‘ );

call fileio.putsSize;

// For string values held in registers:

push( fileHandle );

push( ebx ); // Assume EBX holds the string value

push( ecx ); // Assume ECX holds the width

push( eax ); // Assume AL holds the fill character

call fileio.putsSize;

// For string literals, assuming a 32-bit register

// is available:

push( fileHandle );

lea( eax, "Hello World" ); // Assume EAX is available.

push( eax );

pushd( 25 );

movzx( padChar, eax );

push( eax );

call fileio.putsSize;

// If a 32-bit register is not available:

readonly

literalString :string := "Hello World";

// Note: element zero is the actual pad character.

// The other elements are just padding.

padChar :char[4] := [ ‘.’, #0, #0, #0 ];

push( fileHandle );

push( literalString );

pushd( 25 );

push( (type dword padChar) );

call fileio.putsSize;

Hexadecimal Output Routines

fileio.putb( Handle:dword; b:byte )

This procedure writes the value of b to the file using exactly two hexadecimal digits (including a leading zero if necessary).

HLA high-level calling sequence examples:

fileio.putb( fileHandle, byteVar );

// If the character is in a register (AL):

fileio.putb( fileHandle, al );

HLA low-level calling sequence examples:

// If "byteVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar ) );

call fileio.putb;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar , eax ); // Assume EAX is available

push( eax );

call fileio.putb;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( byteVar , eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putb;

// If the character value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

call fileio.putb;

// If the byte value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.putb;

fileio.puth8( Handle:dword; b:byte )

This procedure writes the value of b to the file using the minimum necessary number of hexadecimal digits.

HLA high-level calling sequence examples:

fileio.puth8( fileHandle, byteVar );

// If the character is in a register (AL):

fileio.puth8( fileHandle, al );

HLA low-level calling sequence examples:

// If "byteVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar ) );

call fileio.puth8;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar , eax ); // Assume EAX is available

push( eax );

call fileio.puth8;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( byteVar , eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth8;

// If the character value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

call fileio.puth8;

// If the byte value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.puth8;

fileio.puth8Size( Handle:dword; b:byte; size:dword; fill:char )

The fileio.puth8Size function writes an 8-bit hexadecimal value to a file allowing you specify a minimum field width and a fill character.

HLA high-level calling sequence examples:

fileio.puth8Size( fileHandle, byteVar, width, padChar );

HLA low-level calling sequence examples:

// If "byteVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar) );

push( width );

push( (type dword padChar) );

call fileio.puth8Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth8Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( byteVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth8Size;

// If "byteVar" or "padChar" are in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.puth8Size;

// Do the following if the characters are

// in AH, BH, CH, or DH:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

xchg( bl, bh ); // Assume padChar is in BH

push( eax );

push( width );

push( ebx );

xchg( al, ah );

xchg( bl, bh );

call fileio.puth8Size;

fileio.putw( Handle:dword; w:word )

This procedure writes the value of w to the file using exactly four hexadecimal digits (including leading zeros if necessary).

HLA high-level calling sequence examples:

fileio.putw( fileHandle, wordVar );

// If the word is in a register (AX):

fileio.putw( fileHandle, ax );

HLA low-level calling sequence examples:

// If "wordVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

call fileio.putw;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

call fileio.putw;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putw;

// If the word value is in a 16-bit register

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

call fileio.putw;

fileio.puth16( Handle:dword; w:word )

This procedure writes the value of w to the file using the minimum necessary number of hexadecimal digits.

HLA high-level calling sequence examples:

fileio.puth16( fileHandle, wordVar );

// If the word is in a register (AX):

fileio.puth16( fileHandle, ax );

HLA low-level calling sequence examples:

// If "wordVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

call fileio.puth16;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

call fileio.puth16;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth16;

// If the word value is in a 16-bit register

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

call fileio.puth16;

fileio.puth16Size( Handle:dword; w:word; size:dword; fill:char )

The fileio.puth16Size function writes a 16-bit hexadecimal value to a file allowing you specify a minimum field width and a fill character.

HLA high-level calling sequence examples:

fileio.puth16Size( fileHandle, wordVar, width, padChar );

HLA low-level calling sequence examples:

// If "wordVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

push( width );

push( (type dword padChar) );

call fileio.puth16Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth16Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth16Size;

// If "wordVar" is in a 16-bit register

// and "padChar" is in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.puth16Size;

fileio.putd( Handle:dword; d:dword )

This procedure writes the value of d to the file using exactly eight hexadecimal digits (including leading zeros if necessary), if underscore output is not enabled. This routine will emit nine characters (eight digits plus an underscore) if underscore output is enabled.

HLA high-level calling sequence examples:

fileio.putd( fileHandle, dwordVar );

// If the dword value is in a register (EAX):

fileio.putd( fileHandle, eax );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

call fileio.putd;

push( fileHandle );

push( eax );

call fileio.putd;

fileio.puth32( Handle:dword; d:dword )

This procedure writes the value of d to the file using the minimum number of hexadecimal digits necessary. If underscore output is enabled (see conv.setUnderscores and conv.getUnderscores) then this function will emit an underscore between groups of four hexadecimal digits, starting from the least signficant digit.

HLA high-level calling sequence examples:

fileio.puth32( fileHandle, dwordVar );

// If the dword is in a register (EAX):

fileio.puth32( fileHandle, eax );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

call fileio.puth32;

push( fileHandle );

push( eax );

call fileio.puth32;

fileio.puth32Size( Handle:dword; d:dword; size:dword; fill:char )

The fileio.puth32Size function outputs d as a hexadecimal string (including underscores, if enabled) and it allows you specify a minimum field width and a fill character.

HLA high-level calling sequence examples:

fileio.puth32Size( fileHandle, dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

fileio.puth32Size( fileHandle, eax, width, cl );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

push( width );

pushd( ‘ ‘ );

call fileio.puth32Size;

push( fileHandle );

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.puth32Size;

// Assume fill char is in CH

push( fileHandle );

push( eax );

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puth32Size;

// Alternate method of the above

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puth32Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( eax );

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth32Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( eax );

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puth32Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth32Size;

fileio.putq( Handle:dword; q:qword )

This procedure writes the value of q to the file using exactly sixteen hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.putq( fileHandle, qwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

call fileio.putq;

fileio.puth64( Handle:dword; q:qword )

This procedure writes the value of q to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.puth64( fileHandle, qwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

call fileio.puth64;

fileio.puth64Size( Handle:dword; q:qword; size:dword; fill:char )

The fileio.putqSize function lets you specify a minimum field width and a fill character. The fileio.putq routine uses a minimum size of two and a fill character of ’0’. Note that if underscore output is enabled, this routine will emit 19 characters (16 digits plus three underscores).

HLA high-level calling sequence examples:

fileio.puth64Size( fileHandle, qwordVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.puth64Size;

push( fileHandle );

push( edx ); // Assume 64-bit value in edx:eax

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.puth64Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puth64Size;

// Alternate method of the above

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puth64Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth64Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puth64Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth64Size;

fileio.puttb( Handle:dword; tb:tbyte )

This procedure writes the value of tb to the file using exactly 20 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.puttb( fileHandle, tbyteVar );

HLA low-level calling sequence examples:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

call fileio.puttb;

fileio.puth80( Handle:dword; tb:tbyte )

This procedure writes the value of tb to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.puth80( fileHandle, tbyteVar );

HLA low-level calling sequence examples:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

call fileio.puth80;

fileio.puth80Size( Handle:dword; tb:tbyte; size:dword; fill:char )

The fileio.puth80Size function lets you specify a minimum field width and a fill character. It writes the tbyte value tb as a hexadecimal string to the specified file using the provided minimum size and fill character.

HLA high-level calling sequence examples:

fileio.puth80Size( fileHandle, tbyteVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.puth80Size;

// Assume fill char is in CH

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puth80Size;

// Alternate method of the above

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puth80Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth80Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puth80Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

pushw( 0 ); // Push push a 0 pad word

push( (type word tbyteVar[8])); // Push H.O. word first

push( (type dword tbyteVar[4]) ); // M.O. dword second

push( (type dword tbyteVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth80Size;

fileio.putl( Handle:dword; l:lword )

This procedure writes the value of l to the file using exactly 32 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.putl( fileHandle, lwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12]) ); // H.O. dword first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

call fileio.putl;

fileio.puth128( Handle:dword; l:lword )

This procedure writes the value of l to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled).

HLA high-level calling sequence examples:

fileio.puth128( fileHandle, lwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12]) ); // H.O. dword first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

call fileio.puth128;

fileio.puth128Size( Handle:dword; l:lword; size:dword; fill:char )

The fileio.puth128Size function writes an lword value to the file and it lets you specify a minimum field width and a fill character.

HLA high-level calling sequence examples:

fileio.puth128Size( fileHandle, tbyteVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.puth128Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puth128Size;

// Alternate method of the above

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puth128Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puth128Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puth128Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puth128Size;

Signed Integer Output Routines

These routines convert signed integer values to string format and write that string to the file specified by the Handle parameter. The fileio.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

These functions print the fill character as the padding value for the extra print positions.

Note that unlike floating point values, these functions do not print a space in front of the value if it is non-negative.

fileio.puti8 ( Handle:dword; b:byte )

This function converts the eight-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.puti8( fileHandle, byteVar );

// If the character is in a register (AL):

fileio.puti8( fileHandle, al );

HLA low-level calling sequence examples:

// If "byteVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar ) );

call fileio.puti8;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar , eax ); // Assume EAX is available

push( eax );

call fileio.puti8;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( byteVar , eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti8;

// If the character value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

call fileio.puti8;

// If the byte value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.puti8;

fileio.puti8Size ( Handle:dword; b:byte; width:int32; fill:char )

This function writes the eight-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.puti8Size( fileHandle, byteVar, width, padChar );

HLA low-level calling sequence examples:

// If "byteVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar) );

push( width );

push( (type dword padChar) );

call fileio.puti8Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puti8Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( byteVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti8Size;

// If "byteVar" or "padChar" are in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.puti8Size;

// Do the following if the characters are

// in AH, BH, CH, or DH:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

xchg( bl, bh ); // Assume padChar is in BH

push( eax );

push( width );

push( ebx );

xchg( al, ah );

xchg( bl, bh );

call fileio.puti8Size;

fileio.puti16( Handle:dword; w:word )

This function converts the 16-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.puti16( fileHandle, wordVar );

// If the word is in a register (AX):

fileio.puti16( fileHandle, ax );

HLA low-level calling sequence examples:

// If "wordVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

call fileio.puti16;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

call fileio.puti16;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti16;

// If the word value is in a 16-bit register

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

call fileio.puti16;

fileio.puti16Size( Handle:dword; w:word; width:int32; fill:char )

This function writes the 16-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.puti16Size( fileHandle, wordVar, width, padChar );

HLA low-level calling sequence examples:

// If "wordVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

push( width );

push( (type dword padChar) );

call fileio.puti16Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puti16Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti16Size;

// If "wordVar" is in a 16-bit register

// and "padChar" is in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.puti16Size;

fileio.puti32( Handle:dword; d:dword )

This function converts the 32-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.puti32( fileHandle, dwordVar );

// If the dword is in a register (EAX):

fileio.puti32( fileHandle, eax );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

call fileio.puti32;

push( fileHandle );

push( eax );

call fileio.puti32;

fileio.puti32Size( Handle:dword; d:dword; width:int32; fill:char )

This function writes the 32-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.puti32Size( fileHandle, dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

fileio.puti32Size( fileHandle, eax, width, cl );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

push( width );

pushd( ‘ ‘ );

call fileio.puti32Size;

push( fileHandle );

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.puti32Size;

// Assume fill char is in CH

push( fileHandle );

push( eax );

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puti32Size;

// Alternate method of the above

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puti32Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( eax );

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puti32Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( eax );

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puti32Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti32Size;

fileio.puti64( Handle:dword; q:qword )

This function converts the 64-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.puti64( fileHandle, qwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

call fileio.puti64;

fileio.puti64Size( Handle:dword; q:qword; width:int32; fill:char )

This function writes the 64-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.puti64Size( fileHandle, qwordVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.puti64Size;

push( fileHandle );

push( edx ); // Assume 64-bit value in edx:eax

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.puti64Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puti64Size;

// Alternate method of the above

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puti64Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puti64Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puti64Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti64Size;

fileio.puti128( Handle:dword; l:lword )

This function converts the 128-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.puti128( fileHandle, lwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12]) ); // H.O. dword first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

call fileio.puti128;

fileio.puti128Size( Handle:dword; l:lword; width:int32; fill:char )

This function writes the 128-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.puti128Size( fileHandle, lwordVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.puti128Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.puti128Size;

// Alternate method of the above

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.puti128Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.puti128Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.puti128Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.puti128Size;

Unsigned Integer Output Routines

These routines convert unsigned integer values to string format and write that string to the file specified by the Handle parameter. The fileio.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

These functions print the fill character as the padding value for the extra print positions.

fileio.putu8 ( Handle:dword; b:byte )

This function converts the eight-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.putu8( fileHandle, byteVar );

// If the character is in a register (AL):

fileio.putu8( fileHandle, al );

HLA low-level calling sequence examples:

// If "byteVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar ) );

call fileio.putu8;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar , eax ); // Assume EAX is available

push( eax );

call fileio.putu8;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( byteVar , eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu8;

// If the character value is in al, bl, cl, or dl

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

call fileio.putu8;

// If the byte value is in ah, bh, ch, or dh

// you’ll have to use code like the following:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

push( eax ); // It’s now in AL

xchg( al, ah ); // Restore al/ah

call fileio.putu8;

fileio.putu8Size( Handle:dword; b:byte; width:int32; fill:char )

This function writes the unsigned eight-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.putu8Size( fileHandle, byteVar, width, padChar );

HLA low-level calling sequence examples:

// If "byteVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword byteVar) );

push( width );

push( (type dword padChar) );

call fileio.putu8Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( byteVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putu8Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( byteVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu8Size;

// If "byteVar" or "padChar" are in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume byteVar is in AL

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.putu8Size;

// Do the following if the characters are

// in AH, BH, CH, or DH:

push( fileHandle );

xchg( al, ah ); // Assume byteVar is in AH

xchg( bl, bh ); // Assume padChar is in BH

push( eax );

push( width );

push( ebx );

xchg( al, ah );

xchg( bl, bh );

call fileio.putu8Size;

fileio.putu16( Handle:dword; w:word )

This function converts the 16-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.putu16( fileHandle, wordVar );

// If the word is in a register (AX):

fileio.putu16( fileHandle, ax );

HLA low-level calling sequence examples:

// If "wordVar " is not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

call fileio.putu16;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

call fileio.putu16;

// If no register is available, do something

// like the following code:

push( fileHandle );

sub( 4, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu16;

// If the word value is in a 16-bit register

// then you can use code like the following:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

call fileio.putu16;

fileio.putu16Size( Handle:dword; w:word; width:int32; fill:char )

This function writes the unsigned 16-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.putu16Size( fileHandle, wordVar, width, padChar );

HLA low-level calling sequence examples:

// If "wordVar" and "padChar" are not one of the last three

// bytes on a page of memory, you can do this:

push( fileHandle );

push( (type dword wordVar) );

push( width );

push( (type dword padChar) );

call fileio.putu16Size;

// If you can’t guarantee that the previous code

// won’t generate an illegal memory access, and a

// 32-bit register is available, use code like

// the following:

push( fileHandle );

movzx( wordVar, eax ); // Assume EAX is available

push( eax );

push( width );

movzx( padChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putu16Size;

// If no registers are available, do something

// like the following code:

push( fileHandle );

sub( 12, esp );

push( eax );

movzx( wordVar, eax );

mov( eax, [esp+12] );

mov( width, eax );

mov( eax, [esp+8] );

movzx( padChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu16Size;

// If "wordVar" is in a 16-bit register

// and "padChar" is in an

// 8-bit register, then you can push

// the corresponding 32-bit register if

// the register is AL, BL, CL, or DL:

push( fileHandle );

push( eax ); // Assume wordVar is in AX

push( width );

push( ebx ); // Assume padChar is in BL

call fileio.putu16Size;

fileio.putu32( Handle:dword; d:dword )

This function converts the 32-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.putu32( fileHandle, dwordVar );

// If the dword is in a register (EAX):

fileio.putu32( fileHandle, eax );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

call fileio.putu32;

push( fileHandle );

push( eax );

call fileio.putu32;

fileio.putu32Size( Handle:dword; d:dword; width:int32; fill:char )

This function writes the unsigned 32-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.putu32Size( fileHandle, dwordVar, width, ‘ ‘ );

// If the dword is in a register (EAX):

fileio.putu32Size( fileHandle, eax, width, cl );

HLA low-level calling sequence examples:

push( fileHandle );

push( dwordVar );

push( width );

pushd( ‘ ‘ );

call fileio.putu32Size;

push( fileHandle );

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.putu32Size;

// Assume fill char is in CH

push( fileHandle );

push( eax );

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.putu32Size;

// Alternate method of the above

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.putu32Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( eax );

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putu32Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( eax );

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.putu32Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( eax );

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu32Size;

fileio.putu64( Handle:dword; q:qword )

This function converts the 64-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.putu64( fileHandle, qwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

call fileio.putu64;

fileio.putu64Size( Handle:dword; q:qword; width:int32; fill:char )

This function writes the unsigned 64-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.putu64Size( fileHandle, qwordVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.putu64Size;

push( fileHandle );

push( edx ); // Assume 64-bit value in edx:eax

push( eax );

push( width );

push( ecx ); // fill char is in CL

call fileio.putu64Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.putu64Size;

// Alternate method of the above

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.putu64Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putu64Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.putu64Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword qwordVar[4]) ); // H.O. dword first

push( (type dword qwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu64Size;

fileio.putu128( Handle:dword; l:lword )

This function converts the 128-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle ) using the minimum number of print positions the number requires.

HLA high-level calling sequence examples:

fileio.putu128( fileHandle, lwordVar );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12]) ); // H.O. dword first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

call fileio.putu128;

fileio.putu128Size( Handle:dword; l:lword; width:int32; fill:char )

This function writes the unsigned 128-bit value you pass to the specified output file using the width and fill values as specified above.

HLA high-level calling sequence examples:

fileio.putu128Size( fileHandle, lwordVar, width, ‘ ‘ );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

pushd( ‘ ‘ );

call fileio.putu128Size;

// Assume fill char is in CH

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

xchg( cl, ch ); // fill char is in CH

push( ecx );

xchg( cl, ch );

call fileio.putu128Size;

// Alternate method of the above

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

mov( ch, [esp] );

call fileio.putu128Size;

// If the fill char is a variable and

// a register is available, try this code:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

movzx( fillChar, ebx ); // Assume EBX is available

push( ebx );

call fileio.putu128Size;

// If the fill char is a variable and

// no register is available, here’s one

// possibility:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

push( (type dword fillChar) ); // Chance of page crossing!

call fileio.putu128Size;

// In the very rare case that the above would

// cause an illegal memory access, use this:

push( fileHandle );

push( (type dword lwordVar[12])); // Push H.O. word first

push( (type dword lwordVar[8]) );

push( (type dword lwordVar[4]) );

push( (type dword lwordVar)); // L.O. dword last

push( width );

sub( 4, esp );

push( eax );

movzx( fillChar, eax );

mov( eax, [esp+4] );

pop( eax );

call fileio.putu128Size;

Floating Point Output Routines

The HLA file I/O class provides several procedures you can use to write floating point files to a text file. The following subsections describe these routines.

Real Output Using Scientific Notation

The floating point numeric output routines translate the three different binary floating point formats to their string representation and then write this string to the file that the Handle parameter specifies. There are two generic classes of these routines: those that convert their values to exponential/scientific notation and those that convert their string to a decimal form.

The fileio.pute80 , fileio.pute64 , and fileio.pute32 routines convert their values to a string using scientific notation. These three routines each have two parameters: the value to output and the field width of the result. These routines produce a string with the following format:

fileio.pute32( Handle:dword; r:real32; width:uns32 )

HLA high-level calling sequence examples:

fileio.pute32( fileHandle, r32Var, width );

// If the real32 value is in an FPU register (ST0):

var

r32Temp :real32;

fstp( r32Temp );

fileio.pute32( fileHandle, r32Temp, 12 );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword r32Var) );

push( width );

call fileio.pute32;

push( fileHandle );

sub( 4, esp );

fstp( (type real32 [esp]) );

pushd( 12 );

call fileio.pute32;

fileio.pute64( Handle:dword; r:real64; width:uns32 )

HLA high-level calling sequence examples:

fileio.pute64( fileHandle, r64Var, width );

// If the real64 value is in an FPU register (ST0):

var

r64Temp :real64;

fstp( r64Temp );

fileio.pute64( fileHandle, r64Temp, 12 );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword r64Var[4]));

push( (type dword r64Var[0]));

push( width );

call fileio.pute64;

push( fileHandle );

sub( 8, esp );

fstp( (type real64 [esp]) );

pushd( 12 );

call fileio.pute64;

fileio.pute80( Handle:dword; r:real80; width:uns32 )

HLA high-level calling sequence examples:

fileio.pute80( fileHandle, r80Var, width );

// If the real80 value is in an FPU register (ST0):

var

r80Temp :real80;

fstp( r80Temp );

fileio.pute80( fileHandle, r80Temp, 12 );

HLA low-level calling sequence examples:

push( fileHandle );

pushw( 0 ); // A word of padding.

push( (type word r80Var[8]));

push( (type dword r80Var[4]));

push( (type dword r80Var[0]));

push( width );

call fileio.pute80;

push( fileHandle );

sub( 12, esp );

fstp( (type real80 [esp]) );

pushd( 12 );

call fileio.pute80;

Real Output Using Decimal Notation

Although scientific (exponential) notation is the most general display format for real numbers, real numbers you display in this format are very difficult to read. Therefore, the HLA fileio module also provides a set of functions that output real values using the decimal representation. Although you cannot (practically) use these decimal output routines for all real values, they are applicable to a wide variety of common numbers you will use in your programs.

These functions come in two varieties. The first variety requires five parameters: the real value to convert, the width of the converted value, the number of digit positions to the right of the decimal point, and a padding character. The second variety only requires the first four parameters and assumes the padding character is a space. These functions write their values using the following string format:

fileio.putr32( Handle:dword; r:real32; width:uns32; decpts:uns32; pad:char )

This procedure writes a 32-bit single precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters. The number is right-justified within the output field (that is, this function prints the padding characters before the string representation of the number).

HLA high-level calling sequence examples:

fileio.putr32( fileHandle, r32Var, width, decpts, fill );

fileio.putr32( fileHandle, r32Var, 10, 2, ‘*’ );

// If the real32 value is in an FPU register (ST0):

var

r32Temp :real32;

fstp( r32Temp );

fileio.putr32( fileHandle, r32Temp, 12, 2, al );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword r32Var) );

push( width );

push( decpts );

movzx( fill, eax );

push( eax );

call fileio.putr32;

push( fileHandle );

push( (type dword r32Var) );

push( width );

push( decpts );

pushd( (type dword fill) ); // If no memory fault possible

call fileio.putr32;

push( fileHandle );

sub( 4, esp );

fstp( (type real32 [esp]) );

pushd( 12 );

sub( 4, esp );

push( eax );

movzx( fill, eax ): // If memory fault were possible

mov( eax, [esp+4] ); // in above code.

pop( eax );

call fileio.putr32;

fileio.putr64( Handle:dword; r:real64; width:uns32; decpts:uns32; pad:char )

This procedure writes a 64-bit double precision floating point value to the file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

HLA high-level calling sequence examples:

fileio.putr64( fileHandle, r64Var, width, decpts, fill );

fileio.putr64( fileHandle, r64Var, 10, 2, ‘*’ );

// If the real64 value is in an FPU register (ST0):

var

r64Temp :real64;

fstp( r64Temp );

fileio.putr64( fileHandle, r64Temp, 12, 2, al );

HLA low-level calling sequence examples:

push( fileHandle );

push( (type dword r64Var[4]) );

push( (type dword r64Var) );

push( width );

push( decpts );

movzx( fill, eax );

push( eax );

call fileio.putr64;

push( fileHandle );

push( (type dword r64Var[4]) );

push( (type dword r64Var) );

push( width );

push( decpts );

pushd( (type dword fill) ); // If no memory fault possible

call fileio.putr64;

push( fileHandle );

sub( 8, esp );

fstp( (type real64 [esp]) );

pushd( 12 );

sub( 4, esp );

push( eax );

movzx( fill, eax ): // If memory fault were possible

mov( eax, [esp+4] ); // in above code.

pop( eax );

call fileio.putr64;

fileio.putr80( Handle:dword; r:real80; width:uns32; decpts:uns32; pad:char )

This procedure writes an 80-bit extended precision floating point value to the file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

HLA high-level calling sequence examples:

fileio.putr80( fileHandle, r80Var, width, decpts, fill );

fileio.putr80( fileHandle, r80Var, 10, 2, ‘*’ );

// If the real80 value is in an FPU register (ST0):

var

r80Temp :real80;

fstp( r80Temp );

fileio.putr80( fileHandle, r80Temp, 12, 2, al );

HLA low-level calling sequence examples:

push( fileHandle );

pushw( 0 );

push( (type word r80Var[8]) );

push( (type dword r80Var[4]) );

push( (type dword r80Var) );

push( width );

push( decpts );

movzx( fill, eax );

push( eax );

call fileio.putr80;

push( fileHandle );

pushw( 0 );

push( (type word r80Var[8]) );

push( (type dword r80Var[4]) );

push( (type dword r80Var) );

push( width );

push( decpts );

pushd( (type dword fill) ); // If no memory fault possible

call fileio.putr80;

push( fileHandle );

sub( 12, esp );

fstp( (type real80 [esp]) );

pushd( 12 );

sub( 4, esp );

push( eax );

movzx( fill, eax ): // If memory fault were possible

mov( eax, [esp+4] ); // in above code.

pop( eax );

call fileio.putr80;

Generic File Output Routine

fileio.put( list_of_items )

fileio.put is a macro that automatically invokes an appropriate fileio output routine based on the type of the parameter(s) you pass it. This is a very convenient output routine and is probably the fileio output call you will use most often in your programs. Keep in mind that this macro is not a single function call; instead, HLA translates this macro into a sequence of calls to procedures like fileio.putu32 , fileio.puts , etc.

fileio.put is a macro that provides a flexible syntax for outputting data to the standard output device. This macro allows a variable number of parameters. For each parameter present in the list, fileio.put will call the appropriate routine to emit that data, according to the type of the parameter. Parameters may be constants, registers, or memory locations. You must separate each macro parameter with a comma.

Here is an example of a typical invocation of fileio.put:

fileio.put( fileHandle, "I=", i, " j=", j, nl );

The above is roughly equivalent to

fileio.puts( fileHandle, "I=" );

fileio.putu32( fileHandle, i );

fileio.puts( fileHandle, " j=" );

fileio.putu32( fileHandle, j );

fileio.newln(fileHandle);

This assumes, of course, that i and j are int32 variables.

The fileio.put macro also lets you specify the minimum field width for each parameter you specify. To print a value using a minimum field width, follow the object you wish to print with a colon and the value of the minimum field width. The previous example, using field widths, could look like the following:

fileio.put( fileHandle, "I=", i:2, " j=", j:5, nl );

Although this example used the literal decimal constants two and five for the field widths, keep in mind that register values and memory value (integers, anyway) are prefectly legal here.

fileio.put( fileHandle, "Real value is ", f:10:3, nl );

The fileio.put macro can handle all the basic primitive types, including boolean, unsigned (8, 16, 32, 64, 128), signed (8, 16, 32, 64, 128), character, character set, real (32, 64, 80), string, and hexadecimal (byte, word, dword, qword, lword).

If you specify a class variable (object) and that class defines a " toString " method, then fileio.put macro will call the associated toString method and output that string to the file. Note that the toString method must dynamically allocate storage for the string by calling stralloc . This is because fileio.put will call strfree on the string once it outputs the string.

There is a known "design flaw" in the fileio.put macro. You cannot use it to print HLA intermediate variables (i.e., non-local VAR objects). The problem is that HLA’s syntax for non-local accesses takes the form "reg32:varname" and fileio.put cannot determine if you want to print reg32 using varname print positions versus simply printing the non-local varname object. If you want to display non-local variables you must copy the non-local object into a register, a static variable, or a local variable prior to using fileio.put to print it. Of course, there is no problem using the other fileio.putXXXX functions to display non-local VAR objects, so you can use those as well.

File Input Routines

The HLA Standard Library provides a complementary set of file input routines. These routines behave in a fashion quite similar to the stdin.XXXX routines. See those routines for a additional examples of these procedures.

General File Input Routines

fileio.read( Handle:dword; var buffer:byte; count:uns32 )

This routine reads a sequence of count bytes from the specified file, storing the bytes into memory at the address specified by buffer .

HLA high-level calling sequence examples:

fileio.read( fileHandle, buffer, count );

fileio.read( fileHandle, [eax], 1024 );

HLA low-level calling sequence examples:

// If buffer is a static variable:

push( fileHandle );

pushd( &buffer );

push( count );

call fileio.read;

// If buffer is not static, 32-bit register available:

push( fileHandle );

lea( eax, buffer );

push( eax );

push( count );

call fileio.read;

// If buffer is not static, no register available:

push( fileHandle );

sub( 4, esp );

push( eax );

lea( eax, buffer );

mov( eax, [esp+4] );

pop( eax );

push( count );

call fileio.read;

fileio.readLn( Handle:dword );

This function reads, and discards, all characters in the file up to the next newline sequence (or end of file).

HLA high-level calling sequence examples:

fileio.readLn( fileHandle );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.readLn;

fileio.eoln( Handle:dword ); @returns( "al" );

This function returns true (1) in EAX if the file is at the end of a line (note that the "returns" value is "al" even though this function returns its result in all of EAX). This function eats the newline sequence from the input.

HLA high-level calling sequence examples:

fileio.eoln( fileHandle );

mov( al, eolnVar );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.eoln;

mov( al, eolnVar );

Character and String Input Routines

The following functions read character data from an input file specified by filevar . Note that HLA’s fileio module does not provide the ability to read character set data directly from the user. However, you can always read a string and then convert that string to a character set using the appropriate function in the cset module.

fileio.getc( Handle:dword ); @returns( "al" );

This function reads a single character from the file and returns that chraacter in the AL register. This function assumes that the file you’ve opened is a text file. Note that fileio.getc does not return the end of line sequence as part of the input stream. Use the fileio.eoln function to determine when you’ve reached the end of a line of text. Because fileio.getc preprocesses the text file (removing end of line sequences) you should not use it to read binary data, use it only to read text files.

fileio.gets( Handle:dword; s:string );

This function reads a sequence of characters from the current file position through to the next end of line sequence and stores these characters (without the end of line sequence) into the string variable you pass as a parameter. Before calling this routine, you must allocate sufficient storage for the string. If fileio.gets attempts to read a larger string than the string’s MaxStrLen value, fileio.gets raises a string overflow exception.

Note that this function does not store the end of line sequence into the string, though it does consume the end of line sequence. The next character a fileio function will read from the file will be the first character of the following line.

If the current file position is at the end of some line of text, then fileio.gets consumes the end of line and stores the empty string into the s parameter.

HLA high-level calling sequence examples:

fileio.gets( fileHandle, inputStr );

fileio.gets( fileHandle, eax ); // EAX contsins string value

HLA low-level calling sequence examples:

push( fileHandle );

push( inputStr );

call fileio.gets;

push( fileHandle );

push( eax );

call fileio.gets;

fileio.a_gets( Handle:dword ); @returns( "eax" );

Like fileio.gets , this function also reads a string from the file. However, rather than storing the string data into a string you supply, this function allocates storage for the string on the heap and returns a pointer to this string in the EAX register. You code should call strfree to release this storage when you’re done with the string data.

The fileio.a_gets function imposes a line length limit of 1,024 characters. If this is a problem, you should modify the source code for this function to raise the limit. This functions raises an exception if you attempt to read a line longer than this internal limit.

HLA high-level calling sequence examples:

fileio.a_gets( fileHandle );

mov( eax, inputStr );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.a_gets;

mov( eax, inputStr );

Signed Integer Input Routines

fileio.geti8( Handle:dword ); @returns( "al" );

This function reads a signed eight-bit decimal integer in the range -128..+127 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geti8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -128..+127. This function returns the binary form of the integer in the AL register.

HLA high-level calling sequence examples:

fileio.geti8( fileHandle );

mov( al, i8Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geti8;

mov( al, i8Var );

fileio.geti16( Handle:dword ); @returns( "ax" );

This function reads a signed 16-bit decimal integer in the range -32768..+32767 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geti16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -32768..+32767. This function returns the binary form of the integer in the AX register.

HLA high-level calling sequence examples:

fileio.geti16( fileHandle );

mov( ax, i16Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geti16;

mov( ax, i16Var );

fileio.geti32( Handle:dword ); @returns( "eax" );

This function reads a signed 32-bit decimal integer in the (approximate) range ±2 Billion from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geti32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range plus or minus two billion. This function returns the binary form of the integer in the EAX register.

HLA high-level calling sequence examples:

fileio.geti32( fileHandle );

mov( eax, i32Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geti32;

mov( eax, i32Var );

fileio.geti64( Handle:dword );

This function reads a signed 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geti64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 64-bit signed integer. This function returns the 64-bit result in EDX:EAX.

HLA high-level calling sequence examples:

fileio.geti64( fileHandle );

mov( edx, (type dword i64Var[4]) );

mov( eax, (type dword i64Var[0]) );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geti64;

mov( edx, (type dword i64Var[4]) );

mov( eax, (type dword i64Var[0]) );

fileio.geti128( Handle:dword; var dest:lword );

This function reads a signed 128-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geti128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 128-bit signed integer. This function stores the 128-bit result in the lword you pass as a reference parameter.

HLA high-level calling sequence examples:

fileio.geti128( fileHandle, lwordVar );

HLA low-level calling sequence examples:

// If lwordVar is a static variable:

push( fileHandle );

pushd( &lwordVar );

call fileio.geti128;

// If lwordVar is a not static variable

// and a 32-bit register is available:

push( fileHandle );

lea( eax, lwordVar ); // Assume EAX is available

push( eax);

call fileio.geti128;

Unsigned Integer Input Routines

fileio.getu8( Handle:dword ); @returns( "al" );

This function reads an unsigned eight-bit decimal integer in the range 0..+255 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.getu8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..255. This function returns the binary form of the integer in the AL register.

HLA high-level calling sequence examples:

fileio.getu8( fileHandle );

mov( al, u8Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.getu8;

mov( al, u8Var );

fileio.getu16( Handle:dword ); @returns( "ax" );

This function reads an unsigned 16-bit decimal integer in the range 0..+65535 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.getu16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..65535. This function returns the binary form of the integer in the AX register.

HLA high-level calling sequence examples:

fileio.getu16( fileHandle );

mov( ax, u16Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.getu16;

mov( ax, u16Var );

fileio.getu32( Handle:dword ); @returns( "eax" );

This function reads an unsigned 32-bit decimal integer in the range 0..+4,294,967,295 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.getu32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..4,294,967,295. This function returns the binary form of the integer in the EAX register.

HLA high-level calling sequence examples:

fileio.getu32( fileHandle );

mov( eax, u32Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.getu32;

mov( eax, u32Var );

fileio.getu64( Handle:dword );

This function reads an unsigned 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.getu64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..264-1. This function returns the binary form of the integer in the the EDX:EAX registers.

fileio.getu128( Handle:dword; var dest:lword );

This function reads an unsigned 128-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.getu128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..2128-1. This function returns the binary form of the integer in the lword parameter you pass by reference.

HLA high-level calling sequence examples:

fileio.getu64( fileHandle );

mov( edx, (type dword u64Var[4]) );

mov( eax, (type dword u64Var[0]) );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.getu64;

mov( edx, (type dword u64Var[4]) );

mov( eax, (type dword u64Var[0]) );

Hexadecimal Input Routines

fileio.geth8( Handle:dword ); @returns( "al" );

This function reads an eight-bit hexadecimal integer in the range 0..$FF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geth function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FF. This function returns the binary form of the value in the AL register.

HLA high-level calling sequence examples:

fileio.geth8( fileHandle );

mov( al, h8Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geth8;

mov( al, h8Var );

fileio.geth16( Handle:dword ); @returns( "ax" );

This function reads a 16-bit hexadecimal integer in the range 0..$FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geth16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF. This function returns the binary form of the value in the AX register (zero-extended into EAX).

HLA high-level calling sequence examples:

fileio.geth16( fileHandle );

mov( ax, h16Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geth16;

mov( ax, h16Var );

fileio.geth32( Handle:dword ); @returns( "eax" );

This function reads a 32-bit hexadecimal integer in the range 0..$FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geth32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF. This function returns the binary form of the value in the EAX register.

HLA high-level calling sequence examples:

fileio.geth32( fileHandle );

mov( eax, h32Var );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geth32;

mov( eax, h32Var );

fileio.geth64( Handle:dword );

This function reads a 64-bit hexadecimal integer in the range 0..$FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geth64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF. This function returns the 64-bit result in the EDX:EAX register pair.

HLA high-level calling sequence examples:

fileio.geth64( fileHandle );

mov( edx, (type dword h64Var[4]) );

mov( eax, (type dword h64Var[0]) );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.geth64;

mov( edx, (type dword h64Var[4]) );

mov( eax, (type dword h64Var[0]) );

fileio.geth128( Handle:dword; var dest:lword );

This function reads a 128-bit hexadecimal integer in the range zero through $FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The fileio.geth128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF. This function stores the 128-bit result into the variable you pass as a reference parameter.

HLA high-level calling sequence examples:

fileio.geth128( fileHandle, lwordVar );

HLA low-level calling sequence examples:

// If lwordVar is a static variable:

push( fileHandle );

pushd( &lwordVar );

call fileio.geth128;

// If lwordVar is a not static variable

// and a 32-bit register is available:

push( fileHandle );

lea( eax, lwordVar ); // Assume EAX is available

push( eax);

call fileio.geth128;

Floating Point Input

fileio.getf( Handle:dword );

HLA high-level calling sequence examples:

fileio.getf( fileHandle );

fstp( fpVar );

HLA low-level calling sequence examples:

push( fileHandle );

call fileio.getf;

fstp( fpVar );

Generic File Input

fileio.get( List_of_items_to_read );

This is a macro that allows you to specify a list of variable names as parameters. The fileio.get macro reads an input value for each item in the list and stores the resulting value in each corresponding variable. This macro determines the type of each variable that you pass it and emits a call to the appropriate fileio.getxxx function to read the actual value. As an example, consider the following call to filevar.get :

fileio.get( i32, charVar, u16, strVar );

The macro invocation above expands into the following:

push( eax );

fileio.geti32( i32 );

fileio.getc();

mov( al, charVar );

fileio.geti16();

mov( ax, u16 );

fileio.gets( strVar );

pop( eax );

Notice that fileio.get preserves the value in the EAX and EDX registers even though various fileio.getxxx functions use these registers. Note that fileio.get automatically handles the case where you specify EAX as an input variable and writes the value to [esp] so that in properly modifies EAX upon completion of the macro expansion.

Note that fileio.get supports eight-bit, 16-bit, 32-bit, 64-bit, and 128-bit input values. It automatically selects the approriate input routine based on the type of the variable you specify.

The File System Module (filesys.hhf)

The filesys functions perform file system manipulations (as opposed to the fileio package that operates on files).

Filename and Pathname String Functions

These functions test and manipulate pathname strings. Most of them do not do any actual file system access, they simply modify a string passed to them.

The file and pathname string functions are relatively OS-neutral. As long as you avoid a few OS-specific filename features (such as Win32 drive letter prefixes and the use of backslash [‘\’] characters in Unix-like OS filenames), you’ll find that these functions are highly portable between various operating systems. These functions automatically convert pathname separator characters to the native OS (except for the functions that explicitly produce Win32-style or Unix-style pathnames). So you can write applications that process pathnames and automatically work with whatever OS the application is running under.

This documentation will use the standard UNIX ‘/’ pathname separator character. Anywhere you see a "/" used in the following examples, just note that you can also use a "\" and the function will still work properly (you can even have a mixture of these two separator characters in the same pathname string and the function will accept this). Keep in mind that most filesys pathname functions will convert all ‘/’ and ‘\’ characters to the native directory separator character; take care if you expect to process Win32 filenames under a UNIX-like OS and you need to keep the Win32 separator characters.

For the purposes of the filesys string functions, a pathname is considered to contain up to five components: a UNC prefix, a path component, a filename component, a basename component, and an extension. These components are not necessarily unique (that is, some of them overlap one another). Not all pathnames contain all of these components. Consider the following valid pathname string:

fsType://computerName/SharedFolder/path1/path2/base.ext

This example pathname contains the following components:

UNC: fsType://computerName/SharedFolder

path: fsType://computerName/SharedFolder/path1/path2

filename: base.ext

basename: base

extension ext

UNC (Universal Naming Convention) names take two basic forms:

//computerName/sharedFolderName

fsType://computerName/sharedFolderName

UNC names contain an optional file system type name followed by a colon. All UNC names contain ‘//’ followed by a computer name which is then followed by a ‘/’ and a shared folder name.

Path components consist of everything to the left of the last ‘/’ appearing in a path name string. Note that a UNC component is also part of a path component. Indeed, if a UNC immediately precedes a filename, then the UNC sequence is the path component (note, however, that a path component may include other subdirectory names in addition to the UNC character sequence). If there is nothing to the left of the last (i.e., only) ‘/’ in a pathname string, then the "/" is the path component.

The filename component is everything appearing to the right of the last ‘/’ character in the pathname string, or the whole pathname string if there is no ‘/’ character in the pathname string.

The basename and extension components are part of the filename. If the filename contains at least one period and that period is not the first character of the filename, then everything to the left of the (last) period is the basename and everything to the right of the (last) period is the extension. If a filename contains multiple periods, then everything up to (but not including) the last period is the basename. If the filename contains only one period and it begins with that period, then the filename has no extension and the basename is equal to the filename. Likewise, if a filename contains no periods at all, it has no extension and the basename is equal to the filename.

procedure filesys.hasDriveLetter( pathname:string ); @returns( "@c" );

This function returns the Win32 drive letter if the pathname argument begins with a single alphabetic character, immediately followed by a colon (‘:’) and the colon is not immediately followed by a pair of slashes (indicating a UNC name). Drive letters are Win32-specific, although this function can be called on any pathname string. If a drive letter is present, this function returns the drive letter in AL, converted to uppercase, and also returns with the carry flag set. If there is no drive letter at the beginning of the name (or if it looks like a UNC name), then this function returns with EAX containing zero and the carry flag clear.

Note that the function "returns" value for this function is "@c" (that is, the carry flag) and not "AL". This allows you to use the function call within a boolean expression (e.g., in an "if" statement) and test for true/false return values.

HLA high-level calling sequence examples:

if( filesys.hasDriveLetter( somePath )) then

stdout.put( "Drive is ", (type char al), nl );

str.delete( somePath, 0, 2 ); // Delete the drive letter

endif;

HLA low-level calling sequence example:

push( somePath );

call filesys.hasDriveLetter;

jnc noDriveLetter;

push( somePath );

pushd( 0 );

pushd( 2 );

call str.delete;

noDriveLetter:

procedure filesys.hasExtension( pathname:string ); @returns( "@c" );

This function returns true if the filename component of the pathname argumen contains an extension. An extension is the last part of a pathname following the last period in the filename. Note that if a filename begins with a period and that is the only period in the filename, then the following characters are not an extension (and the extension is the empty string for such a name). Note that periods found in the path to the filename are not considered when this function searches for the extension. Extensions only belong to filename components, not to path components.

Examples:

filesys.hasExtension( "/path/file.ext" ); // true, extension = "ext"

filesys.hasExtension( "file" ); // false

filesys.hasExtension( ".ext" ); // false

filesys.hasExtension( "file.ext" ); // true, extension = "ext"

filesys.hasExtension( "file.abc.ext" ); // true, extension = "ext"

filesys.hasExtension( "..ext" ); // true, extension = "ext"

filesys.hasExtension( "path.ext/file" ); // false

The true/false result is returned both in the carry flag and in the EAX/AX/AL register. The carry flag is set if the argument has an extension, it is clear otherwise. Similarly, true (1) is returned in EAX/AX/AL if the argument has an extension, false (0) is returned otherwise.

HLA high-level calling sequence examples:

filesys.hasExtension( somePath );

mov( al, somePathHasExtension );

if( @c ) then

<< do something if somePath has an extension >>

endif;

HLA low-level calling sequence example:

push( somePath );

call filesys.hasExtension;

jnc noExtension;

<< Do something if somePath has an extension>>

noExtension:

procedure filesys.hasUncName( pathname:string ); @returns( "@c" );

This function tests the pathname argument to see if it begins with a UNC (universal naming convention) pathname prefix. UNC prefixes take one of two forms (as far as this code is concerned):

//computername/sharedfolder/<path>

<type>://computername/sharedfolder/<path>

<type> can be any string of filename-compatible characters (length one or greater), such as ‘file’, ‘smb’, and so on. <path> may be any OS-compatible pathname of length zero or greater (up to the maximum length supported by the native OS). Portable code should not allow the pathname string (including the UNC) to except about 250 characters.

This function returns true or false in the carry flag indicating whether a UNC, if present, is syntactically correct. That is, this function returns carry clear if there is something that looks like a UNC but is syntactically illegal. Note that a pathname, without an explicit "//computername/sharedfolder/" prefix is still a syntactically correct pathname as far as this function is concerned. That is, this function returns true for pathnames like "name" or "/path/name" even though an explicit UNC item is not present.

This function returns information about the UNC prefix in the EAX register. If this function returns with EAX equal to zero and the carry set, then there is no UNC present in the pathname. If this function returns with EAX containing a value other than zero (and the carry flag set), then a UNC is present and EAX contains an offset into the string that is the start of the pathname just beyond the end of the UNC sequence (i.e., beyond the ‘/’ or ‘\’ that marks the end of the UNC name).

Note: on failure (carry = 0 ), EAX will be returned containing zero.

HLA high-level calling sequence examples:

if( filesys.hasUncName( somePath ) && eax <> 0 ) then

str.delete( somePath, 0, eax ); // Delete the UNC prefix

endif;

HLA low-level calling sequence example:

push( somePath );

call filesys.hasUncName;

jnc noUNC;

test( eax, eax );

jz noUNC;

push( somePath );

pushd( 0 );

push( eax );

call str.delete;

noUNC:

procedure filesys.hasPath( pathname:string ); @returns( "@c" );

This function returns true if the pathname/filename argument contains a path component. Specifically, this function returns true if the pathname string contains any directory separator characters (‘/’ or ‘\’). True is returned in the carry flag (set) and in the EAX/AX/AL register (1). False is carry = 0 or the EAX/AX/AL register equals 0. Note that UNC prefixes immediately before a filename are considered ‘paths’ and this function will return true if a UNC is present.

Examples:

filesys.hasPath( "/path/file.ext" ); // true

filesys.hasPath( "file" ); // false

filesys.hasPath( ".ext" ); // false

filesys.hasPath( "file.ext" ); // false

filesys.hasPath( "file.abc.ext" ); // false

filesys.hasPath( "//machine/folder/file" ); // true

filesys.hasPath( "/" ); // true

HLA high-level calling sequence examples:

filesys.hasPath( somePath );

mov( al, somePathHasAPathComponent );

if( @c ) then

<< do something if somePath has a path component>>

endif;

HLA low-level calling sequence example:

push( somePath );

call filesys.hasPath;

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

procedure filesys.a_extractBase( pathname:string ); @returns( "c" );

This function extracts and returns the base component of a filename. This function allocates storage for the returned basename on the heap and returns a pointer to that string in the EAX register. If a basename exists, this function returns true in the carry flag (set). If no basename exists (e.g., when the filename ends with ‘/’ so it contains no filename component or if the pathname argument is the empty string), then this function returns a pointer to an empty string allocated on the heap in EAX and it returns with the carry flag clear. It is the caller’s responsibility to free the storage associated with the string when the caller is done using that string.

Note that this function’s "returns" value is "@c", not EAX. This allows you to use this function in an HLA boolean expression (e.g., in an "if" statement) to test whether the basename is actually valid (that is, it’s not an empty string). Don’t forget that you still have to free the storage associated with the string, even if it is the empty string.

HLA high-level calling sequence examples:

filesys.a_extractBase( somePath );

mov( eax, basePtr );

if( @c ) then

<<do something with the basename pointed at by basePtr>>

endif;

str.free( basePtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_extractBase;

mov( eax, basePtr );

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

str.free( basePtr );

procedure filesys.extractBase( pathname:string; base:string );
@returns( "c" );

This function extracts and returns the base component of a filename. It extracts the base filename from the pathname argument and stores the result into the string storage pointed at by the base argument. The base argument must point at allocated storage sufficient to hold the base name string or this function will raise an exception. This function returns with the carry flag set if it finds (and copies) a basename component of the pathname. It returns with the carry flag clear if there is no base name component (which implies that pathname ends wth a ‘/’ character or is the empty string).

HLA high-level calling sequence examples:

filesys.extractBase( somePath, baseName );

if( @c ) then

<<do something with the basename held in baseName>>

endif;

HLA low-level calling sequence example:

push( somePath );

push( baseName );

call filesys.extractBase;

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

procedure filesys.a_extractExt( pathname:string ); @returns( "c" );

This function extracts and returns the extension component of a filename. This function allocates storage for the returned extension on the heap and returns a pointer to that string in the EAX register. If an extension exists, this function returns true in the carry flag (set). If no extension exists (e.g., when the filename component contains no periods), then this function returns a pointer to an empty string allocated on the heap in EAX and it returns with the carry flag clear. It is the caller’s responsibility to free the storage associated with the string when the caller is done using that string.

Note that this function’s "returns" value is "@c", not EAX. This allows you to use this function in an HLA boolean expression (e.g., in an "if" statement) to test whether the extension is actually valid (that is, it’s not an empty string). Don’t forget that you still have to free the storage associated with the string, even if it is the empty string.

HLA high-level calling sequence examples:

filesys.a_extractExt( somePath );

mov( eax, extPtr );

if( @c ) then

<<do something with the extension pointed at by extPtr>>

endif;

str.free( extPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_extractExt;

mov( eax, extPtr );

jnc noPath;

<< Do something if somePath has an extension component>>

noPath:

str.free( extPtr );

procedure filesys.extractExt( pathname:string; ext:string ); @returns( "c" );

This function extracts and returns the extension component of a filename. It extracts the extension from the pathname argument and stores the result into the string storage pointed at by the ext argument. The ext argument must point at allocated storage sufficient to hold the extension string or this function will raise an exception. This function returns with the carry flag set if it finds (and copies) an extension component of the pathname. It returns with the carry flag clear if there is no extension component (which implies that filename component contains no periods or is the empty string).

HLA high-level calling sequence examples:

filesys.extractExt( somePath, extName );

if( @c ) then

<<do something with the extension held in extName>>

endif;

HLA low-level calling sequence example:

push( somePath );

push( extName );

call filesys.extractExt;

jnc noPath;

<< Do something if somePath has an extension component>>

noPath:

procedure filesys.a_extractFilename( pathname:string ); @returns( "c" );

This function extracts and returns the filename component of a pathname. This function allocates storage for the returned filename on the heap and returns a pointer to that string in the EAX register. If a filename component exists, this function returns true in the carry flag (set). If no filename exists (e.g., when the pathname ends with a ‘/’ or is the empty string), then this function returns a pointer to an empty string allocated on the heap in EAX and it returns with the carry flag clear. It is the caller’s responsibility to free the storage associated with the string when the caller is done using that string.

Note that this function’s "returns" value is "@c", not EAX. This allows you to use this function in an HLA boolean expression (e.g., in an "if" statement) to test whether the filename is actually valid (that is, it’s not an empty string). Don’t forget that you still have to free the storage associated with the string, even if it is the empty string.

HLA high-level calling sequence examples:

filesys.a_extractFilename( somePath );

mov( eax, fnPtr );

if( @c ) then

<<do something with the filename pointed at by fnPtr>>

endif;

str.free( fnPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_extractFilename;

mov( eax, fnPtr );

jnc noPath;

<< Do something if somePath has a filename component>>

noPath:

str.free( fnPtr );

procedure filesys.extractFilename( pathname:string; filename:string );
@returns( "c" );

This function extracts and returns the filename component of a pathname. It extracts the filename from the pathname argument and stores the result into the string storage pointed at by the filename argument. The filename argument must point at allocated storage sufficient to hold the filename string or this function will raise an exception. This function returns with the carry flag set if it finds (and copies) a filename component of the pathname. It returns with the carry flag clear if there is no filename component (which implies that pathname component ends with a ‘/’ or is the empty string).

HLA high-level calling sequence examples:

filesys.extractFilename( somePath, filename );

if( @c ) then

<<do something with the string held in filename>>

endif;

HLA low-level calling sequence example:

push( somePath );

push( filename );

call filesys.extractFilename;

jnc noPath;

<< Do something if somePath has a filename component>>

noPath:

procedure filesys.a_extractPath( pathname:string ); @returns( "c" );

This function extracts and returns the path component of a pathname string. This function allocates storage for the returned path on the heap and returns a pointer to that string in the EAX register. If a path component exists, this function returns true in the carry flag (set). If no path component exists (e.g., when the pathname argument contains no ‘/’ characters or is the empty string), then this function returns a pointer to an empty string allocated on the heap in EAX and it returns with the carry flag clear. It is the caller’s responsibility to free the storage associated with the string when the caller is done using that string.

Note that this function’s "returns" value is "@c", not EAX. This allows you to use this function in an HLA boolean expression (e.g., in an "if" statement) to test whether the path is actually valid (that is, it’s not an empty string). Don’t forget that you still have to free the storage associated with the string, even if it is the empty string.

HLA high-level calling sequence examples:

filesys.a_extractPath( somePath );

mov( eax, pathPtr );

if( @c ) then

<<do something with the path pointed at by pathPtr>>

endif;

str.free( pathPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_extractPath;

mov( eax, pathPtr );

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

str.free( pathPtr );

procedure filesys.extractPath( pathname:string; path:string );
@returns( "c" );

This function extracts and returns the path component of a pathname string. It extracts the path from the pathname argument and stores the result into the string storage pointed at by the path argument. The path argument must point at allocated storage sufficient to hold the string or this function will raise an exception. This function returns with the carry flag set if it finds (and copies) a path component of the pathname. It returns with the carry flag clear if there is no path component (which implies that pathname component contains no ‘/’ characters or is the empty string).

Note that the path string that this function returns will include any UNC prefixes and any Win32 drive letters that are present in the original pathname. If you need a path result that doesn’t contain any drive letter prefixes, call filesys.hasDriveLetter on the result and delete the first two character of the string if there is a drive letter present. If you need a string without a UNC prefix present, then call filesys.hasUncName on the path result and delete the first EAX characters from the path string if filesys.hasUncName reports that a UNC name is present.

HLA high-level calling sequence examples:

filesys.extractPath( somePath, pathComponent );

if( @c ) then

<<do something with the string held in pathComponent >>

endif;

HLA low-level calling sequence example:

push( somePath );

push( pathComponent );

call filesys.extractPath;

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

procedure filesys.a_joinPaths( leftPath:string; rightPath:string );
@returns( "eax" );

This function concatenates two path strings, adding a directory separator character between them (if necessary). Because of the wide variety of special cases that can occur when concatenating two paths, this function is fairly complex. The operation is described in the following table.


If leftPath…	If rightPath…	Then the resulting path string…
Is empty	Is empty	Is empty.
Ends with ‘/’	Does not begin with ‘/’	Is just the concatenation of the two strings.
Does not end with ‘/’	Begins with ‘/’	Is just the concatenation of the two strings.
Ends with ‘/’	Begins with ‘/’	Is the concatenation of the two strings with one of the ‘/’ characters removed.
Does not end with ‘/’	Does not begin with ‘/’	Is the concatenation of the leftPath with ‘/’ and then the rightPath string.

Note that, unlike many of the other filesys file/path string functions, this function does not return a failure/success status in the carry flag. This function always succeeds (or it raises an exception if an exceptional condition exists).

HLA high-level calling sequence examples:

filesys.a_joinPaths( leftPath, RightPath );

mov( eax, pathPtr );

<<do something with the path pointed at by pathPtr>>

str.free( pathPtr );

HLA low-level calling sequence example:

push( leftPath );

push( rightPath

call filesys.a_joinPaths;

mov( eax, pathPtr );

<< Do something with the string pointed at by pathPtr>>

str.free( pathPtr );

procedure filesys.joinPaths
(
leftPath:string;
rightPath:string;
joinedPath:string
);

This function combines the leftPath and rightPath strings to form a joinedPath string. For the exact details on the concatenation operation, please see the table appearing in the description of the filesys.a_joinPaths function. This function will raise an exception if the string storage pointed at by joinedPaths is not large enough to hold the result. Note that the calculation for string overflow is computed as the sum of the lengths of leftPath and rightPath plus one, even though (in some cases) the required length might need only be the sum of the lengths of the leftPath and rightPath strings. Therefore, you should ensure that the storage allocated for the joinedPath string is at least one character larger than the sum of the two substrings or this function may raise an exception, even if joinedPath turns out to be large enough to hold the actual result.

HLA high-level calling sequence examples:

filesys.joinPaths( leftPath, rightPath, newPath );

<<do something with the string held in newPath >>

HLA low-level calling sequence example:

push( leftPath );

push( rightPath );

push( newPath

call filesys.joinPaths;

<< Do something with newPath>>

procedure filesys.a_normalize( pathname:string ); @returns( "c" );

This function normalizes the pathname passed as the argument and returns a pointer to the normalized pathname in EAX. This function allocates storage for the normalized pathname on the heap; it is the caller’s responsibility to free that storage when the application is done using the string.

A normalized pathname is one that has all the directory separators converted to the native format, has all path components of the form "./" deleted from the path string, and has all path components of the form "path/../" deleted from the path string. Note, however, that if "../" appears at the beginning of a path string, or "../" appears immediately after a UNC path sequence, then the normalized result still contains the "../". Likewise, if there are multiple "../" sequences within a path string and deleting the previous paths would delete a UNC component or would attempt to delete a path sequence before any appearing in the path string, then this function leaves the "../" component present (e.g., "path/../../name" produces the string "../name").

This function returns the carry flag set if it was able to produce a correct normalized string. This function returns with the carry flag clear if the pathname argument contained an unparseable UNC name prefix or other syntax error (in which case the function ignores the UNC prefix and treats the UNC like any other path sequence).

HLA high-level calling sequence examples:

filesys.a_normalize( somePath );

mov( eax, pathPtr );

if( @c ) then

<<do something with the path pointed at by pathPtr>>

endif;

str.free( pathPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_extractPath;

mov( eax, pathPtr );

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

str.free( pathPtr );

procedure filesys.normalize1( pathname:string );
@returns( "c" );

This function nornalizes, in place, the pathname string passed as an argument. On returns, the pathname string contains the normalized result of the original string passed into this function. Note that normalized strings are always the same length or shorter than the original string, so there is no chance of string overflow occuring when normalizing a path string. For details on the normalization process, see the description of the filesys.a_normalize function.

This function returns with the carry flag set if it successfully normalizes the pathname argument and there are no UNC parse errors or other problems. If this function cannot parse a string that looks like it has a UNC prefix, it will treat pathname as though it has no UNC prefix, normalize that, and return with the carry flag clear.

Because this function normalizes the string in place, the pathname argument must point at string data in writeable memory or else this function will raise an exception.

HLA high-level calling sequence examples:

filesys.normalize1( somePath );

if( @c ) then

<<do something with the string held in somePath >>

endif;

HLA low-level calling sequence example:

push( somePath );

call filesys.normalize1;

jnc noPath;

<< Do something with somePath>>

noPath:

procedure filesys.normalize2( pathname:string; path:string );
@returns( "c" );

This function nornalizes the pathname string passed as an argument and stores the normalized result into the string object pointed at by path. The path object must have at least as much space allocated for it as the length of the pathname argument or this function will raise an exception; this exception will be raised even if the actual normalized string would be shorter than the length of pathname and path is actually large enough to hold the actual normalized string. The test for string overflow takes place before the normalization operation begins because this function first copies pathname to path and then performs the normalization operation on path. For details on the normalization process, see the description of the filesys.a_normalize function.

HLA high-level calling sequence examples:

filesys.extractPath( somePath, pathComponent );

if( @c ) then

<<do something with the string held in pathComponent >>

endif;

HLA low-level calling sequence example:

push( somePath );

push( pathComponent );

call filesys.extractPath;

jnc noPath;

<< Do something if somePath has a path component>>

noPath:

procedure filesys.a_toUnixPath( pathname:string ); @returns( "eax" );

This function converts a string to the Unix format. This entails converting all ‘\’ characters to ‘/’ characters in the pathname string. Note that this function does not process any drive letter prefixes. If a drive letter prefix is present in the pathname argument, this function returns that drive letter prefix in the result string.

This function returns a pointer to tne converted string, which is allocated on the heap, in the EAX register. It is the caller’s responsibility to free the storage associated with this string when the caller is done using the string data.

HLA high-level calling sequence examples:

filesys.a_toUnixPath( somePath );

mov( eax, unixPathPtr );

<<do something with the path pointed at by unixPathPtr >>

str.free( unixPathPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_toUnixPath;

mov( eax, unixPathPtr );

<< Do something with unixPathPtr>>

str.free( unixPathPtr );

procedure filesys.toUnixPath1( pathname:string );

This function converts the string argument to UNIX format by replacing all ‘\’ characters with ‘/’ ‘ characters. Note that this function does not process any drive letter prefixes. If a drive letter prefix is present in the pathname argument, this function returns that drive letter prefix in the result string. Converted strings are always the same length as the original string, so there is no chance of string overflow occuring when converting a path string to UNIX format.

Because this function normalizes the string in place, the pathname argument must point at string data in writeable memory or else this function will raise an exception.

HLA high-level calling sequence examples:

filesys.toUnixPath1( somePath );

<<do something with the string held in somePath >>

HLA low-level calling sequence example:

push( somePath );

call filesys.toUnixPath1;

<< Do something with somePath>>

procedure filesys.toUnixPath2( pathname:string; unixPath:string );

This function converts the pathname string argument to UNIX format by replacing all ‘\’ characters with ‘/’ characters. It stores the resulting string into unixPath. Note that this function does not process any drive letter prefixes. If a drive letter prefix is present in the pathname argument, this function returns that drive letter prefix in the result string. Converted strings are always the same length as the original string, so the storage pointed at by the unixPath argument must be able to hold at least as many characters as the current length of the pathname argument or this function will raise an exception.

HLA high-level calling sequence examples:

filesys.toUnixPath2( somePath, unixPath );

<<do something with the string held in unixPath>>

HLA low-level calling sequence example:

push( somePath );

push( unixPath );

call filesys.toUnixPath2;

<< Do something with unixPath>>

procedure filesys.a_toWin32Path( pathname:string ); @returns( "eax" );

This function converts a pathname string to the Windows format. This entails converting all ‘/’ characters to ‘\’ characters in the pathname string.

This function returns a pointer to the converted string, which is allocated on the heap, in the EAX register. It is the caller’s responsibility to free the storage associated with this string when the caller is done using the string data.

HLA high-level calling sequence examples:

filesys.a_toWin32Path( somePath );

mov( eax, win32PathPtr );

<<do something with the path pointed at by win32PathPtr >>

str.free( win32PathPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_toWin32Path;

mov( eax, win32PathPtr );

<< Do something with win32PathPtr >>

str.free( win32PathPtr );

procedure filesys.toWin32Path1( pathname:string );

This function converts the pathname string argument to Windows format by replacing all ‘/’ characters with ‘\’ ‘ characters. Converted strings are always the same length as the original string, so there is no chance of string overflow occuring when converting a path string to UNIX format.

Because this function normalizes the string in place, the pathname argument must point at string data in writeable memory or else this function will raise an exception.

HLA high-level calling sequence examples:

filesys.toWin32Path1( somePath );

<<do something with the string held in somePath >>

HLA low-level calling sequence example:

push( somePath );

call filesys.toWin32Path1;

<< Do something with somePath>>

procedure filesys.toWin32Path2( pathname:string; windowsPath:string );

This function converts the pathname string argument to Windows format by replacing all ‘/’ characters with ‘\’ ‘ characters. It stores the resulting string into windowsPath. Converted strings are always the same length as the original string, so the storage pointed at by the windowsPath argument must be able to hold at least as many characters as the current length of the pathname argument or this function will raise an exception.

HLA high-level calling sequence examples:

filesys.toWin32Path2( somePath, windowsPath );

<<do something with the string held in windowsPath >>

HLA low-level calling sequence example:

push( somePath );

push( windowsPath );

call filesys.toWin32Path2;

<< Do something with windowsPath >>

procedure filesys.a_toNativePath( pathname:string );
procedure filesys.toNativePath1( pathname:string );
procedure filesys.toNativePath2( pathname:string; windowsPath:string );

These functions are synonyms for either the toUnix functions or the toWin32 functions, depending upon the operating system under which you’re compiling them. That is, under Windows, these functions are synonyms for the filesys.a_toWin32Path, filesys.toWin32Path1, and filesys.toWin32Path2 functions. Under other Oses, these functions are synonyms for the filesys.a_toUnixPath, filesys.toUnixPath1, and filesys.toUnixPath2 functions.

Functionally, this procedures convert the pathname passed as an argument to the native OS pathname format. Note that these functions ignore drive letters if they are converting pathnames to UNIX format (that is, the drive letters will still be present in the converted string).

procedure filesys.a_getFullPathName( partialPath:string ); @returns( "eax" );

This function takes the partialPath passed as a parameter and converts it to a full, absolute, pathname. If partialPath begins with a ‘/’ character, this function simply returns partialPath’s value as its result. If partialPath does not begin with a ‘/’ character, then this function determines the working directory path and concatenates (via filesys.joinPaths) partialPath to the end of the current working directory and returns that full path string.

This function returns a pointer to the full pathname string, which is allocated on the heap, in the EAX register. It is the caller’s responsibility to free the storage associated with this string when the caller is done using the string data.

HLA high-level calling sequence examples:

filesys.a_getFullPath( somePath );

mov( eax, fullPathPtr );

<<do something with the path pointed at by fullPathPtr>>

str.free( fullPathPtr );

HLA low-level calling sequence example:

push( somePath );

call filesys.a_getFullPath;

mov( eax, fullPathPtr );

<< Do something with fullPathPtr >>

str.free( fullPathPtr );

procedure filesys.getFullPath( partialPath:string; resultPath:string );

HLA high-level calling sequence examples:

filesys.getFullPath( somePath, fullPath );

<<do something with the string held in fullPath>>

HLA low-level calling sequence example:

push( somePath );

push( fullPath );

call filesys.getFullPath;

<< Do something with fullPath>>

Directory and File Predicates

These functions test some condition about a file or directory and return true or false in the EAX register.

procedure filesys.exists( pathname:string ); @returns( "eax" );

This function returns true if the file exists and the application can open the file (at least for reading). It returns false in EAX if the file does not exist, is inaccessible, or there is some other error that occurs when attemting to open the file.

HLA high-level calling sequence examples:

filesys.exists( "someFilename" );

mov( al, someFilenameExists ); // someFileNameExists:boolean;

HLA low-level calling sequence examples:

someFilename:string := "someFileName";

push( someFileName );

call filesys.exists;

mov( al, someFilenameExists );

procedure filesys.isFile( FileName:string ); @returns( "eax" );

This function returns true if the file exists and is actually a file (rather than a directory) and the application can open the file (at least for reading). It returns false in EAX if the file does not exist, exists but is a directory, is inaccessible, or there is some other error that occurs when attemting to open the file.

HLA high-level calling sequence examples:

filesys.isFile( "someFilename" );

mov( al, someFilenameExists ); // someFileNameExists:boolean;

HLA low-level calling sequence examples:

someFilename:string := "someFileName";

push( someFileName );

call filesys.isFile;

mov( al, someFilenameExists );

procedure filesys.isDir( FileName:string ); @returns( "eax" );

This function returns true if the file exists and is a directory (rather than a regular file). It returns false in EAX if the file does not exist, exists but is not a directory, is inaccessible, or there is some other error that occurs when attemting to open the file.

HLA high-level calling sequence examples:

filesys.isDir( "someDirName" );

mov( al, someDirNameExists ); // someDirNameExists:boolean;

HLA low-level calling sequence examples:

someDirName:string := "someDirName";

push( someDirName );

call filesys.isDir;

mov( al, someDirNameExists );

File Information Functions

These functions return some information about the file.

procedure filesys.size( Handle:dword ); @returns( "edx:eax" );
procedure filesys.size( filename:string ); @returns( "edx:eax" );

These (overloaded) functions return the current size of a file. They return the size in the EDX:EAX register pair. There are two versions of this function – one that accepts a string parameter and one that accepts a dword parameter. The first (dword) form expects you to pass it an open file handle; the second (string) form expects you to pass it a string containing the filename of the file whose size you want to compute.

Note: HLA uses macros to implement overloading. If you really must make a low-level call to one of these functions (or if you need to take the address of one of these functions), then you will need to refer to the actual procedure names: filesys._sizeh_ is the name of the function expecting a file handle, filesys._sizen_ is the name of the function expecting a filename string parameter.

HLA high-level calling sequence examples:

filesys.size( "someFileName" );

mov( eax, sizeOfSomeFileName );

filesys._sizen_( "someOtherFileName" );

mov( eax, sizeOfSomeOtherFile );

fileio.open( "anotherFile", fileio.r );

mov( eax, fileHandle );

filesys.size( fileHandle );

mov( eax, sizeOfAnotherFile );

fileio.open( "anotherFile2", fileio.r );

mov( eax, fileHandle2 );

filesys._sizeh_( fileHandle2 );

mov( eax, sizeOfAnotherFile2 );

HLA low-level calling sequence examples:

someFileName:string := "someFileName";

anotherFile :string := "anotherFile";

push( someFileName );

callfilesys._sizen_;

mov( eax, sizeOfSomeOtherFile );

push( anotherFile );

pushd( fileio.r );

call fileio.open;

mov( eax, fileHandle );

push( eax );

call filesys._sizeh_;

mov( eax, sizeOfAnotherFile2 );

Directory and File Manipulation Functions

procedure filesys.delete( filename:string ); @returns( "eax" );

This function deletes the specified file. Obviously, use this function with care. If this function fails, it raises the ex.CannotRemoveFile exception. Note that this function will only delete regular files. It will fail, and raise an exception if you attempt to delete a directory.

HLA high-level calling sequence examples:

filesys.delete( "someFileName" );

HLA low-level calling sequence examples:

someFileName:string := "someFileName";

push( someFileName);

call filesys.delete;

procedure filesys.mkdir( dirname:string ); @returns( "eax" );

This function creates a directory using the pathname you supply as a parameter. It returns the error status in EAX. If this function fails, it raises the ex.CannotCreateDir exception.

HLA high-level calling sequence examples:

filesys.mkdir( "newDirName" );

HLA low-level calling sequence examples:

newDirName:string := "newDirName";

push( newDirName);

call filesys.mkdir;

procedure filesys.cd( dirname:string );

This function sets the current working directory to the filename you pass as a parameter. If this function fails, it raises the ex.CDFailed exception.

HLA high-level calling sequence examples:

filesys.cd( "newWorkingDirectory" );

HLA low-level calling sequence examples:

newWorkingDirectory:string := "newWorkingDirectory";

push( newWorkingDirectory);

call filesys.cd;

procedure filesys.gwd( dest:string );

This function returns a string containing the current working directory’s pathname in the string you pass as a parameter. The string must have storage allocated for it and it must be large enough to hold the pathname or HLA will raise a string overflow exception.

HLA high-level calling sequence examples:

filesys.gwd( allocatedStringVar );

HLA low-level calling sequence examples:

push( allocatedStringVar);

call filesys.gwd;

procedure filesys.rename( fromPath:string; toPath:string );

This function renames one file to another. The fromPath parameter specifies the file to rename, the toPath parameter specifies the new name for the file. If the rename operation is unsuccessful, this function raises the ex.CannotRenameFile exception.

HLA high-level calling sequence examples:

filesys.rename( "oldName", "newName" );

HLA low-level calling sequence examples:

oldName:string := "oldName";

newName:string := "newName";

push( oldName );

push( newName );

call filesys.rename;

procedure filesys.rmdir( directory:string );

This function deletes the specified directory. The directory must be empty before you attempt to delete it or this function will raise an exception. If this function fails, it raises the ex.CannotRemoveDir exception. Note that this function will only delete directories. It will fail, and raise an exception if you attempt to delete a regular file.

HLA high-level calling sequence examples:

filesys.rmdir( "dirToRemove" );

HLA low-level calling sequence examples:

dirToRemove:string := "dirToRemove";

push( dirToRemove);

call filesys.rmdir;

iterator filesys.fileWithSuffix( directory:string; suffix:string );

This iterator, used within a foreach loop, will repeat once for each file in the directory specified by the directory parameter that ends with the string specified by suffix. On each iteration of the foreach loop, this function will provide a pointer to the full filename in the EAX register. Note that this function only iterates on regular files, it will not iterate (nor return the string name) of any directory entries. The filesys.fileWithSuffix function will allocate storage for the filename string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.fileWithSuffix( "dirToSearch", ".hla" ) do

// At this point, EAX points at a filename ending with ".hla"

mov( eax, filename ); // filename:string

// Do something with that string…

// When we’re done with the string, free it.

str.free( filename );

endfor;

iterator filesys.fileIn( directory:string);

This iterator, used within a foreach loop, will repeat once for each file in the directory specified by the directory parameter. On each iteration of the foreach loop, this function will provide a pointer to the full filename in the EAX register. Note that this function only iterates on regular files, it will not iterate (nor return the string name) of any directory entries. The filesys.fileIn function will allocate storage for the filename string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.fileIn( "dirToSearch" ) do

// At this point, EAX points at a filename of a file

// found in the "dirToSearch" directory.

mov( eax, filename ); // filename:string

// Do something with the string…

// When we’re done with the string, free it.

str.free( filename );

endfor;

iterator filesys.fileInCwd;

This iterator, used within a foreach loop, will repeat once for each file in the current directory. On each iteration of the foreach loop, this function will provide a pointer to the full filename in the EAX register. Note that this function only iterates on regular files, it will not iterate (nor return the string name) of any directory entries. The filesys.fileInCwd function will allocate storage for the filename string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.fileInCwd() do

// At this point, EAX points at a filename of a file

// found in the current working directory.

mov( eax, filename ); // filename:string

// Do something with the string…

// When we’re done with the string, free it.

str.free( filename );

endfor;

iterato

This iterator, used within a foreach loop, will repeat once for each directory entry, whose name ends with suffix, in the directory specified by the directory parameter. On each iteration of the foreach loop, this function will provide a pointer to the full directory name in the EAX register. Note that this function only iterates on directory files, it will not iterate (nor return the string name) of any regular file entries. The filesys.dirWithSuffix function will allocate storage for the directory name string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.dirWithSuffix( "dirToSearch", "suffix" ) do

// At this point, EAX points at name of a directory

// that ends with "suffix" that was found in the "dirToSearch"

// directory.

mov( eax, dirname ); // dirname :string

// Do something with the string…

// When we’re done with the string, free it.

str.free( dirname );

endfor;

iterator filesys.dirIn( directory:string);

This iterator, used within a foreach loop, will repeat once for each directory entry in the directory specified by the directory parameter. On each iteration of the foreach loop, this function will provide a pointer to the full directory name in the EAX register. Note that this function only iterates on directory files, it will not iterate (nor return the string name) of any regular file entries. The filesys.dirIn function will allocate storage for the directory string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.dirIn( "dirToSearch" ) do

// At this point, EAX points at name of a directory

// that was found in the "dirToSearch" directory.

mov( eax, dirname ); // dirname :string

// Do something with the string…

// When we’re done with the string, free it.

str.free( dirname );

endfor;

iterator filesys.dirInCwd;

This iterator, used within a foreach loop, will repeat once for each directory entry in the current directory. On each iteration of the foreach loop, this function will provide a pointer to the full directory name in the EAX register. Note that this function only iterates on directory files, it will not iterate (nor return the string name) of any regular file entries. The filesys.dirInCwd function will allocate storage for the directory string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.dirInCwd() do

// At this point, EAX points at name of a directory

// that was found in the current working directory.

mov( eax, dirname ); // dirname :string

// Do something with the string…

// When we’re done with the string, free it.

str.free( dirname );

endfor;

iterator filesys.itemWithSuffix( directory:string; suffix:string );

This iterator, used within a foreach loop, will repeat once for each entry, whose name ends with suffix, in the directory specified by the directory parameter. On each iteration of the foreach loop, this function will provide a pointer to the name in the EAX register. Note that this function iterates on both directory and regular file entries. The filesys.itemWithSuffix function will allocate storage for the result string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.itemWithSuffix( "dirToSearch", "suffix" ) do

// At this point, EAX points at a filename or a directory

// name ending with "suffix"

mov( eax, entryname ); // entryname :string

// Do something with that string…

// When we’re done with the string, free it.

str.free( entryname );

endfor;

iterator filesys.itemInCwd;

This iterator, used within a foreach loop, will repeat once for each entry in the current directory. On each iteration of the foreach loop, this function will provide a pointer to the name in the EAX register. Note that this function iterates on both directory and regular file entries. The filesys.itemInCwd function will allocate storage for the result string on the heap and return the pointer to this string in EAX. It is the foreach loop body’s responsibility to free up that storage when it is done with the string.

HLA high-level calling sequence examples:

foreach filesys.itemInCwd( ) do

// At this point, EAX points at a filename or a directory

// name from the current working directory.

mov( eax, entryname ); // entryname :string

// Do something with that string…

// When we’re done with the string, free it.

str.free( entryname );

endfor;

HLA Related Macros and Constants (hla.hhf)

The HLA module contains numeric constants produced by some of the HLA symbol-table compile-time functions. It also contains various macros to extend the HLA compile-time language and provide support for other HLA stdlib modules.

The HLA Module

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

#include( "hla.hhf" )

#include( "stdlib.hhf" )

Classification Macros

The hla.hhf module contains some macros that test the type of an identifier at compile time. Here is a typical invocation of these macros:

#if( hla.IsUns( uVar ))

// do something if Uns object

#else

// Do something if not unsigned object

#endif

#macro hla.IsUns( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is an uns8, uns16, uns32, uns64, or uns128 object.

#macro hla.IsInt( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is an int8, int16, int32, int64, or int128 object.

#macro hla.IsHex( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is a byte, word, dword, qword, tbyte, or lword object.

#macro hla.IsNumber( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is an uns8, uns16, uns32, uns64, un128, int8, int16, int32, int64, int128, byte, word, dword, qword, tbyte, or lword object.

#macro hla.IsReal( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is a real32, real64, or real80 object.

#macro hla.IsNumeric( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is an uns8, uns16, uns32, uns64, uns128, int8, int16, int32, int64, int128, byte, word, dword, qword, tbyte, lword, real32, real64, or real80 object.

#macro hla.IsOrdinal( identifier );

This macro returns a compile-time expression that evaluates true if the specified identifier is an uns8, uns16, uns32, uns64, uns128, int8, int16, int32, int64, int128, boolean, char, byte, word, dword, qword, tbyte, lword, or enumerated data type object.

String to Integer Macros

The HLA module provides two macros, hla.asWord and hla.asDword, that let you treat a one to four-character string as a 16-bit or 32-bit number. Specifically, these macros cram the 1-4 bytes of the strings into a two-byte word constant or a 4-byte dword constant.

#macro hla.asWord( "1 or 2 character string" );

This macro places the first character of the string in the L.O. byte of the 16-bit result, and the second character of the string in the H.O. byte of the result. If there is only one character in the string, the H.O. byte of the result will be zero.

#macro hla.asDword( "1 to 4 character string" );

This macro places copies the first through fourth characters of the string to the L.O. to H.O. bytes of the dword results. If there are fewer than 4 characters, the H.O. byte(s) of the result are filled with zeros.

Label Generation Macro

The hla.genlabel macro generates a sequence of strings that are unique, legal, HLA identifiers (within the current compilation, do not use these as public symbols). Typically, you would take the string that this macro returns and convert that string to an actual symbol using the @TEXT function.

Here’s the definition of hla. getLabel in the HLA header file:

val

_hla_labelCnt_ := 0;

#macro genLabel;

"_genLabel_" + string( hla._hla_labelCnt_ ) + "_"

?hla._hla_labelCnt_ := hla._hla_labelCnt_ + 1;

#endmacro;

Procedure Overloading Macro

The hla.overload macro allows you to provide the equivalent of "overloaded functions" in your HLA programs. Note that this macro is somewhat obsolete as the HLA language now provides built-in overloading (see the HLA Reference Manual for details). This macro is provided for compatibility with old code that is still using it.

Overloaded functions are called by "signature" rather than by name. A signature is the combination of the name of a function, the number of parameters, and the types of each of the parameters. As long as two separate functions have unique signatures, they can be called using the same name. Of course, HLA requires each procedure/iterator/method/macro to have a unique name within the current scope, but the overload macro lets you define the name to use when calling these different functions.

As an example, consider the following three function prototypes:

procedure min8( val1:uns8; val2:uns8 ); @external;

procedure min16( val1:uns16; val2:uns16 ); @external;

procedure min32( val1:uns32; val2:uns32 ); @external;

We would like to call these three functions using the single name "min" and letting the different signatures (the differing parameter types in this case) select the actual function to call. The hla.overload macro will write a "min" macro for us that will determine the parameter types and call one of the functions above based on the signature of the call. An overloaded definition looks like the following:

#macro min( _parms_[] ); // Define "min", our overloaded procedure

hla.overload( _parms_ );

hla.signature( min8( uns8, uns8 ));

hla.signature( min16( uns16, uns16 ));

hla.signature( min32( uns32, uns32 ));

hla.endoverload

#endmacro

The first thing to note is that you must create a macro that will be used as the "overloaded procedure". In this example, that macro is the "min" macro. This macro must always have a single array (variable) parameter. The name isn’t important, though "_parms_" is the conventional name to use here.

The body of the overloaded macro is actually going to be written by the hla.overload macro. The hla.overload macro is an HLA context-free macro that begins with "hla.overload", ends with "hla.endoverload", and contains a single "hla.signature" keyword macro invocation for each signature we want our overloaded procedure to support. In this example, we want our min function to call one of three different functions based on the types of the parameters passed to min, so there will be three signature invocations.

A signature keyword macro invocation takes the following form:

hla.signature( actualProcedureName( list_of_parameter_types ));

where actualProcedureName is the name of the function we want to call if the signature matches and list_of_parameter_types is a comma-separated list of HLA data type names, that correspond to the data types for the signature.

The hla.overload macro will write the body of the min macro so that it will parse the parameters passed in (via _parms_) and determine which of the three functions to call. For example:

min( u8, u8a ); // calls min8( u8, u8a );

min( u16, u16a ); // calls min16( u16, u16a );

min( u32, u32a ); // calls min32( u32, u32a );

Here are some additional examples of overloaded macro definitions from the HLA stdlib:

#macro catsub( parms[] );

hla.overload( parms )

hla.signature( str.catsub4(string, dword, dword, string) )

hla.signature( str.catsub5(string, dword, dword, string, string))

hla.endoverload

#endmacro

procedure catsub4( src:string; start:dword; len:dword; dest:string );

external( "STR_CATSUB4" );

procedure catsub5

(

src2 :string;

start :dword;

len :dword;

src1 :string;

dest :string

);

@returns( "(type string eax)" );

external( "STR_CATSUB5" );

#macro first( parms[] );

hla.overload( parms )

hla.signature( str.first2(string, dword) )

hla.signature( str.first3(string, dword, string) )

hla.endoverload

#endmacro

procedure first2

(

s :string;

len :dword

); external( "STR_FIRST2" );

procedure first3

(

s :string;

len :dword;

dest :string

); external( "STR_FIRST3" );

When you use an overloaded function (that is, you invoke the macro whose body was filled in by the hla.overload macro), the code attempts to match the actual parameters against the signatures you’ve provided. If no possible signature can match the actual parameter list, then the system will report an error. If two or more signatures can be matched by the actual parameter list, the system will also report an error. Unfortunately, if the actual parameter list provides an ambiguous footprint, then the system will report an error. Consider the following overloaded function and a couple invocations of that function:

static

u8 :uns8;

u16 :uns16;

s :string;

#macro abc( _parms_[] );

hla.overload( _parms_ )

hla.signature( abc1( uns8, string ))

hla.signature( abc2( uns16, string ))

hla.endoverload;

#endmacro

abc( u8, s ); // Okay, calls abc1

abc( u8, "abc1" ); // Okay, calls abc1

abc( u16, s ); // Okay, calls abc2

abc( 0, s ); // Illegal – matches multiple signatures

The last example doesn’t work because the literal constant zero matches both the uns8 and uns16 types, so this is an ambiguous signature match. Keep this limitation in mind when creating your signatures.

Generic PUT Macro

The hla.put macro provides a mechanism for creating generic "put" functions like the stdout.put, stderr.put, fileio.put, and str.put macros found in the HLA standard library. Indeed, these macros were built using the hla.put macro. By using the hla.put macro, you can easily create your own "put" macro that calls a variety of different functions based on the types of the parameters passed to your "put" macro.

First of all, it’s important to realize that a user-defined "put" macro must appear inside a namespace. The hla.put macro expects to find several objects defined in a namespace whose name you provide. The namespace will contain all the procedures that the user-defined macro will ultimately call as well as a few additional compile-time data structures that the hla.put macro will reference.

Within the namespace you’re defining a "put" macro for, there must be six constant array objects with hla.sizePTypes elements each. These arrays must have the following names and types:

validPutType :boolean [ @global:hla.sizePTypes ];

validPutSizeType :boolean [ @global:hla.sizePTypes ];

validPutSize2Type :boolean [ @global:hla.sizePTypes ];

putFunc :string [ @global:hla.sizePTypes ];

putSizeFunc :string [ @global:hla.sizePTypes ];

putSize2Func :string [ @global:hla.sizePTypes ];

Assuming you’ve created a namespace called "myns", then myns.validPutType will tell the hla.put macro which built-in data types it can process when you specify an unadorned argument to myns.put. For example, if i8 is an int8 object, then myns.put( i8 ); will call some function if the myns.validPutType entry indexed by hla.ptInt8 contains true. Here is the validPutType table for the stdout namespace; most validPutType tables will be a copy of this one (assuming you want your new "put" macro to handle all the same data types as stdout.put):

const

validPutType :boolean[ @global:hla.sizePTypes ] :=

[

@global:false, // Undefined

@global:true, // tBoolean //1

@global:false, // enum //2

@global:true, // tUns8, //3

@global:true, // tUns16, //4

@global:true, // tUns32, //5

@global:true, // tUns64, //6

@global:true, // tUns128, //7

@global:true, // tByte, //8

@global:true, // tWord, //9

@global:true, // tDWord, //10

@global:true, // tQWord, //11

@global:true, // tTByte, //12

@global:true, // tLWord, //13

@global:true, // tInt8, //14

@global:true, // tInt16, //15

@global:true, // tInt32, //16

@global:true, // tInt64, //17

@global:true, // tInt128, //18

@global:true, // tChar, //19

@global:false, // tWChar, //20

@global:true, // tReal32, //21

@global:true, // tReal64, //22

@global:true, // tReal80, //23

@global:false, // tReal128, //24

@global:true, // tString, //25

@global:false, // tZString, //26

@global:false, // tWString, //27

@global:true, // tCset, //28

@global:false, // tArray, //29

@global:false, // tRecord, //30

@global:false, // tUnion, //31

@global:false, // tRegex //32

@global:true, // tClass, //33

@global:false, // tProcptr, //34

@global:false, // tThunk, //35

@global:true, // tPointer //36

@global:false, // tLabel //37

@global:false, // tProc //38

@global:false, // tMethod //39

@global:false, // tClassProc //40

@global:false, // tClassIter //41

@global:false, // tIterator //42

@global:false, // tProgram //43

@global:false, // tMacro //44

@global:false, // tText //45

@global:false, // tRegExMac //46

@global:false, // tNamespace //47

@global:false, // tSegment //48

@global:false, // tAnonRec //49

@global:false, // tAnonUnion //50

@global:false, // tVariant //51

@global:false // tError //52

];

Notice that each element of the array is indexed by the pType value for the data type.

The validPutSizeType array is very similar to the validPutType array (indeed, it is structurally identical to the validPutType array). The difference between the two is that the hla.put macro uses the validPutSizeType array to determine if it can call a "*Size" function when the "put" macro encounters an operand of the form "xx:ss", where "ss" is a print width specfication. For example, if you write "myns.put( i8:4 );" and i8 is an int8 variable, then the hla.put macro will check the hla.ptInt8 element of the validPutSizeType array to determine whether it supports a field width for int8 output. Here is the stdout version of this array (again, most uses of the hla.put macro will copy this, assuming they provide all the same output functionality as stdout.put):

validPutSizeType :boolean[ @global:hla.sizePTypes ] :=

[

@global:false, // Undefined

@global:true, // tBoolean //1

@global:false, // enum //2

@global:true, // tUns8, //3

@global:true, // tUns16, //4

@global:true, // tUns32, //5

@global:true, // tUns64, //6

@global:true, // tUns128, //7

@global:true, // tByte, //8

@global:true, // tWord, //9

@global:true, // tDWord, //10

@global:true, // tQWord, //11

@global:true, // tTByte, //12

@global:true, // tLWord, //13

@global:true, // tInt8, //14

@global:true, // tInt16, //15

@global:true, // tInt32, //16

@global:true, // tInt64, //17

@global:true, // tInt128, //18

@global:true, // tChar, //19

@global:false, // tWChar, //20

@global:true, // tReal32, //21

@global:true, // tReal64, //22

@global:true, // tReal80, //23

@global:false, // tReal128, //24

@global:true, // tString, //25

@global:false, // tZString, //26

@global:false, // tWString, //27

@global:false, // tCset, //28

@global:false, // tArray, //29

@global:false, // tRecord, //30

@global:false, // tUnion, //31

@global:false, // tRegEx //32

@global:false, // tClass, //33

@global:false, // tProcptr, //34

@global:false, // tThunk, //35

@global:true, // tPointer //36

@global:false, // tLabel //37

@global:false, // tProc //38

@global:false, // tMethod //39

@global:false, // tClassProc //40

@global:false, // tClassIter //41

@global:false, // tIterator //42

@global:false, // tProgram //43

@global:false, // tMacro //44

@global:false, // tText //45

@global:false, // tRegExMac //46

@global:false, // tNamespace //47

@global:false, // tSegment //48

@global:false, // tAnonRec //49

@global:false, // tAnonUnion //50

@global:false, // tVariant //51

@global:false // tError //52

];

The validPutSize2Type array is very similar to the validPutSizeType array. The difference between the two is that the hla.put macro uses the validPutSize2Type array to determine if it can call a "*Size" function when the "put" macro encounters an operand of the form "xx:ww:dd", where "ww" is a print width specfication and "dd" is a "number of decimal positions" value. This functionality is typically used for outputting real values in decimal form. For example, if you write "myns.put( r80:14:2 );" and r80 is an real80 variable, then the hla.put macro will check the hla.ptReal80 element of the validPutSize2Type array to determine whether it supports a field width and decimal count for real80 output. Here is the stdout version of this array (again, most uses of the hla.put macro will copy this, assuming they provide all the same output functionality as stdout.put):

validPutSize2Type :boolean[ @global:hla.sizePTypes ] :=

[

@global:false, // Undefined

@global:false, // tBoolean //1

@global:false, // enum //2

@global:false, // tUns8, //3

@global:false, // tUns16, //4

@global:false, // tUns32, //5

@global:false, // tUns64, //6

@global:false, // tUns128, //7

@global:false, // tByte, //8

@global:false, // tWord, //9

@global:false, // tDWord, //10

@global:false, // tQWord, //11

@global:false, // tTByte, //12

@global:false, // tLWord, //13

@global:false, // tInt8, //14

@global:false, // tInt16, //15

@global:false, // tInt32, //16

@global:false, // tInt64, //17

@global:false, // tInt128, //18

@global:false, // tChar, //19

@global:false, // tWChar, //20

@global:true, // tReal32, //21

@global:true, // tReal64, //22

@global:true, // tReal80, //23

@global:false, // tReal128, //24

@global:false, // tString, //25

@global:false, // tZString, //26

@global:false, // tWString, //27

@global:false, // tCset, //28

@global:false, // tArray, //29

@global:false, // tRecord, //30

@global:false, // tUnion, //31

@global:false, // tRegEx //32

@global:false, // tClass, //33

@global:false, // tProcptr, //34

@global:false, // tThunk, //35

@global:false, // tPointer //36

@global:false, // tLabel //37

@global:false, // tProc //38

@global:false, // tMethod //39

@global:false, // tClassProc //40

@global:false, // tClassIter //41

@global:false, // tIterator //42

@global:false, // tProgram //43

@global:false, // tMacro //44

@global:false, // tText //45

@global:false, // tRegExMac //46

@global:false, // tNamespace //47

@global:false, // tSegment //48

@global:false, // tAnonRec //49

@global:false, // tAnonUnion //50

@global:false, // tVariant //51

@global:false // tError //52

];

The putFunc, putSizeFunc, and putSize2Func arrays in your namespace must contain the names of the functions to call if the corresponding entries in validPutType, validPutSizeType, and validPutSize2Type contain true (respectively). These strings must be the name of the procedure to call without the namespace prefix. That is, if you want to tell hla.put to call "myns.puti8" to print an 8-bit integer, then the entry at index hla.ptInt8 in myns.putFunc should contain the string "puti8". Note that if the corresponding entry in the in validPutType, validPutSizeType, or validPutSize2Type tables contain false, then it doesn’t matter what string appears in the array as hla.put will never use it; by convention, the empty string is always put in unused entries. Here is the stdout.putFunc table:

putFunc :string[ @global:hla.sizePTypes ] :=

[

"", // Undefined

"putbool", // tBoolean //1

"", // enum //2

"putu8", // tUns8, //3

"putu16", // tUns16, //4

"putu32", // tUns32, //5

"putu64", // tUns64, //6

"putu128", // tUns128, //7

"putb", // tByte, //8

"putw", // tWord, //9

"putd", // tDWord, //10

"putq", // tQWord, //11

"puttb", // tLWord, //12

"putl", // tLWord, //13

"puti8", // tInt8, //14

"puti16", // tInt16, //15

"puti32", // tInt32, //16

"puti64", // tInt64, //17

"puti128", // tInt128, //18

"putc", // tChar, //19

"", // tWChar, //20

"_pute32", // tReal32, //21

"_pute64", // tReal64, //22

"_pute80", // tReal80, //23

"", // tReal128, //24

"puts", // tString, //25

"putz", // tZString, //26

"", // tWString, //27

"putcset", // tCset, //28

"", // tArray, //29

"", // tRecord, //30

"", // tUnion, //31

"", // tRegEx //32

"", // tClass, //33

"", // tProcptr, //34

"", // tThunk, //35

"putd", // tPointer //36

"", // tLabel //37

"", // tProc //38

"", // tMethod //39

"", // tClassProc //40

"", // tClassIter //41

"", // tIterator //42

"", // tProgram //43

"", // tMacro //44

"", // tText //45

"", // tRegExMac //46

"", // tNamespace //47

"", // tSegment //48

"", // tAnonRec //49

"", // tAnonUnion //50

"", // tVariant //51

"" // tError //52

];

ut.putFunc table:

Please see the stdout.hhf header file for examples of the other two tables.

Once you have set up the six constant arrays in your namespace, defining your own put macro using hla.put is almost trivial. The hla.put macro processes a single "put" operand. The syntax for this macro is the following:

hla.put( <namespaceID>, <first param as string>, <single argument> );

where <namespace> is your namespace identifier, <first param as string> is the first parameter to be passed to all your functions (this can be the empty string if you don’t have a first parameter [e.g., stdout or stderr], or it can be whatever your output functions require; for example, the fileio.put macro specifies a file handle here, the str.put macro specifies a string variable name here).

Because hla.put only handles a single output object, you must provide a simple put macro within your namespace that calls hla.put for each of the actual arguments passed to your put macro. Here’s the stdout version of that macro:

val

stdoutParm:string;

#macro put( _parameters_[] );

#for( @global:stdout.stdoutParm in _parameters_ )

@global:hla.put( stdout, "", @eval(@global:stdout.stdoutParm) )

#endfor

#endmacro

Here’s the fileio version of this macro:

val

_v_ :string;

_curparm_ :string;

#macro put( _ileVar_, _parameters_[] );

?@global:fileio._v_ := @string:_ileVar_;

#for( @global:fileio._curparm_ in _parameters_ )

@global:hla.put

(

fileio,

@global:fileio._v_,

@eval(@global:fileio._curparm_)

)

#endfor

#endmacro

@class Constants

The hla.hhf module contains some macros that test the type of an identifier at compile time. Here is a typical invocation of these macros:

The HLA compile-time @class function returns the following values to denote the classification of an identifier. If a symbol appears more than once in a program, the @class function returns the classification value for the symbol currently in scope.

@Class Return Values
Name	Value	Description
hla.cIllegal	0	Symbol doesn’t have a legal HLA classification.
hla.cConstant	1	Symbol was defined in the CONST section.
hla.cValue	2	Symbol was defined in the VAL section.
hla.cType	3	Symbol was defined in the TYPE section.
hla.cVar	4	Symbol was defined in the VAR section
hla.cParm	5	Symbol is a parameter.
hla.cStatic	6	Symbol was defined in a STATIC, READONLY, or STORAGE section.
hla.cLabel	7	Symbol is a statement label.
hla.cProc	8	Identifier is the name of a (non-class) procedure.
hla.cIterator	9	Identifier is the name of a (non-class) iterator.
hla.cClassProc	10	Identifier is the name of a class procedure.
hla.cClassIter	11	Identifier is the name of a class iterator.
hla.cMethod	12	Identifier is the name of a class method.
hla.cMacro	13	Symbol is a macro.
hla.cKeyword	14	Symbol is an HLA reserved word.
hla.cTerminator	15	Symbol is an HLA TERMINATOR macro.
hla.cRegex	16	Symbol is a regular expression macro
hla.cProgram	17	PROGRAM or UNIT identifier.
hla.cNamespace	18	Identifier is a name space ID.
hla.cSegment	19	Identifier is a segment name.
hla.cRegister	20	Identifier is an 80x86 register name.
hla.cNone	21	Reserved.

HLA pType Constants

The HLA @ptype compile-time function returns the values in the following table for the symbol you pass as a parameter to the function. You should always use these symbol names rather than hard-coding the constants in your programs. These values have changed in the past and they will likely change in the future with improvements to the HLA language.

: @pType Return Values
Symbol	Value	Description
hla.ptIllegal	0	Symbol is undefined or is not an object to which a type can be applied.
hla.ptBoolean	1	Symbol is of type boolean.
hla.ptEnum	2	Symbol is an enumerated type.
hla.ptUns8	3	Symbol is an UNS8 object.
hla.ptUns16	4	Symbol is an UNS16 object.
hla.ptUns32	5	Symbol is an UNS32 object.
hla.ptUns64	6	Symbol is an UNS64 object.
Hla.ptUns128	7	Symbol is an UNS128 object.
hla.ptByte	8	Symbol is a BYTE object.
hla.ptWord	9	Symbol is a WORD object.
hla.ptDWord	10	Symbol is a DWORD object.
hla.ptQWord	11	Symbol is a QWORD object.
hla.ptTByte	12	Symbol is a TBYTE object.
hla.ptLWord	13	Symbol is a LWORD object.
hla.ptInt8	14	Symbol is an INT8 object.
hla.ptInt16	15	Symbol is an INT16 object.
hla.ptInt32	16	Symbol is an INT32 object.
hla.ptInt64	17	Symbol is an INT64 object.
hla.ptInt128	18	Symbol is an INT128 object.
hla.ptChar	19	Symbol is of type CHAR.
hla.ptWChar	20	Symbol is of type WCHAR.
hla.ptReal32	21	Symbol is a REAL32 object.
hla.ptReal64	22	Symbol is a REAL64 object.
hla.ptReal80	23	Symbol is a REAL80 object.
hla.ptReal128	24	Symbol is a REAL128 object.
hla.ptString	25	Symbol has the STRING type.
hla.ptZString	26	Symbol has the ZSTRING type.
hla.ptWString	27	Symbol has the WSTRING type.
hla.ptCset	28	Symbol’s type is CSET.
hla.ptArray	29	The symbol is an array object.
hla.ptRecord	30	The symbol is a record object.
hla.ptUnion	31	The symbol is a union object.
hla.ptRegex	32	The symbol is a regular expression object.
hla.ptClass	33	The symbol is a class object.
hla.ptProcptr	34	The symbol’s type is "pointer to a procedure".
hla.ptThunk	35	The symbol is a THUNK type.
hla.ptPointer	36	The symbol is a POINTER object.
hla.ptLabel	37	The symbol is a statement label object.
hla.ptProc	38	The symbol denotes a procedure.
hla.ptMethod	39	The symbol denotes a method.
hla.ptClassProc	40	The symbol is a procedure within a class.
hla.ptClassIter	41	The symbol denotes an iterator within a class.
hla.ptIterator	42	The symbol is an iterator name.
hla.ptProgram	43	The symbol is the program’s or unit’s identifier.
hla.ptMacro	44	The identifier is a macro.
hla.ptText	45	The identifier is a text object (note: @ptype does not return this value since HLA expands the text prior to processing by @ptype).
Hla.ptRegExMac	46	The symbol is a regular expression macro.
hla.ptNamespace	47	The identifier is a namespace ID.
hla.ptSegment	48	The identifier is a segment ID.
hla.ptAnonRec	49	The identifier is an anonymous record within a union (internal use only, @ptype will never return this value).
hla.ptAnonUnion	50	The identifier is an anonymous union within a record (internal use only, @ptype will never return this value).
hla.ptVariant	51	This value is reserved for internal use by HLA.
hla.ptError	52	This value indicates a cascading error in an expression. Generally, you will not get this value from @ptype unless there was some sort of error in the parameter to pass to @ptype.

Note that the HLA module provides a constant array, hla.ptypeStrs, that returns the associated HLA type name when indexed by one of the above constants. Note that this is a compile-time constant array, not a run-time array of strings. If you want a run-time string array, you can define one thusly:

static

ptypeStrs :string [@elements( hla.ptypeStrs )] := hla.ptypeStrs;

Do note that not every ptype value maps to a valid HLA data type. For example, hla.ptRecord maps to the string "(record)". You cannot use this as a type in an HLA program.

@pclass Return Values

The HLA @pClass function expects a procedure’s parameter name as its sole parameter. It returns one of the following constants that denotes the parameter passing mechanism for the parameter. Note that @pClass’ return values are defined only for parameter identifiers. These values have changed in the past and they will likely change in the future with improvements to the HLA language, so always use these symbolic names rather than hard-coded values.

@pClass Return Values
Symbol	Value	Description
hla.illegal_pc	0	May be returned if the symbol is not a parameter.
hla.valp_pc	1	Returned if parameter is passed by value.
hla.refp_pc	2	@pClass returns this value if you pass the parameter by reference.
hla.vrp_pc	3	Denotes that you’ve passed the parameter by value/result.
hla.result_pc	4	This value means that you’ve passed the parameter by result.
hla.name_pc	5	This value indicates that you’ve passed the parameter by name.
hla.lazy_pc	6	This value indicates that you’ve passed the parameter by lazy evaluation.

@section Return Values

The following constants correspond to bits in the value returned by @section. They denote the current position of the compiler in the code. These values have changed in the past and they will likely change in the future with improvements to the HLA language, so always use these symbolic names rather than hard-coded values.

@section Constants
Symbol	Value	Description
hla.inConst	1	Bit zero is set if HLA is current processing definitions in a CONST section.
hla.inVal	2	Bit one is set if HLA is current processing definitions in a VAL section.
hla.inType	4	Bit two is set if HLA is current processing definitions in a TYPE section.
hla.inVar	8	Bit three is set if HLA is current processing definitions in a VAR section.
hla.inStatic	$10	Bit four is set if HLA is current processing definitions in a STATIC section.
hla.inReadonly	$20	Bit five is set if HLA is current processing definitions in a READONLY section.
hla.inStorage	$40	Bit six is set if HLA is current processing definitions in a STORAGE section.
hla.inMain	$1000	Bit 12 is set if HLA is current processing statements in the main program.
hla.inProcedure	$2000	Bit 13 is set if HLA is current processing statements in a procedure.
hla.inMethod	$4000	Bit 14 is set if HLA is current processing statements in a method.
hla.inIterator	$8000	Bit 15 is set if HLA is current processing statements in an iterator.
hla.inMacro	$1_0000	Bit 16 is set if HLA is current processing statements in a macro.
hla.inKeyword	$2_0000	Bit 17 is set if HLA is current processing statements in a keyword macro.
hla.inTerminator	$4_0000	Bit 18 is set if HLA is current processing statements in a terminator macro.
hla.inThunk	$8_0000	Bit 19 is set if HLA is current processing statements in a thunk’s body.
hla.inUnit	$80_0000	Bit 23 is set if HLA is current processing statements in a unit.
hla.inProgram	$100_0000	Bit 24 is set if HLA is current processing statements in a program (not a unit).
hla.inRecord	$200_0000	Bit 25 is set if HLA is current processing declarations in a record definition.
hla.inUnion	$400_0000	Bit 26 is set if HLA is current processing declarations in a union.
hla.inClass	$800_0000	Bit 27 is set if HLA is current processing declarations in a class.
hla.inNamespace	$1000_0000	Bit 28 is set if HLA is current processing declarations in a union.

HOWL: The HLA Object Windows Library

The HLA Object Windows Library (HOWL) is an application framework for Microsoft Windows that greatly simplifies GUI application development for Windows in assembly language. It lets you declare forms and widgets that describe the visual layout of a GUI application and then you need only write small procedures that handle events associated with your GUI elements. This is far less work than writing a standard Win32 application and processing all the messages that Windows sends to such an application.

Once you master the basics of HOWL, you can write the GUI portion of a Win32 application in a fraction of the time it would take using standard Win32 API programming techniques. Your programs will be easier to read and easier to maintain, as well.

As its name suggests, the HLA Object Windows Library makes extensive use of HLA’s object-oriented programming facilities. If you are unfamiliar with object-oriented programming, or are uncomfortable with HLA’s implementation of object-oriented programming, you should take a look at the chapter on “Classes and Objects” in The Art of Assembly Language and the chapter on Object-Oriented Programming in the HLA reference manual.

Note: Successful use of HOWL requires HLA v2.8 or later. If you have an earlier version, you will need to upgrade to the latest version in order to use HOWL. It should be obvious by now, but HOWL for Windows only supports Microsoft Windows (2000, XP, Vista, and Windows 7; no guarantees on earlier versions).

The HOWL Application Framework

Most HLA programs (at least to date) are written with a “main program” that controls the activities of that application by calling various procedures and other code within the application; the main program is the “traffic cop” that determines what happens and the sequence of those operations. An application framework (like HOWL), on the other hand, contains its own “main program” that controls the sequence of operations within the program. As an application programmer, you will supply various procedures that the framework will call and your procedures will handle various tasks as requested by the application framework’s main program. This paradigm takes a small amount of effort to get used to if you’ve never written event-driven applications before, but it’s fairly easy to master and you should be able to master it in a few short hours.

For technical reasons, your HOWL applications will still be written as an HLA program . However, the main program for your HOWL application is trivial; if your program is named “howlDemo”, then this is what your main program will look like:

begin howlDemo;

HowlMainApp();

end howlDemo;

HowlMainApp is the HOWL application framework main program that you must call from your main program to get the application running.1

Beyond the main program in your HOWL application, there are two methods and three procedures you must also supply:

An “onClose” method (usually containing a single statement)
An “onCreate” method (usually empty)
An “AppStart” procedure
An “AppTerminate” procedure
An “AppException” procedure

Your application will normally contain many more procedures and other code, of course, but every HOWL application will have at least these five procedures and methods.

The first step in creating a HOWL application is to create a subclass of the wForm_t type. You could create such a new class using a declaration like the following:

myNewForm_t:

class inherits( wForm_t );

<< any new fields you want to add >>

endclass;

However, in an typical HOWL application you won’t create a new wForm_t type this way. Instead, you’ll use the wForm..endwForm declaration to achieve this:

wForm( myForm )

<< any new fields you want to add >>

<< any widget declarations you want >>

endwForm

The wForm..endwForm statement does several things for you:

It defines a new class type that is a subclass of wForm_t . This new class type is given the name “myForm_t” (substituting whatever name you supply as the argument to wForm for “myForm” in this example).
It creates a static global variable named “pformname” (substituting the name you supply in the wForm invocation for formname) that is a pointer to an object of type formname_t (again, substituting the name you supply in the invocation to wForm for formname).
It creates a static global variable named “formname” (usual substitution) that is an instance of the class object formname_t .
It initializes “pformname” with the address of the global “formname” variable.
It creates a macro, named formname_implementation , that you can invoke to create a constructor for this new class that initializes all the widgets you declare in the wForm..endwForm statement.

You could manually do all of these things that the wForm..endwForm declaration does for you, but it’s a lot easier and less error prone to to use the wForm..endwForm statement. So this documentation will only consider that approach. If you’re interested in learning how to manually create new wForm_t subclass types, take a look at the macro implementation of wForm..endwForm in the howl.hhf header file.

In order to provide concrete examples, this documentation will assume that you’re supplying the name “myForm” as an argument to the wForm..endwForm macro invocation. Please keep in mind that you can use any name you choose (and “myForm” is not a particularly descriptive or good name) in these examples. In general, you might want to consider using your application’s name (if you’re not already using that as an identifier elsewhere in your program) as the main form name.

With the basic description wForm out of the way, we can now take a look at a complete HOWL application (the generic equivalent of a “hello world” application in the GUI world). The following code appears in pieces in order to explain the purpoes of each piece.

program howlDemo;

#linker( "comdlg32.lib" )

#linker( "comctl32.lib" )

The HOWL library makes use of the Windows common controls and common dialogs dynamically linked libraries. The two #linker statements above instruct HLA to emit instructions to the linker to link in these libraries (so you don’t have to specify these library names on the HLA compiler command line).

?@NoDisplay := true;

?@NoStackAlign := true;

By default, HLA emits code to generate displays for all procedures and it also emits code to align the stack at the beginning of each procedure. These options are rarely needed in HOWL programming, so it’s a good idea to include the two statements above in order to turn off the code generation for these two features.

#includeOnce( "stdlib.hhf" )

#includeOnce( "howl.hhf" )

Like most HLA applications, we’ll include the HLA standard library generic header file (stdlib.hhf) so we can take advantage of most of the standard library’s features. Because stdlib.hhf doesn’t automatically include the howl.hhf header file, the code needs to explicitly include this header file as well in order to use HOWL features.

static

align( 4 );

bkgBrush_g :dword;

bkgColor_g :dword;

The bkgBrush_g and bkgColor_g variables will hold the background color and brush for our forms. We need to declare these variables before our form declaration because many widgets (controls) will need a background color and the widgets will look better if their background color is the same as the form’s.

wForm( myForm )

endwForm

Here’s our wForm declaration. It is important for you to understand that the wForm..endwForm declaration is equivalent to a class declaration in the type section of an HLA program. The wForm macro, in fact, expands in-place) to a type section with a class declaration for myForm_t . There are two things you can place between the wForm and endwForm clauses: class field declarations and invocations of certain context-free macros defined by the wForm macro invocation. We’ll take a look at both of these options a little later, for the current example our wForm..endwForm macro invocation is empty because we’re just creating an empty formfor our application. Note, and this is very important, that the wForm..endwForm statement must appear at some point in your program where it is legal to begin a type section that defines a class (because this is exactly what wForm..endwForm is going to do).

// Implement the mainAppWindow create procedure and object instances:

myForm_implementation();

One of the tasks that the wForm..endwForm macro invocation accomplishes is the creation of a macro (named myForm_implementation in this example) that will expand to some code that the wForm..endwForm macro generates. Somewhere in your program you must invoke this macro ( myForm_implementation ) in order to actually emit the code that the new class you’ve created requires. If you’re wondering why the wForm..endwForm macro doesn’t emit this code directly, just keep in mind that the wForm..endwForm declaration often appears in a header file (rather than directly in your main program as it appears here) and if wForm..endwForm automatically emitted this code, it would be emitted in every file that included the header file. This would result in duplicate code (and duplicate external labels). Therefore, the wForm..endwForm statement generates this macro that you must invoke exactly once in your program in order to compile the code that wForm..endwForm generates.

method myForm_t.onCreate;

begin onCreate;

end onCreate;

method myForm_t.onClose;

begin onClose;

w.PostQuitMessage( 0 );

end onClose;

The myForm_t class that wForm..endwForm creates will define two methods but it will not generate the code for these methods, you will have to provide the code for these methods. Most of the time, these methods will appear exactly as the two above. The HOWL main program invokes the onCreate method at the very end of the execution of the constructor procedure for the myForm_t class. You could put code in this method to execute immediately after the creation of the new form but, as you’ll soon see, you’ll most often put this “on creation” code in the appStart procedure. So most of the time the onCreate method will be empty. Why does HOWL generate a call to a method you’ll almost always leave empty? Well, this is an artifact of object-oriented programming. The onCreate method is quite useful for other classes that are derived from myForm_t’s parent class, so rather than make a special case out of myForm_t (or the other classes), HOWL requires you to write this (usually empty) method and it will call it. Fortunately, this only takes a few bytes of memory and it only gets called once, so there really isn’t an efficiency loss for doing this.

When the user of your application clicks on the form’s close button, or otherwise tells the application to terminate, HOWL will direct control to the myForm_t.onClose method. You can do other things to clean up your application when the program is about to quit, but the main thing you need to do is to tell Windows that the application is quitting and this is done by executing w.PostQuitMessage( 0 ); As it turns out, you generally won’t put any application cleanup code directly in the onClose method; there is an appTerminate procedure that HOWL will call when your program terminates execution and you’ll put all your cleanup code in that procedure.

We’ve talked about the appStart and appTerminate procedures, let’s take a look at them. A typical appStart procedure takes the following form:

procedure appStart;

begin appStart;

push( esi );

// Create the main application window:

w.GetSysColor( w.COLOR_MENU );

mov( eax, bkgColor_g );

w.CreateSolidBrush( eax );

mov( eax, bkgBrush_g );

The above statements initialize the bkgColor_g and bkgBrush_g global variables with the color (and corresponding solid brush) of the menu area on a typical Windows’ window. Though it’s not strictly necessary to have these global variables, they are useful when creating widgets in more complex applications, so most appStart procedures will initialize these variables. Note that you must initialize these variables before calling the constructor for the myForm_t class because the widget declarations appearing in the wForm..endwForm statement will be initialized in the call to the constructor for myForm . Note that you don’t have to specify the w.COLOR_MENU background color. You can specify any RGB color you like. You can use the RGB macro (e.g., RGB( 255, 128, 0 )) to specify the individual red, green, and blue (respectively) components of the RGB color.

The wForm( mForm ) .. endwForm statement appearing earlier in the source file (and the myForm_implementation macro invocation) automatically generated a constructor for the myForm_t class named create_myForm . That declaration also created an instance variable (an object) of type myForm_t named myForm . In order to initialize and display the form, you must call this constructor with the following (or reasonably compatible) arguments:

myForm.create_myForm

(

"My Form", // Window title

0, // Extended style

0, // Style

NULL, // No parent window

w.CW_USEDEFAULT, // x-position on screen

w.CW_USEDEFAULT, // y-position on screen

600, // Width

600, // Height

bkgColor_g, // Background color

true // Make visible on creation

);

mov( esi, pmyForm ); // Save pointer to main window object.

The first argument is a string parameter that HOWL will display in the title bar of the application’s main form. You can put any string you like here, although you should generally put the program’s name in the title bar.

The next two parameters let you extend the window style and extended style. In general, this two parameters will contain zero. HOWL always uses the style ( w.WS_CLIPCHILDREN | w.WS_OVERLAPPEDWINDOW ) and the extended style w.WS_EX_CONTROLPARENT when creating windows for a HOWL form. The styles you specify in the second and third constructor arguments will be logically ORed into HOWL’s existing styles.

The fourth parameter is the handle of the form’s parent form. For main application windows, this argument is always NULL.

The fifth and sixth arguments in the constructor invocation are the x- and y-coordinates on the screen where Windows will position the upper-left-hand corner of the form. You may specify any reasonable values here (within the range of the size of your screen, if you want the form to be visible) or you can specify w.CW_USEDEFAULT, in which case Windows will position the window automatically for you. For the position on the screen, the default coordinates are probably good values to use.

The seventh and eighth arguments are the width and height of the window you’re creating. You’ll have to pick these numbers based on the layout of the widgets on your form. You can also specify w.CW_USEDEFAULT for the width and height and Windows will pick values it feels are appropriate. Generally, though, you’ll want to explicitly specify the width and height for a typical form.

The ninth parameter is the background color to use for the main client area of the form. This is an RGB color value. As this example demonstrates, it’s a good idea to u se the bkgColor_g value in this parameter argument so you can specify that same value (or bkgBrush_g ) for other elements on the display that have a background color.

// Return main window handle in EAX if you want the system

// to support control selection via the TAB key. Return

// NULL in EAX if you don't want to support TAB key selection

// of the controls:

mov( myForm.handle, eax );

pop( esi );

end appStart;

The caller to appStart checks the return value in EAX to determine whether the form supports tab control selection. If you return NULL in EAX, then the form ignores the tab key during execution. If you return the form’s handle ( myForm.handle ), then Windows will support control/widget tab selection on the form.

// appTerminate-

// Called when the application is quitting, giving the app a chance

// to clean up after itself.

// Note that this is called *after* the mainAppWindow_t.onClose method

// executes (indeed, mainAppWindow_t.onClose, by posting the quit message,

// is what actually causes the program to begin terminating, which leads

// to the execution of this procedure).

procedure appTerminate;

begin appTerminate;

// Clean up the main application's form.

// Note that this will recursively clean up all the widgets on the form.

myForm.destroy();

w.DeleteObject( bkgBrush_g );

end appTerminate;

The HOWL system will call the appTerminate procedure after the myForm.onClose method terminates. The appTerminate procedure is a good place to call the class destructor ( myForm.destroy ) and clean up any other resources in use. In the code above, for example, the appTerminate procedure deletes the brush resource created in the appStart procedure. Note that you should only call the main form destructor in the appTerminate procedure, not in the myForm.onClose method. The destructor will free up any allocated storage and other resources in use and you shouldn’t do this while the object is still active (e.g., while the onClose method is executing).

// appException-

// Gives the application the opportunity to clean up before

// aborting when an unhandled exception comes along:

procedure appException( theException:dword in eax );

begin appException;

raise( eax );

end appException;

HOWL will call the appException procedure if an unhandled exception occurs during the execution of your program. As a general rule, it’s a good idea to clean up resouces as best you can before bailing out of the program.

// The main program for a HOWL application must simply

// call the HowlMainApp procedure.

begin howlDemo;

HowlMainApp();

end howlDemo;

The main application of a HOWL program, as noted earlier, should simply call the HowlMainApp procedure which is the real “main program” of the system.

Here’s the complete “trivial HOWL application” withou the annotations:

program howlDemo;

#linker( "comdlg32.lib" )

#linker( "comctl32.lib" )

?@NoDisplay := true;

?@NoStackAlign := true;

#includeOnce( "stdlib.hhf" )

#includeOnce( "howl.hhf" )

static

align( 4 );

bkgBrush_g :dword;

bkgColor_g :dword;

wForm( myForm )

endwForm

// Implement the mainAppWindow create procedure and object instances:

myForm_implementation();

method myForm_t.onClose;

begin onClose;

w.PostQuitMessage( 0 );

end onClose;

method myForm_t.onCreate;

begin onCreate;

end onCreate;

procedure appStart;

begin appStart;

push( esi );

// Create the main application window:

w.GetSysColor( w.COLOR_MENU );

mov( eax, bkgColor_g );

w.CreateSolidBrush( eax );

mov( eax, bkgBrush_g );

myForm.create_myForm

(

"My Form", // Window title

0, // Extended style

0, // Style

NULL, // No parent window

w.CW_USEDEFAULT, // Let Windows position this guy

w.CW_USEDEFAULT, // " " " " "

600, // Width

600, // Height

bkgColor_g, // Background color

true // Make visible on creation

);

mov( esi, pmyForm ); // Save pointer to main window object.

// Return main window handle in EAX if you want the system

// to support control selection via the TAB key. Return

// NULL in EAX if you don't want to support TAB key selection

// of the controls:

mov( myForm.handle, eax );

pop( esi );

end appStart;

// appTerminate-

// Called when the application is quitting, giving the app a chance

// to clean up after itself.

// Note that this is called *after* the mainAppWindow_t.onClose method

// executes (indeed, mainAppWindow_t.onClose, by posting the quit message,

// is what actually causes the program to begin terminating, which leads

// to the execution of this procedure).

procedure appTerminate;

begin appTerminate;

// Clean up the main application's form.

// Note that this will recursively clean up all the widgets on the form.

myForm.destroy();

w.DeleteObject( bkgBrush_g );

end appTerminate;

// appException-

// Gives the application the opportunity to clean up before

// aborting when an unhandled exception comes along:

procedure appException( theException:dword in eax );

begin appException;

raise( eax );

end appException;

// The main program for a HOWL application must simply

// call the HowlMainApp procedure.

begin howlDemo;

HowlMainApp();

end howlDemo;

Assuming you’ve named this file “myForm.hla”, you can compile and run this program as follows:

hla myForm

You can run the application from a command-line by typing “myForm” or you can double-click on the icon to run it in a traditional GUI style. Note that if you double-click on the icon, Windows will open up both the GUI window (your form) and a console window. As it turns out, having the console window is useful for debugging purposes, but if you want to ship a release version of your application, you’ll probably want to ditch the console window. You can achieve this by using the following command line to compile your application:

hla -w myForm

When you run the program (either from the command line or by double clicking on an icon), an empty gray window will appear. You can quit the program by clicking on the close box on the title bar.

To understand how the HOWL application framework functions, we need an example that is slightly more complex than the trivial example presented thus far. Consider the following modifications to the previous example:

procedure onPress(thisPtr:dword; wParam:dword; lParam:dword ); forward;

wForm( myForm )

wPushButton

(

myButton, // Field name in mainWindow object

"Close", // Caption for push button

10, // x position

10, // y position

125, // width

25, // height

onPress // "on click" event handler

);

endwForm

procedure onPress(thisPtr:dword; wParam:dword; lParam:dword );

begin onPress;

w.PostQuitMessage( 0 );

end onPress;

The onPress procedure is an example of an event handler. The HOWL code will automatically call various event handlers in response to some system event, such as someone pressing a button on a form. In this example, we’re going to place a push button on the formand the HOWL code will call the onPress event handler in response to someone pressing that button. How does HOWL know to call onPress rather than some other function? Easy, we’re going to tell it about onPress . The first step is to create a forward declaration for onPress that must appear before the wForm..endwForm statement. We’re going to reference onPress inside the wForm..endwForm statement, so we have to make sure it’s declared before wForm( myForm ) ; the forward declaration achieves this.2

The wPushButton delcaration appearing inside the wForm..endwForm statement tells HOWL to create a push button object on the form. The first argument ( myButton ) is the name of the field that HOWL will create inside the myForm class to represent the push button object. This is roughly equivalent to the following declaration in HLA:

type

myForm: class inherits( wForm_t);

var

myButton: wPushButton_p;

endclass;

(note that type wPushButton_p is defined to be a pointer to wPushButton_t .)

The remaining arguments in the wPushButton statement define the appearance of the button on the actual form. The second argument is the string label that HOWL will display on the button. The third through sixth arguments, as the comments state, specfy the x- and y-coordinates and the width and height of the button on the form. Note that the coordinates are relative to the upper-left-hand corner of the client area on the form.3 The last argument is the one of most interest to us here. This is the name of the “on click” event handler that HOWL will call when you press the push button on the form.

All widget event handlers are “widget procs”. This means that they are procedures with the following parameter list:

type

widgetProc :procedure( thisPtr:dword; wParam:dword; lParam:dword );

Note that widgetProc procedures are not class procedures or methods, they are standard procedures. Specifically, this means that you can’t use the this or super reserved words inside a widgetProc . However, note that a widgetProc does have a thisPtr parameter. This parameter will contain the address of the object that signaled the event (that is, thisPtr will point at the myButton object in this example when the user presses the button and HOWL calls the onPress procedure). In this example, we’ll not use thisPtr , but in more complex examples having a pointer to the object turns out to be important. The wParam and lParam arguments are passed from Windows message procedure on to the widgetProc unchanged. For certain widget types, these arguments contain important data. In the current example, we ignore these arguments as well.

For the onPress procedure in this example, we simply want to quit the program when the user presses the “close” button. Therefore, this onPress procedure executes the same code as the main form’s onClose method, that is: w.PostQuitMessage( 0 ); If you compile this code and run it, you can quit the program by pressing on the “close” button.

In most cases, these event handler procedures are how HOWL communicates with your code. Whenever the user initiates some event by interacting with the widgets on the form, HOWL calls the corresponding widget procedure(s) to let your program handle the event.

The HOWL Declarative Language

In the previous section you saw a couple of simple examples of the HOWL declarative language. The HOWL declarative language is the set of statements that are legal inside a wForm..endwForm sequence. The wPushButton statement was a good example of a HOWL declarative language statement. There are many other widget-defining statements present in the HOWL declarative language. This section will describe those statements.

Before describing the actual statements that define widgets, you should note that the wForm..endwForm statement is actually a class declaration in the HLA language. So in addition to all the legal declarative statements, you can also put any legal class declarations inside a wForm..endwForm statement. For example, if you want to communicate some data between various widgets on a form, one way to achieve this is by placing some class var declarations inside the wForm..endwForm statement:

wForm( myForm )

var

someData :dword;

endwForm

Your event handlers and other code and refer to this data field using the syntax myForm.someData .

Of course, you can add any other legal class objects into this declaration including class constants, procedures, methods, and iterators.

The howl.hhf header file implements the HOWL declarative language using an HLA context-free macro. The wForm..endwForm macro declaration includes various #keyword macros (like wPushButton ) that expand into appropriate declarations in the class (and via some macro magic, store away code to create the constructor procedure for the class). When you look at some HOWL delcarative code, it’s easy to forget that you’re looking at a declaration, not at executable code. It’s easy to think that you should be able to do something like the following:

wForm( myForm )

mov( btnXPosn, eax );

add( 10, eax );

mov( btnYPosn, ecx );

add( 10, ecx );

wPushButton

(

myButton, // Field name in mainWindow object

"Close", // Caption for push button

eax, // x position

ecx, // y position

125, // width

25, // height

onPress // "on click" event handler

);

endwForm

However, this won’t work. Don’t forget that the statements inside the wForm..endwForm declaration are emitted inside a class declaration. Stray statements such as “mov( btnXPosn, eax );” cannot appear inside a class declaration.

It is possible to sneak certain statements into the your widget declarations. Except for the first parameter in most widget declarations (which is the widget object’s name in the class declaration), HOWL records the parameter’s value and “plays it back” when generating the code for the form’s class constructor. This means you can sneak in some code if that code is appropriate for a parameter in a procedure call. Consider the following:

wForm( myForm )

wPushButton

(

myButton, // Field name in mainWindow object

"Close", // Caption for push button

returns

({

mov( btnXPosn, eax );

add( 10, eax );

}, "eax" ),

10, // y position

125, // width

25, // height

onPress // "on click" event handler

);

endwForm

You may specify global variables as arguments to a widget declaration, but you have to ensure that you’ve declared the global object prior to the wForm statement at that you’ve initialized the global object before calling the constructor for that form.

The following subsections describe the wForm..endwForm statement as well as all the widgets that may appear within a wForm..endwForm declaration.

wForm

wForm( <<formname>> )

<< widget and class field declarations >>

endwForm

The wForm..endwForm statement declares a form (or window) for an application. Every application will have at least one of these statements. The single argument is the name associated with the form. HOWL takes this name and generates five distinct program entities from it:

A class type named formname_t that represents the form’s type and holds the declarations for all the widgets on the form.
A data type named formname_p,
A global variable named formname , of type formname_t , that is an instance of the form object.
A global variable named pformname of type formname_p that is initialized with the address of the formname object.
A constructor (class procedure) of the name formname_t.create_formname . You will call this constructor to initialize the formname variable object.

Most programs will use the formname variable directly and ignore the pformname variable. However, pformname is available if having a pointer to the object is more convenient that the object itself.

The constructor for the object has the following prototype:

procedure formname_t.create_formname

(

caption :string;

exStyle :dword;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

fillColor :dword;

visible :boolean

);

caption HOWL displays this string in the title bar of the form’s window.

exStyle HOWL logically ORs this MS Windows "extended window style" (w.WS_EX_* constants) with w.WS_EX_CONTROLPARENT when creating the window for the form.

style HOWL logically ORs this MS Windows "window style" (w.WS_* constants) with w.WS_CLIPCHILDREN | w.WS_OVERLAPPEDWINDOW when creating the window for the form.

parent This is the handle of the parent window for this form. As most wForm objects do not have parent windows, this parameter should contain NULL.

x The x-coordinate on the screen of the upper-left-hand corner of the form.

y The y-coordinate on the screen of the upper-left-hand corner of the form.

width The width of the form (in pixels)

height The height of the form (in pixels)

fillColor This is an RGB value that specifies the background color for the form. The red component is the L.O. eight bits of this value, the green component is in bits 8..15 of this value, and the blue component is in bits 16..23. Bits 24..31 should contain zero. The howl.hhf header file defines a macro, RGB, that lets you assemble an RGB value from three constants: RGB( redConst, greenConst, blueConst ). For example, RGB( 255, 0, 0 ) corresponds to red will a full intensity.

visible This is a boolean constant that specifies whether the form will be created in a visible (true) or hidden (false) state. You can always call the formname.show() method to make a form visible or the formname.hide() method to hide the form at run-time. For the main application window, this field normally contains true.

Generally, formname objects are singletons. That is, you typically create only a single instance of a formname object. However, as formname _t is a standard HLA data type, there is nothing stopping you from creating multiple objects of this type. Most of the type, however, it would be somewhat confusing to have two instances of the same form on the display at one time. In some instances this is reasonable. For example, if you have a text editor form and you want to allow the user to edit multiple files (or multiple views of the same file) concurrently, it might make sense to have two instances of the same window on the screen at one time.

wForm..endwForm declarations are not recursive. That is, you cannot embed a wForm inside another wForm declaration. wForm windows are main application forms and support menus, tabs, and other facilities only possible on the main application form, hence the restriction.

wForm objects are examples of containers in HOWL. A container, as its name suggests, may contain other objects (specifically widget objects). There are a couple of different kinds of containers in HOWL, but wForm contains are special because they can contain two things that other containers cannot: menus and tabs. Therefore, this document will describe these widgets next

wMainMenu..endwMainMenu

wMainMenu

<< main menu widget declarations >>

endwMainMenu

A wForm object can contain an optional main menu widget. This consists of the wMainMenu..endwMainMenu statement. If a form contains a main menu widget, the main menu widget must be the first widget declaration appearing on the form. E.g.,

wForm( myForm )

wMainMenu

<< menu item declarations >>

endwMainMenu

<< other widget declarations >>

endwForm

Within the wMainMenu..endwMainMenu declaration you define the items that appear on the menu. These include menu items, submenus, and separators. The following subsections describe each of these items.

A wMainMenu object can be thought of as a container object, albeit a very specialized one. wMainMenu objects can contain wMenuItems, wMenuSeparators , and wSubMenu objects. Unlike normal containers, however, wMainMenu objects cannot contain arbitrary HOWL objects.

wMenuItem

A wMenuItem declaration defines a single menu item in a main menu or a submenu. This declaration is only legal within a wMainMenu..endwMainMenu or wSubMenu..endwSubMenu declaration.

wMenuItem

(

menuItemName,

menuItemChecked,

menuString,

menuHandler

);

The menuItemName argument is an identifier that HOWL inserts into the wForm object to represent this particular menu item. You generally won’t directly refer to this identifier in your programs, but HOWL requires a field name so you must supply a unique (to the class) identifier here.

The menuItemCheck argument is a boolean constant that specifies whether the menu item can contain a check mark next to it in the menu display. If this is true, then the menu item will have the ability to display (or not display) a checkmark next to the menu item. If this field is false, then the menu item will not have this ability. See the discussion of the wMenuItem_t.checked method to see how to set or clear this checkmark.

The menuString argument is a string constant that specifies the text that HOWL will display for the menu item.

The menuHandler argument is either NULL or the name of a widgetProc that HOWL will call when the user selects this particular menu item. If the argument is NULL, HOWL will ignore the selection of the menu item.

HOWL displays menu items across the menu bar on a wForm (the menu bar appears immediately below the title bar in the window). Generally, most main menu items are actually submenus, though straight menu items are also legal in and main menu.

wMenuSeparator

The wMenuSeparator declaration should only appear in a submenu (that is, within a wSubMenu..endwSubMenu declaration). This draws a horizontal bar across the menu to separate sets of menu items in a submenu.

wSubMenu..endwSubMenu

wSubenu

<< menu item declarations >>

endwSubmenu

Submenu item declarations are syntactically similar to main menu declarations. However, submenus must always appear inside another menu declaration (either a wMainMenu..endwMainMenu or some other wSubMenu..endwSubmenu declaration). Unlike wMenuItem declarations, there is no handler associated with a submenu. HOWL (and Windows) automatically handles all the processing associated with a submenu.

Menu Example

Here’s a complete menu declaration, including submenus within submenus and menu items in the main menu:

wForm( mainAppWindow );

wMainMenu;

wSubMenu( menu_1, "menu1" );

wMenuItem( menu_1_1, false, "Item_1_1", handler_1_1 );

wMenuItem( menu_1_2, true, "Item_1_2", handler_1_2 );

wMenuItem( menu_1_3, true, "Item_1_3", handler_1_3 );

wMenuSeparator;

wMenuItem( menu_exit, false, "Exit", exitHandler );

endwSubMenu;

wSubMenu( menu_2, "menu2" );

wMenuItem( menu_2_1, false, "Item_2_1", handler_2_1 );

wSubMenu( menu_2_2, "Menu_2_2" );

wMenuItem( menu_2_2_1, false, "Item_2_2_1", handler_2_2_1 );

wMenuItem( menu_2_2_2, false, "Item_2_2_2", handler_2_2_2 );

endwSubMenu;

wMenuItem( menu_3, false, "menu3", handler_3 );

endwMainMenu;

<< other widget declarations >>

endwForm

wTab

(

tabName, // identifier

tabString, // string

tabHandler, // widgetProc name or NULL

bkgColor // RGB color

)

By default, a wForm object provides a single surface to which you can attach widgets. The wTab declaration allows you to specify multiple surfaces on a form, each user-selectable by clicking on a tab at the top of the form. Like wForm objects, wTab objects are containers and may contain all the same widgets (except wMainMenu items). If you utilize tabs on a wForm object, the first wTab declaration must appear after the wMainMenu declaration (if any) and before any other widgets, e.g.,

wForm( mainAppWindow );

wMainMenu;

wMenuItem( exitMenu, false, "exit", exitHandler );

endwMainMenu;

wTab( tab1, "tab1", NULL, bkgColor_g );

<< widgets associated with tab1 >>

The declarations for widgets associated with a tab appear immediately after that tab up to the next tab declaration or the endwForm clause. Most forms, if they use tabs, will have at least two tabs. Here’s an example declaration of a form with two tabs:

wForm( mainAppWindow );

wMainMenu;

wMenuItem( exitMenu, false, "exit", exitHandler );

endwMainMenu;

wTab( tab1, "tab1", NULL, bkgColor_g );

wPushButton

(

buttonOnTab1, // Identifier for button

"Tab1 Button", // Caption for push button

10, // x position

10, // y position

125, // width

25, // height

onClick1 // "on click" event handler

);

wTab( tab2, "tab2", NULL, bkgColor_g );

wPushButton

(

buttonOnTab2, // Identifier for button

"Tab2 Button", // Caption for push button

10, // x position

10, // y position

125, // width

25, // height

onClick2 // "on click" event handler

);

endwForm

This example creates two tab pages on the form, each with on button on the respective forms.

HOWL and Windows automatically handle switching from one form to the other when the user clicks on the tabs.

Note that if you place on or more tabs on a form, the size of the client area (where you can put other widgets) is reduced by the size of the tabs bar at the top of the form.

Check Boxes

HOWL supports five types of check boxes: generic check boxes (wCheckable), standard check boxes (wCheckBox), three-state check boxes (wCheckBox3), left-text check boxes (wCheckBoxLT), and three-state left-text checkboxes (wCheckBox3LT).

The non-three-state checkboxes alternate between two states when the user clicks on the check box (or its caption): checked and unchecked. The three-state check boxes alternate between three states: unchecked, checked, and grayed (don’t care).

The standard (non-LT) checkboxes draw their check boxes immediately to the left of the caption (that is, the text is to the right of the check box). The LT (left text) check boxes draw their text to the left of the check box.

CheckBox declarations let you specify an "onClick" event handler that HOWL will call whenever the user clicks on a checkbox and changes its state. This argument should either be the name of a widgetProc procedure or NULL (if you don’t want HOWL to call any procedure, which is actually a common occurrence with checkboxes).

wCheckable

(

checkBoxID, // Identifier for checkbox

caption, // Caption for checkbox

style, // Style for checkbox

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

This declaration creates a generic checkbox on the form. The style argument must be one of the following constants:

w.BS_3STATE Creates a button that is the same as a check box, except that the box can be grayed as well as checked or unchecked. Use the grayed state to show that the state of the check box is not determined.

w.BS_AUTO3STATE Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and unchecked.

w.BS_AUTOCHECKBOX Creates a button that is the same as a check box, except that the check state automatically toggles between checked and unchecked each time the user selects the check box.

w.BS_CHECKBOX Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the w.BS_LEFTTEXT style (or on Windows 95 only, with the equivalent w.BS_RIGHTBUTTON style).

Possibly OR’d logically with one of the following constants (as appropriate):

w.BS_BOTTOM Places text at the bottom of the button rectangle.

w.BS_LEFTTEXT Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the w.BS_RIGHTBUTTON style.

w.BS_CENTER Centers text horizontally in the button rectangle.

w.BS_LEFT Left-justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the w.BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.

w.BS_PUSHLIKE Makes a button (such as a check box, three-state check box, or radio button) look and act like a push button. The button looks raised when it isn't pushed or checked, and sunken when it is pushed or checked.w.BS_RIGHT Right-justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the w.BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.

w.BS_RIGHTBUTTON Positions a radio button's circle or a check box's square on the right side of the button rectangle. Same as the w.BS_LEFTTEXT style.

w.BS_TOP Places text at the top of the button rectangle.

w.BS_VCENTER Places text in the middle (vertically) of the button rectangle.

wCheckBox

(

checkBoxID, // Identifier for checkbox

caption, // Caption for checkbox

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

This declaration creates a standard checkbox on the form.

wCheckBox3

(

checkBoxID, // Identifier for checkbox

caption, // Caption for checkbox

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

This declaration creates a three-state checkbox on the form.

wCheckBox3LT

(

checkBoxID, // Identifier for checkbox

caption, // Caption for checkbox

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

This declaration creates a three-state, left-text, checkbox on the form.

wCheckBoxLT

(

checkBoxID, // Identifier for checkbox

caption, // Caption for checkbox

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

This declaration creates a left-text checkbox on the form.

wComboBox

A combobox is a combination editBox, listBox, and pull-down menu. The user can type text directly into the editBox section of the combo box or click on the arrow on the right side of the widget to open up a pull-down menu from which the user can select an item.

wComboBox

(

comboBoxID, // ComboBox name (an identifier)

"combo box", // Initial string in the edit box (usually and empty string)

x, // x

y, // y

w, // width

h, // height

sorted, // true or false

onCBSelChange, // onSelChange handler (or NULL)

"comboBox1", // List of initial string values for the list

"comboBox2", // This list may contain zero or more items.

"comboBox3"

);

The comboBoxID argument is the HLA identifier name that HOWL will use for the comboBox object within the wForm declaration; this name should be unique within the form declaration.

The second argument is a string that HOWL will use as the default value of the edit box field when the form is first created. Most often, this will be the empty string. Note that once the user enters data into the edit box or selects and entry from the pull-down menu list, the initial string value is lost.

The x, y, w, and h fields specify the position and size of the combo box on the form.

The sorted field is a boolean value that determines whether the fields of the pull-down menu list are sorted or remain in their "inserted" order. If this field is true, then Windows will sort each entry you add to the list (including the initial entries). If this field is false, then Windows leaves the entries in the order that you add them. Note that it is certainly possible to add and delete fields while the program is running; see the discussion of the wComboBox_t type later in this document. Most often, you’ll probably specify false for this field.

The onCBSelChange field lets you specify an "on selection change" event handler or NULL if you don’t want HOWL to invoke an event handler when the selection change. Normally, you’ll put NULL in this field because you’ll normally read the text from the widget when you press some other button or when some other event occurs, not when the user changes the text selection in the edit box or selects some entry from the pull-down menu list.

The remaining entries in the wComboBox declaration are optional. These entries, if present, must all be string constants that HOWL will use to populate the pull-down menu list. Note that you can add strings to the list at run time, so you don’t have to populate the list at declaration time. However, for many lists you’ll know the items the user can select from at design time, so you can fill in those entries in the wComboBox declaration.

wDragListBox

A wDragListBox object is similar to a wListBox (list box) object that provides the user with the ability to rearrange items in the list box. The declaration of a wDragListBox is

wDragListBox

(

dlName, // DragListBox name (HLA identifier)

x, // x-coordinate

y, // y-coordinate

w, // width

h, // height

onListBoxClick, // onClick handler

"DragListBox1", // Initial list population (can be empty)

"DragListBox2",

"DragListBox3"

);

The dlName argument is the name that HOWL will use in the wForm declaration for this wDragListBox object. This name must be unique within the wForm declaration.

The x, y, w, and h arguments specify the position and size of the wDragListBox object on the form.

The onListBoxClick argument is the name of a widgetProc that HOWL will call whenever the user clicks on one of the list items. This field can be NULL, in which case HOWL won’t bother to call any procedure when the user clicks on an item (this is actually a common situation; usually the program will determine the currently selected item in a wDragListBox when some other event occurs, and ignore the immediate changes that might occur in a wDragListBox object).

The remaining objects are optional. If present, they must all be strings and the wDragListBox declaration uses these strings to initially populate the wDragListBox object.

wEditBox

A wEditBox object allows the user to enter string data into a program.

wEditBox

(

ebName, // HLA identifier for this object

InitialText, // Initial text for edit box

x, // x position

y, // y position

w, // width

h, // height

s, // style

onChange // onChange handler (can be NULL)

);

The ebName argument is the name that HOWL will use in the wForm declaration for this wEditBox object. This name must be unique within the wForm declaration.

The InitialText argument is a string (usually empty) that HOWL uses to initialize the edit box’s text field when the form is first created.

The x, y, w, and h arguments specify the position and size of the wEditBox object on the form.

The s argument is the edit box style. This is any of the following edit box styles that HOWL logically ORs with the w.AUTOHSCROLL style:

w.ES_AUTOHSCROLL Automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero.

w.ES_AUTOVSCROLL Automatically scrolls text up one page when the user presses the ENTER key on the last line.

w.ES_CENTER Centers text in a multiline edit control.

w.ES_LEFT Left-aligns text.

w.ES_LOWERCASE Converts all characters to lowercase as they are typed into the edit control.

w.ES_MULTILINE Designates a multiline edit control. The default is single-line edit control.

When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style.

When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed.

If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed.

Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Note that edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.

w.ES_NOHIDESEL Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus.

w.ES_NUMBER Allows only digits to be entered into the edit control.

w.ES_OEMCONVERT Converts text entered in the edit control. The text is converted from the Windows character set to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.

w.ES_PASSWORD Displays an asterisk (*) for each character typed into the edit control. You can use the EM_SETPASSWORDCHAR message to change the character that is displayed.

w.ES_READONLY Prevents the user from typing or editing text in the edit control.

w.ES_RIGHT Right-aligns text in a multiline edit control.

w.ES_UPPERCASE Converts all characters to uppercase as they are typed into the edit control.

w.ES_WANTRETURN Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box's default push button. This style has no effect on a single-line edit control.

The onChange argument is the name of a widgetProc that HOWL will call whenever the user changes any text in the edit box. This field can be NULL, in which case HOWL won’t bother to call any procedure when the user changes the text (this is actually a common situation; usually the program will determine the currently selected item in a wEditBox when some other event occurs, and ignore the immediate changes that might occur in a wEditBox object). Note that if onChange is non-NULL, then HOWL will call the widgetProc any time there is a single-character change to the edit box; this is probably more often than you’d like, which is why this field is generally NULL and applications simply read the data from the edit box when some other event occurs.

wEllipse

(

ellipseName, // HLA identifier

x, // x

y, // y

w, // width

h, // height

lineColor, // linecolor (RGB)

fillColor, // Ellipse interior color (RGB)

bkgColor // Ellipse exterior color (RGB)

)

The ellipseName argument is the identifier name that HOWL uses in the wForm declaration for the ellipse object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the ellipse. If these coordinates and sizes form a square, then you’ll draw a circle on the form.

The lineColor argument specifies an RGB value that HOWL uses when drawing the outline of the ellipse (the pen color). wEllipse objects always draw the outline with a solid line.

The fillColor argument specifies an RGB value that HOWL uses to fill the interior of the ellipse. wEllipse objects always fill the interior with a solid brush (color).

The bkgColor argument specifies an RGB value that HOWL uses to fill the retangular area described by x, y, w, and h that is outside the ellipse. As a general rule, this should be the same color as the background color for the form unless you want a visible rectangle surrounding the ellipse. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

wIcon

The wIcon declaration places an icon object on the form.

wIcon

(

iconIdentifier, // icon name (HLA identifier)

IconResourceStr, // icon resource value

x, // x

y, // y

w, // width

h, // height

bkgColor // background color

)

The iconIdentifier field is an HLA identifier that HOWL uses in the form declaration for this particular icon. This name must be unique within the wForm declaration.

The IconResourceStr argument is either a string containing the name of an internal icon resource value or a constant that is less than $1_0000 (that specifies a system icon). If this is a string, it is not a filename for the icon, rather it is a resource ID produced by a resource compiler. See the HLA examples (HOWL directory) for examples that show how to use the resource compiler to produce icons for a program. If this is a value less than $1_0000, then it must be one of the following values:

w.IDI_APPLICATION
w.IDI_ASTERISK
w.IDI_EXCLAMATION
w.IDI_HAND
w.IDI_QUESTION
w.IDI_WINLOGO

Because of syntactical issues with the HLA macro language, if you want to specify these constants as the IconResourceStr argument (which normally must be a string), the best way to do this is to use instruction composition thusly:

wIcon

(

icon1, // icon name

mov( w.IDI_APPLICATION, eax), // icon resource value

10, // x

440, // y

32, // width

32, // height

bkgColor_g // background color

)

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the icon. If this bounding box is too small for the icon, portions of the icon will be clipped. If this bounding box is too big for the icon, then HOWL will fill the extra area with the background color.

The bkgColor argument specifies the background color that HOWL will use to fill the bounding box for the icon if the icon itself is smaller than the bounding box specified by the x, y, w, and h fields.

wGroupBox..endwGroupBox

A wGroupBox object is a container. It draws a rectangular box on a form that contains other objects. All the widgets you declare between a wGroupBox statement and the corresponding endwGroupBox terminator will be contained by the group box (and can be treated as a whole) at run time.

Note that placing wRadioButtons within a wGroupBox object does not automatically create a set of radio set buttons. See the wRadioSet declaration for that purpose. wGroupBox objects really exist just to make the form look pretty.

wGroupBox

(

groupBoxID, // HLA identifier

Caption, // String caption for group box

x, // x position

y, // y position

w, // width

h // height

)

<<Other widget declarations, not including Radio Sets >>

endwGroupBox

wLabel

(

labelID, // HLA identifier

labelString, // Label string

x, // x

y, // y

w, // width

y, // height

style, // Alignment and style

textColor, // Foreground color

bkgColor // Background color

);

The wLabel declaration lets you place a text string on the form.

The labelID argument is the name of the wLabel field within the form’s class. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the label’s string. If this bounding box is too small for the string, portions of the string will be clipped. If this bounding box is too big for the icon, then HOWL will fill the extra area with the background color.

The style field is one or more of the following Windows constants logically-ORed together:

w.DT_BOTTOM Bottom-justifies text. This value must be combined with DT_SINGLELINE.

w.DT_CENTER Centers text horizontally.

w.DT_EXPANDTABS Expands tab characters. The default number of characters per tab is eight.

w.DT_LEFT Aligns text to the left.

w.DT_NOPREFIX Turns off processing of prefix characters. Normally, DrawText interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off.

w.DT_RIGHT Aligns text to the right.

w.DT_SINGLELINE Displays text on a single line only. Carriage returns and linefeeds do not break the line.

w.DT_TOP Top-justifies text (single line only).

w.DT_VCENTER Centers text vertically (single line only).

w.DT_WORDBREAK Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.

For example, to vertically and horizontally center a string within the wLabel bounding box, you would use the following constant for the style field:

w.DT_CENTER | w.DT_VCENTER | w.DT_SINGLELINE

The textColor and bkgColor fields are RGB values that specify the (solid) colors used to draw the text and the backgroun for the text. Usually the text’s background color is the same as the form’s background color unless you are trying to create a special effect.

wListBox

A wListBox object contains a sequence of strings from which the user can select a single entry. The declaration of a wListBox is

wListBox

(

lbName, // ListBox name (HLA identifier)

x, // x-coordinate

y, // y-coordinate

w, // width

h, // height

sort, // true or false

onListBoxClick, // onClick handler

"ListBox1", // Initial list population (can be empty)

"ListBox2",

"ListBox3"

);

The lbName argument is the name that HOWL will use in the wForm declaration for this wListBox object. This name must be unique within the wForm declaration.

The x, y, w, and h arguments specify the position and size of the wListBox object on the form.

The remaining objects are optional. If present, they must all be strings and the wListBox declaration uses these strings to initially populate the wListBox object.

wPasswdBox

A wPasswdBox object is very similar to a wEditBox object insofar as it allows the user to enter a string of text onto the form. The difference is that the wPasswdBox object displays asterisks (or some other character) when the user types a string into the editbox. This shields sensitive information from prying eyes.

wPasswdBox

(

pbName, // HLA identifier for this object

IntitialText, // Initial text for edit box

x, // x position

y, // y position

w, // width

h, // height

s, // style

onChange // onChange handler (can be NULL)

);

The pbName argument is the name that HOWL will use in the wForm declaration for this wPasswdBox object. This name must be unique within the wForm declaration.

The InitialText argument is a string (usually empty) that HOWL uses to initialize the password box’s text field when the form is first created. This is almost always the empty string.

The x, y, w, and h arguments specify the position and size of the wPasswdBox object on the form.

The s parameter is the Windows edit box style that HOWL logically ORs with the value (w.ES_AUTOHSCROLL | w.ES_PASSWORD) . See the discussion of the available styles in the description of the wEditBox object.

The onChange argument is the name of a widgetProc that HOWL will call whenever the user changes any text in the password box. This field can be NULL, in which case HOWL won’t bother to call any procedure when the user changes the text (this is actually a common situation; usually the program will determine the currently selected item in a wPasswdBox when some other event occurs, and ignore the immediate changes that might occur in a wPasswdBox object). Note that if onChange is non-NULL, then HOWL will call the widgetProc any time there is a single-character change to the password box; this is probably more often than you’d like, which is why this field is generally NULL and applications simply read the data from the password box when some other event occurs.

wPie

The wPie declaration defines a graphic object on the form that is a "pie slice", that is, a portion of a pie graph.

wPie

(

pieName, // HLA identifier

x, // x

y, // y

w, // width

h, // height

startAngle, // Starting handle (in degrees)

endAngle, // Ending angle (in degrees)

lineColor, // linecolor (RGB)

fillColor, // Ellipse interior color (RGB)

bkgColor // Ellipse exterior color (RGB)

)

The pieName argument is the identifier name that HOWL uses in the wForm declaration for the pie slice object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the pie slice.

The startAngle parameter is a real64 value that specifies the starting angle of the pie slice. The angle is specified in degrees. Angles are measured in a counter-clockwise fashion from the vertical line going from the middle of the bounding box to the top of the bounding box (warning: this is not intuitive).

The endAngle parameter is a real64 value that specifies the ending angle of the pie slice. The angle is specified in degrees. The wPie object draws a slice of a pie graph filling in the ellipse from the startAngle to the endAngle in a counter-clockwise fashion.

The lineColor argument specifies an RGB value that HOWL uses when drawing the outline of the pie slice (the pen color). wPie objects always draw the outline with a solid line.

The fillColor argument specifies an RGB value that HOWL uses to fill the interior of the pie slice. wPie objects always fill the interior with a solid brush (color).

The bkgColor argument specifies an RGB value that HOWL uses to fill the retangular area described by x, y, w, and h that is outside the pie slice. As a general rule, this should be the same color as the background color for the form unless you want a visible rectangle surrounding the pie slice. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

wPolygon

The wPolygon object draws a multi-vertex polygon on the screen.

wPolygon

(

polyName, // HLA identifier

x, // x

y, // y

w, // width

h, // height

lineColor, // linecolor (RGB)

fillColor, // Ellipse interior color (RGB)

bkgColor, // Ellipse exterior color (RGB)

x1, // Optional points list

y1, // Must have an even number of coordinates

x2,

y2,

xn,

)

The polyName argument is the identifier name that HOWL uses in the wForm declaration for the polygon object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the polygon.

The lineColor argument specifies an RGB value that HOWL uses when drawing the outline of the polygon (the pen color). wPolygon objects always draw the outline with a solid line.

The fillColor argument specifies an RGB value that HOWL uses to fill the interior of the polygon. wPolygon objects always fill the interior with a solid brush (color).

The bkgColor argument specifies an RGB value that HOWL uses to fill the retangular area described by x, y, w, and h that is outside the polygon. As a general rule, this should be the same color as the background color for the form unless you want a visible rectangle surrounding the polygon. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

The remain arguments always appear in pairs and specify the points that make up the polygon. If you specify n points (n*2 arguments), HOWL will draw n lines between each pair of points (and between (xn,yn) and (x1,y1) to complete the closed polygon).

wBitmap

The wBitmap declaration creates a bitmapped object on the form.

wBitmap

(

bmName, // HLA identifier

bmResource, // Bitmap resource name

x, // x

y, // y

w, // width

h, // height

bkgColor // RGB background color

)

The bmName argument is the identifier name that HOWL uses in the wForm declaration for the bitmapped object. This name must be unique within the wForm declaration.

The bmResource argument is a string constant specifying the name of the bitmap resource within the executable file. Note that this is not a filename on the disk. You must use the resource editor to compile a bitmap file into the executable file. The name you provide to the resource editor for this bitmapped object is the name you use for the bmResource string.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the bitmap. If the w and h fields are too small, Windows will truncate the bitmap when it draws it. If the w and h fields are larger than the bitmap, Windows will fill the extra area with the value of the bkgColor argument.

The bkgColor argument specifies an RGB value that HOWL uses to fill the retangular area described by x, y, w, and h that is outside the bitmap. As a general rule, this should be the same color as the background color for the form unless you want a visible rectangle surrounding the bitmap. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

wProgressBar

The wProgressBar declaration creates a progress bar object on the form.

wProgressBar

(

pbName, // HLA identifier

x, // x

y, // y

w, // width

h // height

)

The pbName argument is the identifier name that HOWL uses in the wForm declaration for the progress bar object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the progress bar.

See the description of the wProgressBar_t class type later in the document to learn how to specify the current progress in the progress bar.

wPushButton

(

pbID, // Identifier for push button

caption, // Caption for push button

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

The pbName argument is the identifier name that HOWL uses in the wForm declaration for the push button object. This name must be unique within the wForm declaration.

The caption argument is a string that Windows will display on the push button.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the push button.

The onClick argument is either NULL or the name of a widgetProc that HOWL will call when the user presses the corresponding button on the form.

Radio Button Objects

wForm declarations allow you to place radio buttons directly on a form or you can group a set of radio buttons together in a radio button set. In general, you’ll rarely use the first form because wRadioButton and wRadioButtonLT objects don’t readily exhibit button semantics. On a form by themselves, radio buttons behave just like check box objects so you’re better off using check box objects than radio buttons for this purpose. Generally, wRadioButton and wRadioButtonLT objects are useful when you’re building a form dynamically at run time rather than at design time with the HOWL declarative language. Nevertheless, the HOWL declarative language includes entries for wRadioButton and wRadioButtonLT objects for the sake of completeness.

wRadioButton

(

rbID, // Identifier for radio button

caption, // Caption for radio button

style, // Style for radio button

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

The rbName argument is the identifier name that HOWL uses in the wForm declaration for the radio button object. This name must be unique within the wForm declaration.

The caption argument is a string that Windows will display to the right of the radio button.

The style argument is either 0 (for standalone radio buttons) or one of the following constants (for radio button groups):

For the first radio button in a group:

w.BS_AUTORADIOBUTTON | w.WS_GROUP | w.WS_TABSTOP

For all but the first radio button in a group:

w.BS_AUTORADIOBUTTON

Note that you should really use the wRadioSet object to create sets of radio buttons rather than grouping them manually. Note that you must declare all grouped radio buttons consecutively in your source file. Any intervening widgets will end a radio set button group.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the radio button.

The onClick argument is either NULL or the name of a widgetProc that HOWL will call when the user presses the corresponding radio button on the form.

wRadioButtonLT

(

rbID, // Identifier for radio button

caption, // Caption for radio button

style, // Style for radio button

x, // x position on form

y, // y position on form

w, // width

h, // height

onClick // "on click" event handler (or NULL)

);

wRadioButtonLT objects are identical to wRadioButton objects except the caption text is draw on the left side of the radio buton rather than on the right side.

wRadioSet..endwRadioSet

Functional radio buttons are created as part of a radio button set. The wRadioSet..endwRadioSet block encapsulates a set of wRadioSetButton and wRadioSetButtonLT objects that HOWL treats as a single set of radio buttons rather than independent buttons. The wRadioSet declaration takes the following form:

wRadioSet

(

rsID, // Identifier for radio set

caption, // Caption for radio set group box

x, // x position on form

y, // y position on form

w, // width

h // height

);

<< radio set button declarations >>

endwRadioSet

Only wRadioSetButton and wRadioSetButtonLT declarations may appear within a wRadioSet..endwRadioSet declaration and you cannot nest wRadioSet..endwRadioSet declarations. The wRadioSet..endwRadioSet declaration creates a group box with the specified bounding box. It draws the caption string through the line of the bounding box in the upper left hand corner.

All radio set buttons appearing in a wRadioSet group are treated as a single set of radio buttons. At most one radio set button will be checked in the group; pressing one button unchecks any other buttons in the same group.

Note that a wRadioSet object is a container object. It contains all the radio set buttons associated with the radio set.

wRadioSetButton

(

rsbtnID, // HLA identifier

caption, // String caption for radio button

x, // x position

y, // y position

w, // width

y, // height

onClick // "on click" event handler

);

The wRadioSetButton declaration may only appear within a wRadioSet..endwRadioSet statement.

The rsbtnID argument must be a unique (to the form) HLA identifier. HOWL uses this identifier as the field name within the form class of the wForm..endwForm declaration.

The caption field is a string that HOWL displays to the right of the radio button image.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the radio button.

The onClick argument is either NULL or the name of a widgetProc that HOWL will call when the user presses the corresponding radio button on the form.

wRadioSetButtonLT

(

rsbtnID, // HLA identifier

caption, // String caption for radio button

x, // x position

y, // y position

w, // width

y, // height

onClick // "on click" event handler

);

The wRadioSetButtonLT declaration may only appear within a wRadioSet..endwRadioSet statement.

The rsbtnID argument must be a unique (to the form) HLA identifier. HOWL uses this identifier as the field name within the form class of the wForm..endwForm declaration.

The caption field is a string that HOWL displays to the left of the radio button image.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the radio button.

The onClick argument is either NULL or the name of a widgetProc that HOWL will call when the user presses the corresponding radio button on the form.

wRectangle

(

rectName, // HLA identifier

x, // x

y, // y

w, // width

h, // height

lineColor, // linecolor (RGB)

fillColor // Rectangle interior color (RGB)

)

The rectName argument is the identifier name that HOWL uses in the wForm declaration for the rectangle object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the rectangle.

The lineColor argument specifies an RGB value that HOWL uses when drawing the outline of the rectangle (the pen color). wRectangle objects always draw the outline with a solid line.

The fillColor argument specifies an RGB value that HOWL uses to fill the interior of the rectangle. wRectangle objects always fill the interior with a solid brush (color).

Note that there is no background color (as exists for other graphic objects). This is because the rectangle completely fills the bounding box so there is no need to fill the background area as it never shows through.

wRoundRect

(

rrectName, // HLA identifier

x, // x

y, // y

w, // width

h, // height

cw, // Corner width

cht, // Corner height

lineColor, // linecolor (RGB)

fillColor, // Round rectangle interior color (RGB)

BkgColor // Round rectangle exterior color (RGB)

)

The r rectName argument is the identifier name that HOWL uses in the wForm declaration for the round rectangle object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the round rectangle.

The cw and cht arguments specify the width and height of the ellipse used to draw the corners of the round rectangle.

The lineColor argument specifies an RGB value that HOWL uses when drawing the outline of the round rectangle (the pen color). wRoundRect objects always draw the outline with a solid line.

The fillColor argument specifies an RGB value that HOWL uses to fill the interior of the rectangle. wRectangle objects always fill the interior with a solid brush (color).

The bkgColor argument specifies an RGB value that HOWL uses to fill the retangular area described by x, y, w, and h that is outside the round rectangle. As a general rule, this should be the same color as the background color for the form unless you want a visible rectangle surrounding the bitmap. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

wScrollBar

(

scrollBarID, // Scrollbar name (HLA id)

x, // x

y, // y

w, // width

h, // height

style, // Scroll bar style

onChange // On change handler

)

The scrollBarID argument is the identifier name that HOWL uses in the wForm declaration for the scroll bar object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the scroll bar.

The style argument specifies the scroll bar style and is the logical-OR of zero or more of the following constants:

w.SBS_BOTTOMALIGN Aligns the bottom edge of the scroll bar with the bottom edge of the rectangle defined by the CreateWindow parameters x, y, nWidth, and nHeight. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.

w.SBS_HORZ Designates a horizontal scroll bar. If neither the SBS_BOTTOMALIGN nor SBS_TOPALIGN style is specified, the scroll bar has the height, width, and position specified by the parameters of CreateWindow.

w.SBS_LEFTALIGN Aligns the left edge of the scroll bar with the left edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.

w.SBS_RIGHTALIGN Aligns the right edge of the scroll bar with the right edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.

w.SBS_SIZEBOX Designates a size box. If you specify neither the SBS_SIZEBOXBOTTOMRIGHTALIGN nor the SBS_SIZEBOXTOPLEFTALIGN style, the size box has the height, width, and position specified by the parameters of CreateWindow.

w.SBS_SIZEBOXBOTTOMRIGHTALIGN Aligns the lower-right corner of the size box with the lower-right corner of the rectangle specified by the parameters of CreateWindow. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.

w. SBS_SIZEBOXTOPLEFTALIGN Aligns the upper-left corner of the size box with the upper-left corner of the rectangle specified by the parameters of CreateWindow. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.

w.SBS_SIZEGRIP Same as SBS_SIZEBOX, but with a raised edge.

w.SBS_TOPALIGN Aligns the top edge of the scroll bar with the top edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.

w.SBS_VERT Designates a vertical scroll bar. If you specify neither the SBS_RIGHTALIGN nor the SBS_LEFTALIGN style, the scroll bar has the height, width, and position specified by the parameters of CreateWindow.

The onChange argument is the name of a widgetProc that HOWL will call whenever there is a change made to the scroll bar’s position.

wTextEdit

A wTextEdit object allows the user to enter a text file object.

wTextEdit

(

teName, // HLA identifier for this object

InitialText, // Initial text for text edit object

x, // x position

y, // y position

w, // width

h, // height

s, // style

onChange // onChange handler (can be NULL)

);

The teName argument is the name that HOWL will use in the wForm declaration for this wTextEdit object. This name must be unique within the wForm declaration.

The InitialText argument is a string (usually empty) that HOWL uses to initialize the text editor’s text field when the form is first created.

The x, y, w, and h arguments specify the position and size of the wTextEdit object on the form.

The s argument is the Windows editbox style that HOWL logically ORs with the value (w.ES_MULTILINE | w.ES_WANTRETURN | w.WS_HSCROLL | w.WS_VSCROLL) . See the discussion of the legal values in the section on wEditBox .

The onChange argument is the name of a widgetProc that HOWL will call whenever the user changes any text in the text editor. This field can be NULL, in which case HOWL won’t bother to call any procedure when the user changes the text (this is actually the most common situation; usually the program will determine the currently selected item in a wTextEdit when some other event occurs, and ignore the immediate changes that might occur in a wTextEdit object). Note that if onChange is non-NULL, then HOWL will call the widgetProc any time there is a single-character change to the text edit object; this is probably more often than you’d like, which is why this field is generally NULL and applications simply read the data from the text edit object when some other event occurs.

wTrackBar

(

trackBarID, // Trackbar name (HLA id)

x, // x

y, // y

w, // width

h, // height

style, // Track bar style

onChange // On change handler

)

The trackBarID argument is the identifier name that HOWL uses in the wForm declaration for the track bar object. This name must be unique within the wForm declaration.

The x, y, w, and h fields specify the coordinates and sizes for the bounding box surrounding the track bar.

The style argument specifies the track bar style and is the logical-OR of zero or more of the following constants:

w.TBS_HORZ Designates a horizontal track bar (this is the default).

w.TBS_TOP Display tick marks on the top of a horizontal track bar.

w.TBS_BOTTOM Display tick marks on the bottom of a horizontal track bar (default).

w.TBS_VERT Designates a vertical track bar.

w.TBS_LEFT Display tick marks on the left side of a vertical track bar.

w.TBS_RIGHT Display tick marks on the right side of a vertical track bar (default).

w.TBS_BOTH Display tick marks on both sides of a track bar (vert or horz).

Note that all wTrackBar objects have the w.TBS_AUTOTICKS style.

The onChange argument is the name of a widgetProc that HOWL will call whenever there is a change made to the scroll bar’s position.

wUpDown

wUpDown

(

upDownID, // Up/down control object name

style, // No special format/style/alignment

x, // x

y, // y

w, // width

h, // height

min, // Minimum position

max, // Maximum position

initial, // Initial position

onUpDown // Click event handler

);

A wUpDown widget is a pair of arrow buttons that the user can click on to increment or decrement a value. wUpDown objects are stand-alone (see wUpDownEditBox for a version that is connected to an edit box).

The upDownID field is an HLA identifier that HOWL uses as the name of the object on the form. This name must be unique within the form class declaration.

The style argument is one of the following values:

UDS_ALIGNLEFT Positions the up-down control next to the left edge of the buddy window. The buddy window is moved to the right and its width decreased to accommodate the width of the up-down control. This style is generally used only with the UDS_AUTOBUDDY style. See wUpDownEditBox for additional details concerning buddy controls.

UDS_ALIGNRIGHT Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control. This style is generally used only with the UDS_AUTOBUDDY style. See wUpDownEditBox for additional details concerning buddy controls.

UDS_ARROWKEYS Causes the up-down control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.

UDS_AUTOBUDDY Automatically selects the previous window in the Z order as the up-down control's buddy window.

UDS_HORZ Causes the up-down control's arrows to point left and right instead of up and down.

UDS_NOTHOUSANDS Does not insert a thousands separator between every three decimal digits.

UDS_SETBUDDYINT Causes the up-down control to set the text of the buddy window (using the WM_SETTEXT message) when the position changes. The text consists of the position formatted as a decimal or hexadecimal string.

UDS_WRAP Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.

The x, y, w, and h arguments specify the position and size of the wUpDown object on the form. HOWL ignores these values if you specify a non-NULL buddy value; in that case, HOWL uses the bounding box of the wEditBox object to control the placement of the up/down arrows.

The min argument specifies the minimum value that a wUpDown object will return. If the control’s current value is equal to the min value and the user presses the down arrow, the wUpDown object will not decrement the value.

The max argument specifies the maximum value that a wUpDown object will return. If the control’s current value is equal to the max value and the user presses the up arrow, the wUpDown object will not increment the value.

The initial argument specifies the initial value of the wUpDown object when the form is created.

The onUpDown argument is either NULL or specifies the name of a widgetProc procedure that HOWL will call whenever the user presses an up or down arrow on the control. If this field is NULL, then HOWL will not call a function whenever an up or down arrow is pressed and the application will have to call an appropriate wUpDown method to retrieve the current value of the wUpDown control.

wUpDownEditBox

wUpDownEditBox

(

upDownID, // Up/down control object name

style, // No special format/style/alignment

x, // x

y, // y

w, // width

h, // height

min, // Minimum position

max, // Maximum position

initial, // Initial position

onTextChange, // On Change event handler (edit box)

onUpDown // Click event handler (up/down arrow)

);

A wUpDown widget is a pair of arrow buttons that the user can click on to increment or decrement a value. wUpDown objects can be stand-alone or they can be associated with a wEditBox object (the "buddy"). When a wUpDown object is associated with a buddy wEditBox object, the arrows are connect to the edit box and clicking on the up or down arrows produces a string in the wEditBox object representing the current value of the wUpDown object.

The style argument is one of the following values:

UDS_ALIGNRIGHT Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.

UDS_ARROWKEYS Causes the up-down control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.

UDS_AUTOBUDDY Automatically selects the previous window in the Z order as the up-down control's buddy window. This style shouldn’t be used with wUpDownEditBox objects.

UDS_HORZ Causes the up-down control's arrows to point left and right instead of up and down.

UDS_NOTHOUSANDS Does not insert a thousands separator between every three decimal digits.

UDS_WRAP Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.

The initial argument specifies the initial value of the wUpDown object when the form is created.

The onTextChange argument is either NULL or specifies the name of a widgetProc procedure that HOWL will call whenever the user changes a value in the edit box control. If this field is NULL, then HOWL will not call a function whenever the edit box changes and the application will have to call an appropriate wUpDownEditBox method to retrieve the current value of the wUpDownEditBox’s edit box control. Note that pressing an up or down error will cause a change to the edit box, which will call HOWL to call this function.

wTimer

wTimer

(

timerID, // Timer control object name

period, // Timeout value in milliseconds

timing, // Type of timer (wTimer_t.oneShot or wTimer_t.periodic)

onTimeOut // Timeout event handler

);

A wTimer widget creates a small background thread that calls the onTimeOut widget after some period of time. Timers operate on one of two modes: oneShot or periodic . In the wTimer_t.oneShot mode , the timer delays for at least the number of milliseconds specified by the period argument and then calls the onTimeOut widgetProc exactly once. In the wTimer_t.periodic mode, the timer calls the onTimeOut widgetProc once every period milliseconds.

Note that declaring a wTimer object in the HOWL declarative language does not actually start the timer operating. It initializes the object, but you must call the wTimer_t.start method associated with the class to actually begin the timing process. See the description of the wTimer_t class later in this document for more details.

wWindow..endwWindow

A wWindow object is a container. It specifies a rectangular area on a form that contains other objects. All the widgets you declare between a wWindow statement and the corresponding endwWindow terminator will be contained by the window (and can be treated as a whole) at run time.

wWindow

(

windowID, // HLA identifier

caption, // Window title (ignored unless style calls for title)

exStyle, // Extended style for window

style, // Windows’ style for window

x, // x position

y, // y position

w, // width

h, // height
bkgColor // RGB background color for window

)

<<Other widget declarations >>

endwWindow

The HOWL Run-time Library

Although the HOWL declarative language (the wForm..endwForm macro) makes it very easy to design forms, your applications will need to interact with the HOWL run-time library code in order to make full use of HOWL’s capabilities. This section of this document describes the run-time semantics of the HOWL library.

The first thing to note is that HOWL is an object-oriented library. Almost all HOWL data types and code are part of the HOWL object hierarchy. So the best place to start when describing HOWL is with a description of the object hierarchy.

HOWL contains a single base class, appropriately named wBase_t . All other objects in HOWL are derived from this class. We’ll describe wBase_t completely in the next section, but the important thing to note is that wBase_t is the root of the class hierarchy tree for HOWL.

As you should know from object-oriented programming, descendant (child/derived) classes inherit all the fields of their base (parent/ancestor) classes. Therefore, all the classes in the HOWL object hierarchy inherit the fields of the wBase_t class (and all other ancestor classes to that particular class). In the following sections that describe each of the classes in the HOWL hierarchy, the descriptions will only discuss the fields that are specific to a given class; this document assumes that you understand that each class will inherit fields from all the ancestor classes and that you should look at the documentation for those ancestor classes in order to get the full picture for each class.

Every HOWL object (that is derived from wBase_t ) contains a special wType field. This is an lword (128-bit) object that HOWL uses to maintain run-time type information about that particular object. This is an array of 128 bits that specify membership/absence from a particular class. When an application is given a generic pointer to an object of any HOWL type (e.g., wBase_t ), the application can test this array to see if that object is a specific type (or is derived from a specific type). To accommodate this, HOWL defines a set of constants for each of that HOWL class types (except wBase_t ) that have the following names and functions:

typename_b ("b" stands for "bit number") is a small integer number between zero and the number of HOWL class types (less that 128) that associates a unique enumerated value with each HOWL class type. This also provides an index into the wType bit array.
typename_ps ("ps" stands for "power set") is a singleton set constant containing a "1" bit at index typename_b with all other bits containing zero.
typename_c ("c" stands for "constant") is a constant (up to 128 bits) with a "1" bit in each bit position specifying whether typename is a descendant (or is) the type indicated by the typename_b bit position into typename_c. For example, wProgressBar_c would contain set bits in bit positions wProgressBar_b and wVisual_p because wProgressBar_t is derived from wVisual_t . Because all HOWL objects are derived from wBase_t , there is no need to set aside a bit position for wBase_t in wProgressBar_c . Note that typename_c is generated via the logical-OR of typename_ps and all the ancestor class "_ps" values for typename_t.

The following diagram shows the HOWL object hierarchy. The nodes in gray are abstract classes; you do not normally create objects of these types (generally, you only create objects of types derived from abstract base classes).

Private Data Fields

Many HOWL classes contain private data fields. Although HLA will not prevent you from accessing these private data fields, application programmers should avoid direct access of these private fields. Access to the private data fields is intended for use by HOWL functions only.

For those data fields whose values might be of interest to a HOWL application programmer, the HOWL library generally provides accessor ("getter") and mutator ("setter") functions that let you access these private fields. You should always attempt to use these accessor/mutator functions for all private data access. Reading the values of some private fields (by calling the accessor functions) may cause HOWL to make a Win32 API call to make the value consistent with Windows; writing to a private data field (via a mutator) may cause HOWL to execute some additional code to tell Windows (or the rest of HOWL) about the change. Reading and writing these private data fields directly may circumvent these actions that keep HOWL’s internal data structures consistent.

The private fields in a class are easily distinguished in the howl.hhf header file; the header collects all private data fields into record variables within the classes that have a "_private" suffix. Unless you are writing a class that is an extension of the HOWL library, you should not directly access these fields.

Abstract Classes

The HOWL class hierarchy contains several abstract base classes that combine features common to various concrete classes. The following subsections describe each of these base classes.

wBase_t

The wBase_t class is the root class of the entire HOWL hierarchy. This class has the following definition:

wBase_t:

class

var

handle :dword;

_name :string;

wType :lword;

wBase_private:

record

visible :boolean;

enabled :boolean;

onHeap :boolean;

align( 4 );

objectID :dword;

nextWidget :wBase_p;

// Pointer the wForm object that this

// object belongs to.

parentForm :wForm_p;

// Handle of the Windows parent window associated

// with this control. Note that parentForm.handle

// may not be the same as parentHandle because this

// object could belong to some other window that

// is a child window of the main form. (Okay, parentForm

// was probably a bad name to use).

parentHandle :dword;

endrecord;

static

objectID_g :dword; external( "objectID_object_t" );

// Constructors/Destructors:

procedure create_wBase

(

wbName :string

); external;

method destroy; external;

method show; external;

method hide; external;

method enable; external;

method disable; external;

// Accessor/mutator functions:

method get_handle; @returns( "eax" ); external;

method get_objectID; @returns( "eax" ); external;

method get_visible; @returns( "al" ); external;

method get_enabled; @returns( "al" ); external;

method get_onHeap; @returns( "al" ); external;

method get_parentHandle; @returns( "eax" ); external;

method get_parentForm; @returns( "eax" ); external;

method set_onHeap( onHeap:boolean ); external;

method set_parentHandle( parentHandle:dword ); external;

method set_parentForm( parentForm:wForm_p ); external;

// Default message processor:

method processMessage

(

hwnd :dword;

uMsg :dword;

wParam :dword;

lParam :dword

); external;

endclass;

objectID_g This is a static field that HOWL uses to dynamically assign unique Windows identifiers to objects. Applications should not reference this field; they must not modify the value of this field. HOWL automatically increments this field whenever you create an instance of some HOWL object.

wType The wType field is a 128-bit bit array that provides run-time type information about an object to the application. If you test bit position typename_b in the wType field, you can determine if the current object is derived from (or is) type typename. The howl.hhf header file defines typename_b constants for all the HOWL types (subsituting the appropriate type name, such as wButton_t , for typename). This is a public field for read-only access. Applications must never modify its value.

handle Almost all HOWL objects have a Windows handle associated with them. The handle field contains this value. Technically, handle ought to be a private data field (there is even an accessor function for it), however, because applications need to frequently access this field, it was made public. Note, however, that an application should never write data to this field.

_name This field is a string representation of the object’s name in the main form. This field is mainly useful for testing, debugging, and tracing purposes. Other than initializing this string pointer, the HOWL library doesn’t access this field at all, so an application is free to use this field however it wants.

visible This boolean variable contains true if the object is a wVisual_t object and is visible on the form. It contains false if the object is not visible. If the object isn’t a wVisual_t (or descendant) object, then this field’s value is meaningless. This is a private field, always use the accessor function to retrieve its value. Applications must never directly change the value of this field.

enabled This boolean variable contains true if the object is a wVisual_t object and is enabled on the form. It contains false if the object is not enabled. If the object isn’t a wVisual_t (or descendant) object, then this field’s value is meaningless. This is a private field, always use the accessor function to retrieve its value. Applications must never directly change the value of this field.

onHeap This field contains true if the object’s storage is allocated on the heap. It contains false if the object’s storage is not allocated on the heap. If you initialize an object in storage that is not on the heap, it is your responsibility to set this field to false. If you create an object and request heap allocation for it (by calling a class procedure constructor with ESI equal to zero), the HOWL constructors will automatically set this field to true. This is a private field, always use the accessor function to retrieve its value. Applications must never directly change the value of this field.

objectID The objectID field contains the specific Windows ID (if applicable) for the current object. The create method for an object generally copies the global objectID_g value to this field and then increments the global value to generate unique ID values for each object. For the most part, HOWL ignores this field (it identifies objects by the pointer to the object rather than by the Windows ID). This is a private field, always use the accessor function to retrieve its value. Applications must never directly change the value of this field.

nextWidget wContainer_t objects use this field to create a linked list of widgets contained by the container object. All objects created via the HOWL declarative language (except the wForm object) are contained by some object (e.g., the wForm object). However, it is possible to dynamically instantiate objects that are not contained by a form, and the form object itself isn’t contained by another container, so you cannot assume that this field contains a valid value unless you iterator across the widgets of a container object. This is a private data field, no application program access is legal.

parentForm This is a pointer to the wForm object that holds the current widget. Note that this is the actual object pointer, not the form’s handle. This is a private field, always use the accessor/mutator functions to read/write its value.

parentHandle This is the window handle of the Windows’ object on which the current widget is a child control. This is a private field, always use the accessor/mutator functions to read or write its value.

create_wBase The create_wBase procedure is the constructor for the class. Because wBase_t is an abstract class, you never instantiate objects of type wBase_t . Unless you are writing a constructor for a new class you’ve derived from wBase_t , you will probably never call this constructor. This constructor is responsible for setting up the object’s _name field (passed as an argument), setting up the ObjectID field, and initializing all the other fields to reasonable default values (that the derived classes’ constructors will probably overwrite).

destroy This is the base level destructor function. You do not generally call this method directly; instead, a higher-level destructor function will probably call this function when you invoke destroy on some object. The wBase_t.destroy method checks the onHeap field and will deallocate the storage associated with the object if the storage was allocated on the heap.

show ,

hide These two methods simply store true ( show ) or false ( hide ) into the visible field. Other than that, they do nothing. They are included in wBase_t just to allow code to show and hide all objects. Generally, wBase_t descendant classes (usually wVisual_t descendants) override these methods to show or hide a visual object on the screen.

enable ,

disable These two methods store true ( enable ) or false ( disable ) into the enabled field.. Other than that, they do nothing. They are included in wBase_t just to allow code to enable and disable objects. Generally, wBase_t descendant classes (usually wVisual_t descendants) override these methods to enable or disable a visual object on the screen.

get_handle,

get_objectID,

get_visible,

get_enabled,

get_onHeap,

get_parentHandle

get_parentForm These are "accessor" functions that retrieve the value of the associated class field. As a general rule you should always call the accessor function to retrieve an object’s data field values as the accessor might contain code to "condition" those values prior to consumption

set_onHeap This is a "mutator" function that lets an application write a value to the onHeap field. Applications should always call this mutator rather than writing directly to the onHeap field because their might be code in the mutator that does additional processing required by the class.

set_parentHandle

This is a "mutator" function that lets an application write a value to the parentHandle field. Applications should be very careful about writing to this field. The only time an application should write to parentHandle is when it dynamically creates a new object at run-time (or, in the rare case of moving a widget from one form to another).

set_parentForm This is a "mutator" function that lets an application write a value to the parentForm field. Applications should be very careful about writing to this field. The only time an application should write to parentHandle is when it dynamically creates a new object at run-time (or, in the rare case of moving a widget from one form to another).

processMessage The processMessage method is used by HOWL to do default Windows message processing when no other object handles a message sent from Windows. This is a Windows callback function and you should never call it directly unless you’re extending HOWL by added new classes (and you wind up calling this code from the processMessage function in your new class). See the HOWL source code for more details on this function.

wVisual_t

The wVisual_t class, derived from wBase_t, contains the basic information that all visual objects (that is, those appearing on a form) possess. Of course, as wVisual_t is derived from wBase_t, all wVisual_t objects include all the fields from the wBase_t type.

wVisual_t:

class inherits( wBase_t );

var

align( 4 );

wVisual_private:

record

x :dword;

y :dword;

width :dword;

height :dword;

bkgColor :dword;

bkgBrush :dword;

style :dword;

exStyle :dword;

endrecord;

// Constructors/Destructors:

procedure create_wVisual

(

wvName :string;

parentHandle :dword;

x :dword;

y :dword;

width :dword;

height :dword

); external;

// Accessor functions:

method get_x; @returns( "eax" ); external;

method get_y; @returns( "eax" ); external;

method get_width; @returns( "eax" ); external;

method get_height; @returns( "eax" ); external;

method get_bkgColor; @returns( "eax" ); external;

method get_style; @returns( "eax" ); external;

method get_exStyle; @returns( "eax" ); external;

method set_x( x:dword ); external;

method set_y( y:dword ); external;

method set_width( width:dword ); external;

method set_height( height:dword ); external;

method set_bkgColor

(

bkgColor:dword

); external;

method move( x:dword; y:dword ); external;

method resize( width:dword; height:dword ); external;

method setFocus; external;

override method show; external;

override method hide; external;

override method enable; external;

override method disable; external;

override method destroy; external;

method onClose; external;

method onCreate; external;

endclass;

x, y, width,

height These fields form a bounding rectangle into which the object will appear. These are private data fields. HOWL applications should use the accessor/mutator functions to change their values.

bkgColor This field holds an RGB value representing the background color for the window defined by the wVisual_t object. Never access this field directly; always use the accessor/mutator functions so that HOWL can properly update the private bkgBrush field. Note all objects derived from the wVisual_t class use this field,those objects that do not simply ignore its value.

bkgBrush This is the brush that Windows uses to paint the background color for the wVisual_t object. Note that this is a private field and applications should never access it. HOWL computes the value for this field from the bkgColor field. Note all objects derived from the wVisual_t class use this field,those objects that do not simply ignore its value.

style This is the window style used for various window objects. Not all wVisual_t objects make use of this field.

exStyle This is the window extended style used for various window objects. Not all wVisual_t objects make use of this field.

create_wVisual This is the constructor for the class. Because this is an abstract base class, you must never call this function with ESI containing NULL. In general, you will never directly call this function unless you are creating your own HOWL classes. Whenever you call the constructor for a concrete HOWL class, it will automatically call this constructor for you.

get_x,

get_y,

get_width,

get_height,

get_bkgColor

get_style,

get_exStyle

These are the "accessor" functions for this class. You should call these functions to retrieve any data fields for the object.

set_x,

set_y,

set_width,

set_height,

set_bkgColor

set_style

set_exStyle These are the "mutator" functions for the class. You must call these functions rather than storing values directly into the data fields for the object. These function do additional work that is necessary for the system (such as redrawing objects when you change their possition or size).

move This is a combination of set_x and set_y rolled into a single convenient package (which causes less redraw flashing on the screen versus making the two separate calls).

resize This is a combination of set_width and set_height rolled into a single convenient package (which causes less redraw flashing on the screen versus making the two separate calls).

show, hide These methods make a visual object visible ( show ) or invisible ( hide ) on the form. These methods are also responsible for updating the object’s visible field.

enable, disable These methods enable or disable (gray) an object on the form. Note that not all visual objects can be enabled or disabled. Those that cannot be disabled simply ignore calls to these methods.

set_focus This method changes the window focus to the current object.

onCreate,

onClose These methods are intended for internal use by the HOWL system. You should never call them directly.

wClickable_t

The wClickable_t type is an abstract base class derived from wVisual_t that contains fields and code associated with objects that the user can click on (with the mouse) on the form. This class inherits all the fields from wVisual_t. This class handles both single-click and double-click events. Some objects don’t support double-clicking, in which case the double-click facilities wind up being unused.4

wClickable_t:

class inherits( wVisual_t );

var

align( 4 );

wClickable_private:

record

onClick :widgetProc;

onDblClick :widgetProc;

endrecord;

procedure create_wClickable

(

wcName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

method get_onClick; @returns( "eax" ); external;

method get_onDblClick; @returns( "eax" ); external;

method set_onClick( onClick :widgetProc ); external;

method set_onDblClick( onDblClick :widgetProc ); external;

method click; external;

endclass;

onClick This is a pointer to a widgetProc procedure that HOWL will call when the user clicks on a wClickable_t object. This field must either contain NULL (meaning HOWL will ignore the click operation) or the address of a widgetProc procedure.

onDblClick This is a pointer to a widgetProc procedure that HOWL will call when the user double-clicks on a wClickable_t object. If this field contains NULL, then HOWL disables the double-click operation. Note that not all wClickable_t objects support double-clicking, so this field may be ignored by HOWL. Also note that if the user double-clicks on an object (that supports double clicking) and both the onClick and onDblClick fields contain non-NULL values, HOWL will call the onClick widgetProc procedure twice and the onDblClick widgetProc procedure once.

create_wClickable

This is the class constructor. Applications will not normally call this procedure (the constructors for derived classes will call this procedure).

get_onClick,

get_onDblClick These methods return the value of the onClick and onDblClick data fields. Application programs should always call these "accessor" functions rather than directly accessing these fields.

set_onClick,

set_onDblClick These "mutator" functions set the value of the onClick and onDblClick data fields.

click This method simulates a click on the current object’s button.

wButton_t

The wButton_t type is an abstract class that contains common fields for all the button, checkbox, and radio button class types. This class is derived from wClickable_t , so it inherits all the wClickable_t fields.

wButton_t:

class inherits( wClickable_t );

var

align( 4 );

wButton_private:

record

onPaint :widgetProc;

onHilite :widgetProc;

onUnHilite :widgetProc;

onDisable :widgetProc;

onSetFocus :widgetProc;

onKillFocus :widgetProc;

endrecord;

procedure create_wButton

(

wbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

method get_onPaint; @returns( "eax" ); external;

method get_onHilite; @returns( "eax" ); external;

method get_onUnHilite; @returns( "eax" ); external;

method get_onDisable; @returns( "eax" ); external;

method get_onSetFocus; @returns( "eax" ); external;

method get_onKillFocus; @returns( "eax" ); external;

method set_onPaint ( onPaint :widgetProc ); external;

method set_onHilite ( onHilite :widgetProc ); external;

method set_onUnHilite ( onUnHilite :widgetProc ); external;

method set_onDisable ( onDisable :widgetProc ); external;

method set_onSetFocus ( onSetFocus :widgetProc ); external;

method set_onKillFocus ( onKillFocus:widgetProc ); external;

method get_text( txt:string ); external;

method a_get_text; external;

method set_text( txt:string ); external;

override method processMessage; external;

endclass;

onPaint This is a pointer to a widgetProc procedure that HOWL will call whenever the button is painted on the screen. If this pointer contains NULL, HOWL does not call any user-defined onPaint procedure. On older versions of Windows this notification was used for owner-drawn buttons. Newer versions of Windows use the "owner drawn" style for this purpose. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

onHilite This is a pointer to a widgetProc that HOWL will call (if the pointer is non-NULL) when a button is first pressed. On older versions of Windows, this was used to draw the button in a special depressed state. In HOWL, you can use this event to trigger some operation when the button is first clicked. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

onUnHilite This is a pointer to a widgetProc that HOWL will call (if the pointer is non-NULL) when a button is released. On older versions of Windows, this was used to draw the button in a normal non-depressed state. In HOWL, you can use this event to trigger some operation when the button is released. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

onDisable This is a pointer to a widgetProc that HOWL will call (if the pointer is non-NULL) when a button is disabled. On older versions of Windows, this was used to draw the button in a disabled state. In HOWL, you can use this event to trigger some operation when the button is disabled. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

onSetFocus This is a pointer to a widgetProc that HOWL will call (if the pointer is non-NULL) when focus is shifted to the button. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

onKillFocus This is a pointer to a widgetProc that HOWL will call (if the pointer is non-NULL) when focus is shifted away from the button. By default, the wButton_t.create_wButton constructor initializes this field with NULL.

Note that wButton_t objects inherit the remaining button notification functions, onClick and onDblClick , from the wClickable_t class.

create_wButton The create_wButton procedure is the constructor for this class. Like all the constructors in HOWL abstract classes, user application do not normally call this constructor directly; constructors in derived classes will call this procedure.

get_onPaint,

get_onHilite,

get_onUnHilite,

get_onDisable,

get_onSetFocus,

get_onKillFocus These are accessor functions that return the values of the corresponding widgetProc function pointers. Note that the create_wButton construction initializes all these pointers to NULL when an object is first created.

set_onPaint,

set_onHilite,

set_onUnHilite,

set_onDisable,

set_onSetFocus,

set_onKillFocus These are the mutator functions that let you set the addresses of the event handler functions for this class.

get_text This function retrieves the caption text for a button and stores that text into the string passed as a parameter to this function. The string you pass to this function must have sufficient storage allocated for it to hold the caption or this function will raise an ex.StringOverflow exception.

a_get_text This function makes a copy of the button’s caption on the heap and returns a pointer to this string in the EAX register. It is the caller’s responsibility to free the storage associated with this string when it is done using the string data.

set_text This function changes the button’s caption text to the string value you pass as an argument.

processMessage This is an internal HOWL function. User applications do not call this method.

wCheckable_t

The wCheckable_t class is an abstract base class for button objects that are "checkable". This includes the various check boxes and radio buttons.

wCheckable_t:

class inherits( wButton_t );

procedure create_wCheckable_t

(

wchkName :string;

caption :string;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

method set_check( state:dword ); external;

method get_check; @returns( "eax" ); external;

endclass;

create_wCheckable

The procedure is the constructor for this class. Like all abstract base class constructors, applications should not call this procedure. The constructors for concrete classes will make calls to this constructor as appropriate.

get_check This method retrieves the current state of the checkable button. It returns true in EAX if the button is checked, false if the button is not checked.

set_check This method sets the current state of the checkable button. If the single argument contains true, the button will be checked; if the argument contains false, the button will be unchecked.

wSurface_t

The wSurface_t abstract base class represents a single "window" on a form onto which HOWL can draw things. This abstract class, for example, is the base class for graphic objects like rectangles as well as HOWL views and windows. wSurface_t objects are clickable (as this class inherits the wClickable_t class).

wSurface_t:

class inherits( wClickable_t );

var

align( 4 );

wSurface_private:

record

// onPaint event pointer:

onPaint :widgetProc;

endrecord;

procedure create_wSurface

(

wsName :string;

exStyle :dword;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

bkgColor :dword;

visible :boolean

); external;

override method destroy; external;

override method processMessage; external;

override method onClose; external;

override method onCreate; external;

method get_onPaint; @returns( "eax" ); external;

method set_onPaint( onPaint:widgetProc ); external;

endclass;

onPaint This widgetProc pointer is either NULL or points at a procedure that HOWL will call when it receives a w.WM_PAINT message for the surface.

create_wSurface The create_wSurface procedure is the constructor for the wSurface_t class. Like all abstract base class constructors, applications will not directly call this procedure -- the derived class constructors are the ones that will call this procedure.

destroy The destroy method is responsible for freeing up the storage associated with the object and the _bkgBrush system resource when an application is done using a wSurface_t object. Normally, applications will not directly call this destructor. Instead, derived class destructor methods will call this method when they are destroyed.

processMessage,

onClose,

onCreate These are private methods used by HOWL. Application programs should not call these methods.

get_onPaint,

set_onPaint These are the accessor/mutator functions that get/set the address of the onPaint event-handling widgetProc.

wFilledFrame_t

The wFilledFrame_t abstract base class is used for objects that contain graphic entities drawn with a line and filled with an interior color. This includes objects such as rectangles, ellipses, and round rectangles. This extends the wSurface_t type by adding a line drawing color and a fill color (on top of the background color provided by wSurface_t ).

wFilledFrame_t:

class inherits( wSurface_t );

var

align( 4 );

wFilledFrame_private:

record

lineColor :dword;

fillColor :dword;

_linePen :dword;

_lineBrush :dword;

_fillBrush :dword;

endrecord;

procedure create_wFilledFrame

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lineColor :dword;

fillColor :dword;

bkgColor :dword

); external;

method get_fillColor; @returns( "eax" ); external;

method get_lineColor; @returns( "eax" ); external;

method set_fillColor( fillColor:dword ); external;

method set_lineColor( lineColor:dword ); external;

override method destroy; external;

override method processMessage; external;

endclass;

lineColor This is the RGB color of the pen used to draw the outline of the graphic object. Applications must not access this field directly but should, instead, use the accessor/mutator functions because those function maintain the private _linePen and _lineBrush fields as well.

fillColor This is the RGB color of the brush used to fill the interior of the graphic object. Applications must not access this field directly but should, instead, use the accessor/mutator functions because those function maintain the private _fillBrush field as well. Note that the fillColor differs from the background color (inherited from wSurface_t ) in that the fill color paints the interior of the graphic object while the background color paints the exterior of the graphic object (within the bounding rectangle).

_linePen,

_lineBrush,

_fillBrush These are private fields in the class that applications must not access. These fields are automatically maintained by HOWL whenever you call one of the wFilledFrame_t mutator functions.

create_wFilledFrame

This is the constructor for the wFilledFrame_t class. Like other abstract base classes, you do not call this constructor directly, the derived classes’ constructions will call this constructor for you.

destroy This is the destructor for the class. It frees up storage allocated for an object and frees up the system brush resources created for the object. Applications do not normally call this destructor directly; derived class destructors will call this destructor automatically.

get_lineColor

get_fillColor,

set_fillColor,

set_lineColor These are the accessor and mutator functions for the wFilledFrame_t data fields. You must always call these functions to access the data fields of this class because these functions also maintain the private pen and brush fields for this class.

wabsEditBox_t

The wabsEditBox_t class is the abstract base class used by the classes that support textual input from the user (e.g., wEditBox_t, wPasswdBox_t , and wTextEdit_t ). Edit boxes (and text editors) are among the more feature-rich controls provided by Windows, so it’s not surprising that there are many fields and functions associated with this base class.

wabsEditBox_t:

class inherits( wVisual_t );

var

align( 4 );

wabsEditBox_private:

record

onChange :widgetProc;

onErrSpace :widgetProc;

onHScroll :widgetProc;

onVScroll :widgetProc;

onMaxText :widgetProc;

onUpdate :widgetProc;

onSetFocus :widgetProc;

onKillFocus :widgetProc;

textColor :dword;

endrecord;

procedure create_wabsEditBox

(

webName :string;

initialTxt :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

method get_onChange; @returns( "eax" ); external;

method get_onErrSpace; @returns( "eax" ); external;

method get_onHScroll; @returns( "eax" ); external;

method get_onMaxText; @returns( "eax" ); external;

method get_onUpdate; @returns( "eax" ); external;

method get_onSetFocus; @returns( "eax" ); external;

method get_onKillFocus; @returns( "eax" ); external;

method set_onChange ( onChange :widgetProc ); external;

method set_onErrSpace ( onErrSpace :widgetProc ); external;

method set_onHScroll ( onHScroll :widgetProc ); external;

method set_onMaxText ( onMaxText :widgetProc ); external;

method set_onUpdate ( onUpdate :widgetProc ); external;

method set_onSetFocus ( onSetFocus :widgetProc ); external;

method set_onKillFocus ( onKillFocus:widgetProc ); external;

method get_textColor; @returns( "eax" ); external;

method set_textColor( textColor:dword ); external;

method undo; external;

method cut; external;

method copy; external;

method paste; external;

method clear; external;

method get_canUndo; @returns( "eax" ); external;

method emptyUndoBuffer; external;

method get_modified; @returns( "eax" ); external;

method set_modified( modified:boolean ); external;

method get_text( txt:string ); external;

method a_get_text; @returns( "eax" ); external;

method set_text( txt:string ); external;

method get_length; @returns( "eax" ); external;

method get_selectedText( txt:string ); external;

method a_get_selectedText; @returns( "eax" ); external;

method get_selection

(

var startPosn :dword;

var endPosn :dword

); external;

method set_selection

(

startPosn :dword;

endPosn :dword

); external;

method replace_selection

(

replacement :string;

canUndo :boolean

); external;

override method processMessage; external;

endclass;

onChange This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever any change is made to the text associated with the control. Note that HOWL will call this function after the update is drawn to the screen.

onErrSpace This is a widgetProc pointer that HOWL will call (if it is not NULL) if Windows cannot allocate sufficient storage to handle the current editor operator.

onHScroll This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever the user clicks on the control’s horizontal scroll bar. Note that HOWL will call this function before the update is drawn to the screen.

onVScroll This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever the user clicks on the control’s vertical scroll bar. Note that HOWL will call this function before the update is drawn to the screen.

onMaxText This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever the user exceeds the maximum number of character for the edit control.

onUpdate This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever any change is made to the text associated with the control. Note that HOWL will call this function before the update is drawn to the screen (this is the crucial difference between this function and the onChange handler).

onSetFocus This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever focus shifts to the edit control.

onKillFocus This is a widgetProc pointer that HOWL will call (if it is not NULL) whenever focus shifts away from the edit control.

textColor This is the RGB color that Windows will use to draw the text on the editbox. This is a private data field; applications should only access this value using the associated access and mutator. The constructor initializes the text color to black.

get_onChange,

set_onChange,

get_onErrSpace,

set_ onErrSpace,

get_onHScroll,

set_onHScroll,

get_onVScroll,

set_onVScroll,

get_onMaxText,

set_onMaxText,

get_onUpdate,

set_onUpdate,

get_onSetFocus,

set_onSetFocus,

get_onKillFocus,

set_onKillFocus These are the accessor and mutator functions for all the data fields specific to this abstract base class. Applications should call these functions to access the data fields rather than accessing them directly.

canUndo This function returns true in EAX if it is possible to undo the last operation to the editBox buffer (via the undo method).

emptyUndoBuffer This method clears the undo buffer and sets the canUndo flag to false.

undo,

cut,

copy,

paste,

clear These methods perform the standard Windows editing functions on the current selection in an edit control. Normally, you’d call these functions when the user selects an appropriate "edit" menu entry or they press one of the standard accelerator keys (e.g., "control-C" for copy).

get_text This function retrieves the string (text) associated with an editor control and stores the text into the string argument passed as the parameter. The string passed as an argument must be large enough to hold the text or this function will raise an ex.StringOverflow exception.

a_get_text This function retrieves the string (text) associated with an editor control and stores the text into a string allocated on the heap. It is the caller’s responsibility to free the storage associated with this string when it is done using it. This function returns a pointer to the new string in the EAX register.

set_text This function replaces the text in the edit control with the string passed as an argument.

get_length This function returns the current number of characters in the string associated with the edit control.

get_selection This function retrieves the starting and ending zero-based indexes into the string of the current text selection of the edit control. These indexes are returned in the two arguments passed by value. Note that the ending index will contain the offset to the character just beyond the selection in the edit control.

set_selection This function sets the starting and ending indexes for the edit control.

replace_selection

This function replaces the selected text in the editBox with the string you supply as the argument.

get_textColor,

set_textColor These accessor/mutator functions get and set the text color that the widget uses.

processMessage This is a private method in the wabsEditBox_t class. Applications should not directly call this method.

wContainer_t

The wContainer_t abstract base class, as its name suggests, is a special class that can contain other widgets. Containers possess a special linked list of wBase_t objects and the wContainer_t provides methods to manipulate this list of objects. Classes derived from wContainer_t include form classes, windows, radio sets, and group boxes.

wContainer_t:

class inherits( wVisual_t );

var

align( 4 );

wContainer_private:

record

numWidgets :uns32;

widgetList :wVisual_p;

lastWidget :wVisual_p;

endrecord;

procedure create_wContainer

(

wcName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword

); external;

override method destroy; external;

override method show; external;

override method hide; external;

override method enable; external;

override method disable; external;

method get_numWidgets; @returns( "eax" ); external;

method insertWidget( theWidget:wBase_p ); external;

method findWidget( objectID:dword ); external;

iterator widgetOnForm( nestingLevel:uns32 ); external;

iterator widgetsJustOnForm; external;

endclass;

numWidgets This is the number of widgets contained by the wContainer_t object. The constructor initializes this field to zero and inserting widgets into the container increments this field by one. This is a private field; use the get_numWidgets method to retrieve this field’s value. Applications should never store a value directly into this field.

widgetList This is a pointer to the first item in the list of widgets contained by the wContainer_t object. This is a private field; applications should never access this field.

lastWidget This is a pointer to the last item in the list of widgets contained by the wContainer_t object. This is a private field; applications should never access this field.

destroy This method iteratively calls the destructor for all widgets contained by the wContainer_t object and then it frees the storage held by the container object itself. Because wContainer_t is an abstract base class, applications should not call this destructor directly. Instead, they will call the destructor for some derived class which will indirectly call this method. Imporant note: because a container automatically calls the destructor for all widgets contained by the container, an application must not explicitly call the destructor for any of those widgets.

show This method iteratively calls all the show methods for each of the widgets contained by the container. Because wContainer_t is an abstract base class, applications should not call this method directly. Instead, they will call the show method for some derived class which will indirectly call this method.

hide This method iteratively calls all the hide methods for each of the widgets contained by the container. Because wContainer_t is an abstract base class, applications should not call this method directly. Instead, they will call the hide method for some derived class which will indirectly call this method.

enable This method iteratively calls all the enable methods for each of the widgets contained by the container. Because wContainer_t is an abstract base class, applications should not call this method directly. Instead, they will call the enable method for some derived class which will indirectly call this method.

disable This method iteratively calls all the disable methods for each of the widgets contained by the container. Because wContainer_t is an abstract base class, applications should not call this method directly. Instead, they will call the disable method for some derived class which will indirectly call this method.

get_numWidgets This method returns the value of the numWidgets field in the EAX register. Note that there is no corresponding "set_numWidgets" mutator function; applications cannot directly set the value of this field, wContainer_t objects increment the value of this field by calling the insertWidget method.

insertWidget This method inserts a widget into the wContainer_t’s linked list. The argument is a pointer to a wVisual_t object (or some object type derived from wVisual_t ). Widgets are inserted into the linked list at the end of the list (i.e., after the widget pointed at by lastWidget ). As this is being written, there is no way to remove a widget from a wContainer_t’s widget list. This restriction may be relaxed in a future version of HOWL.

findWidget This function searches for a widget in the wContainer_t’s widget list. The single argument is the ObjectID value (inherited from wBase_t ) of the object to search for. This function is mainly useful for various Windows callback functions (message handlers) that pass along a widgets object identifier without specifying the object itself.

widgetOnForm This is an HLA iterator (that you use in an HLA foreach loop) that iterates over all the widgets in a container’s widget list. This iterator is recursive. This means that if one of the items in a widget list is a wContainer_t class (or a class derived from wContainer_t ), then the iterator will drill down into that container and return its list of widgets as well. For example, the wContainer_t destroy, show, hide, enable , and disable methods all use this iterator to process all the widgets held by the container. On each iterator of the foreach loop, this iterator returns a pointer to the current widget in the EAX register.

widgetsJustOnForm

This iterator is very similar to widgetOnForm except that it is not recursive. On each iteration of the foreach loop it will return an entry from the current container’s widget list. It will not recursively process the lists of any wContainer_t objects appearing in the current container.

Containers

There are five main (concrete) container objects in HOWL: wForm_t objects, window_t objects, wGroupBox_t objects, wTabs_t objects, and wRadioSet_t objects. We’ll consider the first three of these objects in this section (plus menu objects, because it makes sense to discuss menus along with wForm_t objects) and wRadioSet_t objects in the section on buttons.

Forms and Menus

The main form for an application is a wForm_t object. Most applications will have a single wForm_t object, though a multi-window application can certainly support two or more wForm_t windows. A wForm_t menu is special (compared, say, to a wTabPage_t object) because it supports a menu. In a sense, a wForm_t object is a double container because it can contain an arbitrary list of widgets and it can contain a list of menu items.

wForm_t

The wForm_t class type is a window_t object with the addition of a list of menu items (which may be empty). The wForm statement in the HOWL declarative language defines a class that is derived from wForm_t . The wForm statement inserts the widget declarations into this new class and creates a constructor for the new class. Therefore, wForm_t is the basis for all forms created with the HOWL declarative language. Technically, wForm_t is a concrete class , not an abstract class, (meaning you can create objects of type wForm_t ). However, in most HOWL applications your main window will actually consist of an object whose type is derived from wForm_t (the wForm..endwForm declaration creates this class for you).

wForm_t:

class inherits( window_t );

var

align( 4 );

wForm_private:

record

menuList :wMenuItem_p;

endrecord;

procedure create_wForm

(

wwName :string;

caption :string;

exStyle :dword;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

fillColor :dword;

visible :boolean

); external;

method appendMenuItem( mi:wMenuItem_p ); external;

override method insertWidget; external;

override method processMessage; external;

endclass;

menuList This is a private data field that points at the list of menu items for the wForm_t’s menu. Applications should not access this field.

create_wForm This is the constructor for wForm_t objects. If you call this procedure using the classname, e.g., "wForm_t.create_wForm( ... );" then this constructor will allocate storage for the wForm_t object on the heap and initialze all the fields of the wForm_t object with reasonable values (including the parameter values you specify). If you have a statically declared wForm_t object, or a pointer to a wForm_t object you’ve already allocated storage for, then calling this procedure via that object will initialize the fields of that object, e.g., "somewFormObject.create_wForm( ... );", without allocating new storage for the object. Although wForm_t is a concrete class and it’s not unreasonable for an application to call create_wForm directly, most applications will actually work with classes derived from wForm_t , so it would be unreasonable for an application to call this constructor directly. If you look back at the discussion of the wForm..endwForm statement in the section on the HOWL declarative language, you’ll notice that the appStart procedure calls a constructor named "myForm.create_myForm". This constructor is a good example of a constructor for a class ( myForm_t ) derived from wForm_t . Note that myForm is a statically declared object of type myForm_t (which is derived from wForm_t ) in the examle given earlier in this documentation.

wwName: this is a string that HOWL stores in the _name field of the object (from wBase_t ). HOWL does not copy this string, so the character data associated with this argument must exist for the duration of the program (and must not change). You should use str.a_cpy to create a copy of this string to pass to create_wForm if the original string might change during the execution of the program.

caption: This is the string that HOWL will display in the title bar of the wForm_t’s window on the screen. Note that Windows will create an internal copy of this string, so it need not continue to exist after the call to the constructor.

exStyle: the constructor logically-ORs the value you supply to this parameter with the Windows’ w.WS_EX_CONTROLPARENT extended window style. Normally you would supply zero for this parameter value. However, if you want your form to have some additional window extended style attributes, you can supply one (or more) of the w.WS_EX_* constants here. See the Windows documentation for w .CreateWindowEx for more details on the possible extended style constants you can use.

style: the constructor logically-ORs this value with the ( w.WS_CLIPCHILDREN | w.WS_OVERLAPPEDWINDOW) style when creating the window. Normally you would supply zero for this parameter value. However, if you want your form to have some additional window style attributes, you can supply one (or more) of the w.WS_* constants here. See the Windows documentation for w .CreateWindow for more details on the possible window style constants you can use.

parent: this is the handle of the parent window for this form. This should always be NULL (if you are creating a child window, you’ll probably be using the window_t type, not a wForm_t type).

x, y, width, height: These fields describe the position and size of the wForm_t window on the main screen. These will either be the pixel coordinates and sizes or the Windows’ constant w.CW_USEDEFAULT (that tells Windows to pick good default values for these arguments).

fillColor: This is the RGB background color you want to use for the client (drawing) area of the wForm_t window.

visible: if true, then the constructor makes this form visible when it creates it. If this argument is false, then you must explicitly call the show method to make the form visible on the screen. For the main form, this argument is almost always true. If you are creating multiple windows (forms), then you might set this argument to false for all but the main form and call the show method to display the windows as needed.

appendMenuItem This method appends a new menu item to the wForm_t object’s menu list. See the discussion of menu items (following shortly) for a complete discussio of those objects. In most HOWL applications, you will not directly call this method; the HOWL declarative language automatically appends all menu items you declare in the wMenu..endwMenu statement to the main window’s wForm_t object. However, if you want to manually create a wForm_t object, you can call this functiont to attach a menu item to the form.

insertWidget See wContainer_t.insertWidget for more details. Note that this overridden version will also set the parentForm field of the widget you insert (plus all contained widgets, if the argument is a container) to the value of the form.

processMessage This is an internal HOWL method. Applications should not call this function.

wMenu_t

Exactly one wMenu_t object is create for every wForm_t object that has a menu. The wMenu_t object corresonds to the main menu for the form. This should be the first menu item (note that wMenu_t is derived from wMenuItem_t , described next) added to the wForm_t object via an appendMenuItem method call.

wMenu_t:

class inherits( wMenuItem_t );

// Constructors/Destructors:

procedure create_wMenu

(

wmName :string;

wmText :string;

parentHandle :dword

); external;

override method destroy; external;

endclass;

create_wMenu This constructor creates the main menu item.

wmName: this is a string that HOWL stores in the _name field of the main menu object (from wBase_t ). HOWL does not copy this string, so the character data associated with this argument must exist for the duration of the program (and must not change). You should use str.a_cpy to create a copy of this string to pass to create_wMenu if the original string might change during the execution of the program.

wmText: This is basically ignored and should be the empty string or some string like "main menu".

parentHandle: This must be the handle of the wForm_t object that contains this menu.

destroy This is the destructor method for the wMenu_t object. Applications should not call this method directly if the menu is on a form. The wForm_t object that holds the menu will automatically call the destructors for all the objects on its menu list (including the wMenu_t object).

wMenuItem_t

wMenuItem_t objects generally correspond to the actual menu items present in the main window.

wMenuItem_t:

class inherits( wBase_t );

var

align( 4 );

wMenuItem_private:

record

nextMenu :wMenuItem_p;

itemType :dword;

itemString :string;

itemHandler :widgetProc;

endrecord;

// Constructors/Destructors:

procedure create_wMenuItem

(

wmiName :string;

parentHandle :dword;

itemType :dword;

itemString :string;

itemHandler :widgetProc

); external;

override method enable; external;

override method disable; external;

method checked( state:boolean ); external;

// Accessor functions:

method get_itemType; @returns( "eax" ); external;

method get_itemString; @returns( "eax" ); external;

method get_itemHandler; @returns( "eax" ); external;

method set_itemType( itemType:dword ); external;

method set_itemString( itemString:string ); external;

method set_itemHandler( itemHandler:widgetProc ); external;

endclass;

nextMenu This is a private data field that the wForm_t class uses to create a linked list of menu items on the main form. Applications should not access this field.

parentHandle This is the handle of the main application’s form

itemType This field specifies the type of the menu item. It must be the logical OR of oe or more of the following constants: w.MF_STRING, w.MF_CHECKED, w.MF_DISABLED, w.MF_ENABLED, w.MF_GRAYED, w.MF_SEPARATOR, and w.MF_UNCHECKED . See the Windows documentation for w.AppendMenu for more details.

itemString This is the string text that Windows displays for the menu item.

itemHandler This is a widgetProc procedure that HOWL will call when the user selects a menu item.

enable,

disable These two methods will enable or disable a menu item, respectively. Note that when HOWL disables a menu item, it will gray that menu item and will prevent the user from selecting it in the menu. This is equivalent to the (w.MF_DISABLE | w.MF_GRAYED) item type.

checked If the current menu item has the w.MF_CHECKED flag, then calling this method will display a check mark if the argument is true, it will clear a displayed check mark if the argument is false.

get_itemType,

get_itemString,

get_itemHandler These accessor functions return the values of the respective fields in the EAX register.

set_itemType,

set_itemString,

set_itemHandler These mutator functions set the values of the respective fields to the value passed as an argument. Note that the set_itemString function does not make a copy of the string data, it stores the string pointer directly into the itemString data field. Therefore, your application should make a copy of the string to pass to this mutator if the string data could change.

Tabbed Forms

A tabbed form is a wForm_t object that contains exactly one wTabs_t object on it. A wTabs_t object is a container that contains a list of wTabPage_t (window) objects on it, one wTabPage_t object for each tab. present on the wTabs_t control. Whenever the user selects one of the tabs on the wTabs_t control, HOWL will display the corresponding wTabPage_t object (hiding the previously displayed wTabPage_t object). This lets an application have multiple pages on the main form that the user can select the pages as needed.

wTabs_t

The wTabs_t class is a special type of container class. If used correctly, wTabs_t objects only hold wTabPage_t objects (called "pages") that correspond to a window on top of the main form that hold the widgets associated with a tab on that main form. wTabs_t objects represent the current state of a tabbed form.

wTabPage_array :pointer to wTabPage_p;

wTabs_t:

class inherits( wContainer_t );

var

align( 4 );

wTabs_private:

record

curSelection :dword;

numTabs :uns32;

pages :wTabPage_array;

numElements :dword;

endrecord;

procedure create_wTabs

(

wtName :string;

parent :window_p;

x :dword;

y :dword;

width :dword;

height :dword

); external;

method get_numTabs; @returns( "eax" ); external;

method curTab; @returns( "eax" ); external;

method setTab( tab:uns32 ); external;

method get_page( tabIndex:dword ); @returns( "eax" ); external;

method deleteTab( tabIndex:dword ); @returns( "eax" ); external;

method insertTab

(

index :dword;

tabText :string;

page :wTabPage_p

); external;

override method destroy; external;

override method processMessage; external;

endclass;

curSelection This field contains the zero-based tab index for the currently active tab on a wForm_t tabbed object. This is a private data field that applications must not access.

numTabs This private data field contains the number of tabs currently associated with the wTabs_t object. Applications should never directly access this data field. They can use the get_numTabs accessor method to query its value. Applications must never directly change the value of this field.

pages The pages data field is a pointer to an array of wTabPage_p pointers. This is a private data field and applications should not access or modify its contents. Applications can use the get_page method to read entries from the array pointed at by pages.

numElements This is a private data field that specifies the number of elements in the array pointed at by the pages data field. Applications must not access or modify this value.

create_wTabs This is the constructor for the wTabs_t class. If called as a class procedure (e.g., "wTabs_t.create_wTabs") then this procedure will allocate storage on the heap for a new wTabs_t object and return a pointer to that new object in ESI. If you call this method via an object variable (e.g., "myTab.create_wTab") then this constructor will initialize the fields of that object without allocating new storage for it (and return a pointer to the object in ESI).

wtName: this string is assigned to the _name field of the object. This string should not change during the execution of the program. Pass a copy of the string (using str.a_cpy) if it is possible for this string to change during program execution.

parent: this is the handle of the parent window_t object (e.g., wForm_t object) that holds this wTabs_t object.

x, y, width, height: These arguments specify the position and size of the tab control within the client area of the parent object. The x and y values are almost always zero, the width should be the width of the client area of the parent window, and the height should 25 or some other similar value.

destroy This is the destructor for the wTabs_t class. Generally, tabs are attached to a wForm_t object and that object will destroy the tabs when it is destroyed. Therefore, an application will rarely call a wTabs_t destructor unless it explicitly creates the wTab_t object and doesn’t attach those tabs to some other container (e.g., wForm_t ) object).

get_numTabs This method returns the current number of tabs on the tab control. In addition to returning the value of the numTabs data field, this method also does a sanity check to ensre that the number of tabs on the Windows control matches the numTabs data field value.

curTab This method returns the currently selected tab index (0..numtabs-1). Note that this method actually calls Windows to retrieve this value, it is not simply an accessor to the curSelection data field (indeed, this is a mutator to the curSelection field because it will update curSelection with the value that Windows returns). This also does a sanity check on the values and raises an exception if Windows and HOWL have different ideas about the number of tabs on the control.

setTab This method sets the currently selected tab to the value you pass as an argument. This value must be in the range 0..numTabs-1. If the argument is outside this range, the setTab method raises an exception. This method also does a sanity check to ensure that Windows’ and HOWL’s tab counts are the same.

deleteTab This function deletes a tab (specified by the zero-based tabIndex argument) from the tab bar on the form. Note that this function does not call the destructor for the tab object, nor does it destroy any of the widgets contained on the form. It simply removes the tab from the tab bar (and the corresponding entry from the array pointed at by the pages data field). This function returns the pointer to the wTabPage_t widget removed from the pages array in the EAX register. Note that this method does not remove the wTabPage_t object from the tab’s widgetList (that is, the tab still contains the wTabPage_t object). Therefore, if you destroy the tab, or otherwise iterate over all the widgets held by the wTabs_t container, you will still process the deleted tab. All that deleting a tab does is visibly remove it from the tab control on the form. Note that you can insert the deleted wTabPage_t object (whose address is returned in EAX by deleteTab ) by calling insertTab . It is your responsibility to save the value returned by deleteTab (or otherwise locate the deleted item) if you intend to reinsert it into the tab control later on.

insertTab This build adds a new tab entry to the tab control and inserts a pointer to a wTabPage_t object into the array pointed at by the tab’s pages data field.

index: This is the zero-based index specifying the tab position. This value must be in the range 0.. numTabs . If index is less than numTabs , then insertTab will insert the new tab in front of the tab at the specified index. If index is equal to numTabs , then insertTab will append the new tab to the end of the tab list. If index is greater than numTabs , insertTab will raise an exception.

tabText: this is the string that Windows will draw on the tab. Windows will make a copy of this string’s character data.

page: this is the wTabPage_t object that HOWL will display when you select the new tab. Generally, a program will place several other widgets on thie wTabPage_t display surface

processMessage This is a private method. Applications should never call this method..

wGroupBox_t

A wGroupBox_t object is a rectangular panel with a caption along the upper-left-hand corner of the rectangle (on top of the line outlining the rectangle). Generally, wGroupBox_t objects are used to visually separate and group items on a form.

wGroupBox_t:

class inherits( wContainer_t );

procedure create_wGroupBox

(

wgbName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword

); external;

endclass;

create_wGroupBox This is the constructor for the wGroupBox_t class.

wgbName: This is the name of the object that HOWL stores into the _name data field.

caption: This is the string that Windows displays in the upper-left-hand corner of the group box. Windows makes a copy of this string for its internal use.

parent: This is the handle of the window (usually the main form or a wView_t object on a tabbed form) that contains the group box.

x, y, width, height: These are the (parent-form-relative) coordinates and size for the group box.

Graphic Objects

Graphic objects in HOWL are static images that HOWL draws on a form. Examples include rectangles and ellipses. All graphic objects are derived from wSurface_t , which is derived from wClickable_t , so graphic objects can respond to single clicks. Note that although the wClickable_t type also handles double clicks, graphic objects don’t send double-click notifications, so if you try to install a double-click handler for one of these objects (which is legal to do), it won’t have any effect. Double-clicks will simply be treated as two single clicks. Because attaching an "onClick" handler to a graphic object is not the common case, you will have to explicitly call the set_onClick method to initialize an onClick handler. The HOWL declarative language doesn’t provide an option to do this for you.

wBitmap_t

The wBitmap_t class lets you create objects that display a bit mapped image on a form.

wBitmap_t:

class inherits( wSurface_t );

var

align( 4 );

wBitmap_private:

record

stretch :boolean;

align( 4 );

imageName :string;

imageHandle :dword;

sourceX :dword;

sourceY :dword;

sourceW :dword;

sourceH :dword;

destW :dword;

destH :dword;

endrecord;

procedure create_wBitmap

(

wiName :string;

imageName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

bkgColor :dword

); external;

method get_imageName; @returns( "eax" ); external;

method get_sourceX; @returns( "eax" ); external;

method get_sourceY; @returns( "eax" ); external;

method get_sourceW; @returns( "eax" ); external;

method get_sourceH; @returns( "eax" ); external;

method get_destW; @returns( "eax" ); external;

method get_destH; @returns( "eax" ); external;

method get_stretch; @returns( "al" ); external;

method load_bitmap( imageName:string ); external;

override method destroy; external;

override method processMessage; external;

method normalBitmap; @returns( "eax" ); external;

method stretchBitmap

(

sourceX :dword;

sourceY :dword;

sourceW :dword;

sourceH :dword;

destW :dword;

destH :dword

); external;

endclass;

imageName This is a string that specifies the name of the bitmap resource within the executable file. Important this is not the name of a ".bmp" file on the disk. You must compile ".bmp" files into your executable using a "resouce compiler". The name you attach to the resource is the name that this string will contain. This is a private field. Applications should not access it directly. Note that if the value of this field is less than $1_0000, then it specifies a standard Windows bitmap resource rather than an actual resource name. See the discussion of the load_bitmap method for more details.

imageHandle,

sourceX,

sourceY,

sourceW,

sourceH,

destW,

destH These are private data fields that applications must not access or modify.

stretch This private field determines whether a bitmap is stretched or displayed normal. This field is set to true by the stretchBitmap method and set to false by the normalBitmap method.

create_wBitmap This is the constructor for the wBitmap_t class. If called as a class procedure (e.g., "wBitMap_t.create_wBitmap") this procedure will allocate storage on the heap for the object and return a pointer to the new (initialized) object in ESI. If you call this constructor specifying an existing object, then it will simply initialize that object in-place.

wiName: this is the string that the HOWL code stores into the _name field. This string’s value should not change over the lifetime of the bitmap object.

imageName: This is either a string containing a bitmap resource name within the executable file, or a standard Windows bitmap resource value. Legal bitmap resource constants are:

w.OBM_BTNCORNERS, OBM_BTSIZE, w.OBM_CHECK, w.OBM_CHECKBOXES, w.OBM_CLOSE, w.OBM_REDUCE, w.OBM_COMBO, w.OBM_REDUCED, w.OBM_DNARROW, w.OBM_RESTORE, w.OBM_DNARROWD, w.OBM_RESTORED, w.OBM_DNARROWI, w.OBM_RGARROW, w.OBM_LFARROW, w.OBM_RGARROWD, w.OBM_LFARROWD, w.OBM_RGARROWI, w.OBM_LFARROWI, w.OBM_SIZE, w.OBM_MNARROW, w.OBM_UPARROW, w.OBM_UPARROWD, w.OBM_UPARROWI, w.OBM_ZOOM, w.OBM_ZOOMD.

See the Windows documentation for more details on these constants.

parent: this is the handle of the form, wView_t , or other drawing surface that contains the wBitmap_t object (and on whose surface the bitmap will be drawn).

x, y, width, height: these arguments specify the bounding box on the parent’s form where the bitmap will be drawn. If this bounding rectangle is larger than the bitmap image (in any dimension), then HOWL will fill the unaccounted-for area wth the background color. If this bounding rectangle is smaller than the image (in any dimension), then HOWL will clip the bitmap when drawing it.

bkgColor: this is the RGB background color that HOWL uses to fill in the bounding rectangle if the bitmap is smaller than the bounding rectangle. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

load_bitmap This method loads the bitmap object with an image resource in the executable file. The argument is a string specifying the resource name or one of the standard Windows bitmap resource constants (see the discussion in create_wBitmap ). Note that this is not a ".bmp" filename. You must compile bitmaps into the executable file using a resource compiler and specify the resource name as the parameter to load_bitmap .

destroy This is the class destructor. This method releases all resources and memory in use by the wBitmap_t object. Usually, applications will not call this method directly. Instead, HOWL will automatically call this destructor when destroying the main application’s wForm_t form or a wView_t object that contains the bitmap.

processMessage This is a private method that applications should never call.

normalBitmap This method sets the stretch field to false to display the bitmap in a normal form.

stretchBitmap This method sets the stretch field to true and copies the parameters to the corresponding private data fields.

sourceX: The stretched bitmap will be copied from the original bit map starting at this zero-based x-coordinate.

sourceY: The stretched bitmap will be copied from the original bit map starting at this zero-based y-coordinate.

sourceW: This many bits along the X axis will be copied to the stretched bitmap.

sourceH: This many bits along the Y axis will be copied to the stretched bitmap.

destW: The bit mapped will be stretched (or shrunk) so that the sourceW bits will be displayed using destW bits.

destH: The bit mapped will be stretched (or shrunk) so that the sourceH bits will be displayed using destH bits.

wEllipse_t

Ellipse graphic objects (of which circles are special cases) allow you to place ellipses anywhere on a form or wView_t object.

wEllipse_t:

class inherits( wFilledFrame_t );

procedure create_wEllipse

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lineColor :dword;

fillColor :dword;

bkgColor :dword

); external;

override method processMessage; external;

endclass;

create_wEllipse This is the consructor for the wEllise_t class. If you call this as a class procedure (e.g., "wEllipse_t.create_wEllipse") then this procedure will allocate storage for a new wEllipse_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wEllipse will initialize that object in-place.

wrName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the ellipse will be drawn.

x, y, width, height: These arguments form a bounding box in which the ellipse will be drawn. If width and height are the same value (meaning the bounding rectangle is a square), then the ellipse will form a circle.

lineColor: this is the RGB color value for the pen that HOWL will use to draw the outline of the ellipse.

fillColor: this is the RGB color value for the brush that HOWL will use to paint the interior of the ellipse.

bkgColor: this is the RGB color value for the brush that HOWL will use to paint the exterior of the ellipse. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

processMessage This is a private method that applications must not call.

wPie_t

The wPie_t graphic object draws a slice of a pie graph on a window. Note that wPie_t is only capable of drawing a single wedge of a pie graph. Note: the procedures and methods in the wPie_t class make use of the FPU on the CPU. You must ensure that the FPU is initialized (i.e., you’re not in MMX mode) before using these functions.

wPie_t:

class inherits( wFilledFrame_t );

var

align( 8 );

wPie_private:

record

startAngle :real64;

endAngle :real64;

endrecord;

procedure create_wPie

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

startAngle :real64;

endAngle :real64;

lineColor :dword;

fillColor :dword;

bkgColor :dword

); external;

override method processMessage; external;

method get_startAngle; @returns( "st0" ); external;

method get_endAngle; @returns( "st0" ); external;

method set_startAngle( startAngle:real64 ); external;

method set_endAngle( endAngle:real64 ); external;

endclass;

startAngle This is the starting angle (measure counter-clockwise from the vertical line) from which wPie_t objects between drawing the wedge. Applications should not access or modify this field directly; they should use the supplied accessor and mutator functions for this purpose. Do not assume the value of this field is degrees or radians.

endAngle This is the ending angle (measured counter-clockwise from the vertical line) to which wPie_t object draw the wedge (from the startAngle to the endAngle in the counter-clockwise direction). Applications should not access or modify this field directly; they should use the supplied accessor and mutator functions for this purpose. Do not assume the value of this field is degrees or radians.

create_wPie This the is the constructor for the wPie_t class. If you call this as a class procedure (e.g., "wPie_t.create_wPie") then this procedure will allocate storage for a new wPie_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wPie will initialize that object in-place.

wrName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the wedge will be drawn.

x, y, width, height: These arguments form a bounding box in which the pie wedge will be drawn.

startAngle: starting angle for the wedge (see the discussion above). This angle is specified in degrees (not radians).

endAngle: ending angle for the wedge (see the discussion above). This angle is specified in degrees, not radians.

lineColor: this is the RGB color value for the pen that HOWL will use to draw the outline of the wedge.

fillColor: this is the RGB color value for the brush that HOWL will use to paint the interior of the wedge.

bkgColor: this is the RGB color value for the brush that HOWL will use to paint the exterior of the wedge.

processMessage This is a private method that applications must not call.

get_startAngle ,

get_endAngle These are accessor functions for the startAngle and endAngle data fields. Note that because these values are real, these functions return their results on the top of the FPU stack. These functions return the angles in degrees.

set_startAngle ,

set_endAngle These are the mutator functions for the startAngle and endAngle data fields. These functions expect the angle in degrees.

wPolygon_t

A polygon is a closed geometric object created by drawing a set of lines between the points in a list (and from the last point to the first point to close the object).

Note: Windows automatically resizes most geographic objects you draw (e.g., rectangles and ellipses). It does not, however, resize a polygon if you change its bounding box. The HOWL polygon class, fortunately, contains extra code to resize a polygon if you change the width or height of the bounding box. Therefore, when using HOWL, your programs can treat polygons just like other geometric objects with respect to the resize method.

ptArray :pointer to w.POINT; // w.POINT:[x:dword, y:dword]

wPolygon_t:

class inherits( wFilledFrame_t );

var

align( 4 );

wPolygon_private:

record

points :ptArray;

scaledPoints :ptArray;

nPoints :uns32;

origW :dword;

origH :dword;

endrecord;

procedure create_wPolygon

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lineColor :dword;

fillColor :dword;

bkgColor :dword

); external;

override method destroy; external;

override method processMessage; external;

override method set_width; external;

override method set_height; external;

override method resize; external;

method set_points

(

nPoints :dword;

points :ptArray

); external;

method get_points; @returns( "eax" ); external;

method get_nPoints; @returns( "eax" ); external;

endclass;

points This is the address of an array of w.POINT objects in memory (each element is 8 bits, a four-byte x-coordinate followed by a four byte y-coordinate value). This is a private data field that applications should not access or modify directly.

scaledPoints This is the address of an array of w.POINT objects in memory (each element is 8 bits, a four-byte x-coordinate followed by a four byte y-coordinate value). The Polygon class uses this array (rather than points) to draw the polygon if the polyon has been resized since it was created. This is a private data field that applications should not access or modify directly.

nPoints This is the number of points in the array pointed at by the points field. If this field is zero, then the points data field may contain an arbitary value. This is a private data field that applications should not access or modify directly.

origW This field holds the original (created) width of the current polygon. The polygon class uses this value to determine if it has to scale the polygon along the x-axis because the polygon has been resized. This is a private data field that applications should not access or modify directly.

origH This field holds the original (created) height of the current polygon. The polygon class uses this value to determine if it has to scale the polygon along the y-axis because the polygon has been resized. This is a private data field that applications should not access or modify directly.

create_wPolygon This the is the constructor for the wPolygon_t class. If you call this as a class procedure (e.g., "wPolygon_t.create_wPolygon") then this procedure will allocate storage for a new wPolygon_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wPolygon will initialize that object in-place. Note that this constructor initializes nPoints to zero (and points to NULL). So immediately upon creation, the polygon has no vertexes and it will not draw anything on the form until you provide a list of points.

wrName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the polygon will be drawn.

x, y, width, height: These arguments form a bounding box in which the polygon will be drawn.

lineColor: this is the RGB color value for the pen that HOWL will use to draw the outline of the polygon.

fillColor: this is the RGB color value for the brush that HOWL will use to paint the interior of the polygon.

bkgColor: this is the RGB color value for the brush that HOWL will use to paint the exterior of the polygon. If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

processMessage This is a private method that applications must not call.

destroy This is the destructor for the wPolygon_t class. Normally, applications do not call this destructor directly; instead, a container will call this destructor automatically when the container is destroyed. However, if you’ve created an independent (of any container) polygon object, you should call this destructor to free the resources it uses when you are done with the polygon.

set_width,

set_height,

resize This are overridden methods from the wFilledFrame_t class. They handle scaling the polygon when you change the size of the polygon’s bounding box. See the descriptions in wFillFrame_t for more details. Note that the these functions will usually make a copy of the points data pointed at by the points field and then set scaledPoints to point at this new data (note, however, that if you reset the size back to the original size, then these functions will deallocate the storage pointed at by the scaledPoints field).

set_points This is the mutator for the points and nPonts data fields.

nPoints: This argument specifies the number of points in the points array passed as the second argument.

points: this is a pointer to an array of nPoints w.POINT elements. The set_points method will make a copy of this data into internally allocated storage (on the heap) and store a pointer to the new data in the points field (this call also frees any storage previously in use by the points and scaledPoints fields).

get_nPoints This accessor returns the number of points in the polygon (the value of the nPoints field).

get_points The get_points accessor function returns the value of the points or scaledPoints field. It returns a pointer to the points field if the current bounding box width and height of the polygon haven’t changed since the last set_points call. This method returns scaledPoints if the polygon has been resized.

wRectangle_t

The wRectangle_t graphic object displays a (clickable) rectangle on a window or form.

wRectangle_t:

class inherits( wFilledFrame_t );

procedure create_wRectangle

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lineColor :dword;

fillColor :dword

); external;

override method processMessage; external;

endclass;

create_wRectangle

This is the consructor for the wRectangle_t class. If you call this as a class procedure (e.g., "wRectangle_t.create_wRectangle") then this procedure will allocate storage for a new wRectangle_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then wRectangle_t will initialize that object in-place.

wrName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the window object on which the ellipse will be drawn.

x, y, width, height: These arguments form a bounding box in which the rectangle will be drawn. If width and height are the same value, then the rectangle will form a square.

lineColor: this is the RGB color value for the pen that HOWL will use to draw the outline of the rectangle.

fillColor: this is the RGB color value for the brush that HOWL will use to paint the interior of the rectangle.

processMessage This is a private method that applications must not call.

wRoundRect_t

wRoundRect_t objects are graphic objects that are rectangles with rounded corners.

wRoundRect_t:

class inherits( wFilledFrame_t );

var

align( 4 );

wRoundRect_private:

record

cornerWidth :dword;

cornerHeight :dword;

endrecord;

procedure create_wRoundRect

(

wrName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

cornerWidth :dword;

cornerHeight :dword;

lineColor :dword;

fillColor :dword;

bkgColor :dword

); external;

method get_cornerWidth; @returns( "eax" ); external;

method get_cornerHeight; @returns( "eax" ); external;

method set_cornerWidth( cornerWidth:dword ); external;

method set_cornerHeight( cornerHeight:dword ); external;

override method processMessage; external;

endclass;

cornerWidth This data field controls the width of the ellipse that Windows draws on each corner of the rounded rectangle. Applications should not access this field directly, they should use the appropriate accessor and mutator functions to access or set the value of this data field. This value should be less than 1/2 the height of the round rectangle object.

cornerHeight This data field controls the height of the ellipse that Windows draws on each corner of the rounded rectangle. Applications should not access this field directly, they should use the appropriate accessor and mutator functions to access or set the value of this data field. This value should be less than 1/2 the height of the round rectangle object.

create_wRoundRect

This is the consructor for the wRoundRect_t class. If you call this as a class procedure (e.g., "wRoundRect_t.create_wRoundRect") then this procedure will allocate storage for a new wRoundRect_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRoundRect will initialize that object in-place.

wrName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the round rectangle will be drawn.

x, y, width, height: These arguments form a bounding box in which the round rectangle will be drawn.

lineColor: this is the RGB color value for the pen that HOWL will use to draw the outline of the round rectangle.

fillColor: this is the RGB color value for the brush that HOWL will use to paint the interior of the round rectangle.

bkgColor: this is the RGB color value for the brush that HOWL will use to paint the exterior of the round rectangle (the area just outside the rounded corners). If the H.O. byte of this color value contains $FF, then HOWL will use the RGB value in the L.O. three bytes to fill the initial object window’s background color but will not redraw the background thereafter (making the object’s background transparent).

get_cornerWidth,

get_cornerHeight These are the accessor functions for the cornerWidth and cornerHeight data fields. Applications should call these methods rather than accessing the data fields directly.

set_cornerWidth,

set_cornerHeight These are the mutator functions for the cornerWidth and cornerHeight data fields. Applications should call these methods rather than writing directly to the data fields.

processMessage This is a private method that applications must not call.

Buttons

The HOWL button widgets come in two basic varieties: checkable (check boxes and radio buttons) and non-checkable (push buttons). All buttons are derived from the wClickable_t class. The constructors for these buttons let you initialize the onClick widgetProc associated with all buttons; you can also call the set_onDblClick method to make a button double-clickable.

wCheckBox_t

wCheckBox_t objects hare a binary state (checked or unchecked). Whenever the user clicks on a checkbox, the widget toggles its state. Note that wCheckBox_t objects inherit the fields of the wCheckable_t class. You can call the get_check and set_check methods of that class to get the current wCheckBox_t object state or to set it.

wCheckBox_t:

class inherits( wCheckable_t );

procedure create_wCheckBox

(

wcbName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wCheckBox

This is the consructor for the wCheckBox_t class. If you call this as a class procedure (e.g., "wCheckBox_t.create_wCheckBox") then this procedure will allocate storage for a new wCheckBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wCheckBox will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn immediately to the right of the check box. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the check box will be drawn.

x, y, width, height: These arguments form a bounding box in which the check box and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the checkbox widget. If this field contains NULL, HOWL will not call any widgetProc procedure.

wCheckBox3_t

wCheckBox3_t checkboxes are similar to standard checkboxes except they have three states: checked, unchecked, and grayed. The get_state method (inherited from wCheckable_t ) will return 0 (unchecked), 1 (checked), or 2 (grayed).

wCheckBox3_t:

class inherits( wCheckable_t );

procedure create_wCheckBox3

(

wcb3Name :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wCheckBox3

This is the consructor for the wCheckBox3_t class. If you call this as a class procedure (e.g., "wCheckBox3_t.create_wCheckBox3") then this procedure will allocate storage for a new wCheckBox3_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wCheckBox3 will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the check box will be drawn.

x, y, width, height: These arguments form a bounding box in which the check box and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the checkbox widget. If this field contains NULL, HOWL will not call any widgetProc procedure.

wCheckBox3LT_t

wCheckBox3LT_t checkboxes are similar to wCheckBox3_t checkboxes except they draw the caption text to the left of the checkbox rather than to the right of it. The get_state method (inherited from wCheckable_t ) will return 0 (unchecked), 1 (checked), or 2 (grayed).

wCheckBox3LT_t:

class inherits( wCheckable_t );

procedure create_wCheckBox3LT

(

wcb3ltName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wCheckBox3LT

This is the consructor for the wCheckBox3LT_t class. If you call this as a class procedure (e.g., "wCheckBox3LT_t.create_wCheckBox3LT") then this procedure will allocate storage for a new wCheckBox3LT_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wCheckBox3LT will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn immediately to the left of the check box. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the check box will be drawn.

x, y, width, height: These arguments form a bounding box in which the check box and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the checkbox widget. If this field contains NULL, HOWL will not call any widgetProc procedure.

wCheckBoxLT_t

wCheckBoxLT_t checkboxes are similar to wCheckBox_t checkboxes except they draw the caption text to the left of the checkbox rather than to the right of it.

wCheckBoxLT_t:

class inherits( wCheckable_t );

procedure create_wCheckBoxLT

(

wcb3ltName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wCheckBoxLT

This is the consructor for the wCheckBoxLT_t class. If you call this as a class procedure (e.g., "wCheckBoxLT_t.create_wCheckBoxLT") then this procedure will allocate storage for a new wCheckBoxLT_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wCheckBoxLT will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the check box will be drawn.

x, y, width, height: These arguments form a bounding box in which the check box and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the checkbox widget. If this field contains NULL, HOWL will not call any widgetProc procedure.

wPushButton_t

wPushButton_t objects are standard Windows push button widgets. They almost always invoke some sort of "onClick" widgetProc procedure when the button is pressed.

wPushButton_t:

class inherits( wButton_t );

procedure create_wPushButton

(

wpbName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wPushButton

This is the consructor for the wPushButton_t class. If you call this as a class procedure (e.g., "wPushButton_t.create_wPushButton") then this procedure will allocate storage for a new wPushButton_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wPushButton will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn on the push button. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the push button will be drawn.

x, y, width, height: These arguments form a bounding box in which the push button and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the push button widget. If this field contains NULL, HOWL will not call any widgetProc procedure.

wRadioButton_t

wRadioButton_t objects are stand-alone radio buttons on a form. You’ll rarely use these objects because radio buttons are generally employed in sets (using a wRadioSet_t container and wRadioSetButton_t objects). A stand-alone radio button is essentially a check box with a circle and a dot rather than a square and an "x". The main purpose for wRadioButton_t objects (and wRadioButtonLT_t objects) is for programmers who want to manually control the operation of the radio buttons.

wRadioButton_t:

class inherits( wCheckable_t );

procedure create_wRadioButton

(

wrbName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wRadioButton

This is the consructor for the wRadioButton_t class. If you call this as a class procedure (e.g., "wRadioButton_t.create_wRadioButton") then this procedure will allocate storage for a new wRadioButton_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRadioButton will initialize that object in-place.

wrbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn to the right of the radio button. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the radio button will be drawn.

x, y, width, height: These arguments form a bounding box in which the radio button and caption will be drawn.

wRadioButtonLT_t

wRadioButton_LT objects are just like wRadioButton_t objects except the text appears to the left of the radio button rather than to the right.

wRadioButtonLT_t:

class inherits( wCheckable_t );

procedure create_wRadioButtonLT

(

wrbltName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wRadioButtonLT

This is the consructor for the wRadioButton_t class. If you call this as a class procedure (e.g., "wRadioButtonLT_t.create_wRadioButtonLT") then this procedure will allocate storage for a new wRadioButtonLT_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRadioButtonLT will initialize that object in-place.

wrbltName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn to the left of the radio button. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the radio button will be drawn.

x, y, width, height: These arguments form a bounding box in which the radio button and caption will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever you click on the radio button widget. If this field contains NULL, HOWL will not call any widgetProc procedure. Generally, if you’re using wRadioButtonLT_t objects in your application, it is the responsibility of the onClick procedure to properly update the other radio buttons associated with the one the user has just clicked on. Note that the wRadioSet..endwRadioSet statement in the HOWL declarative language will report an error if you attempt to add some non-radio-set-button widget to the wRadioSet_t object you’re creating.

wRadioSet_t

A wRadioSet_t object is a container that holds (only) wRadioSetButton_t and wRadioSetButtonLT_t objects. The wRadioSet_t object automatically maintains all the buttons it contains, ensuring that (at most) one button is checked at a time. Note that an application must only insert groups of wRadioSetButton_t and wRadioSetButtonLT_t objects into the widget list of a wRadioSet_t object. If an application (manually) inserts other objects into a wRadioSet_t widget list, the radio buttons may not behave properly. Visually, a wRadioSet_t object is identical to a wGroupBox_t object. That is, it is a rectangular panel with a caption in the upper-left-hand corner of the rectangle.

wRadioSet_t:

class inherits( wContainer_t );

var

align( 4 );

wRadioSet_private:

record

// Windows handle for the group box window

groupBoxHndl :dword;

endrecord;

procedure create_wRadioSet

(

wrsName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

bkgColor :dword

); external;

override method processMessage; external;

override method destroy; external;

override method set_width; external;

override method set_height; external;

override method resize; external;

endclass;

groupBoxHndl This is the handle for the actual group box (a separate surface for the background is use to fill in the area behind the group box). This is a private field. Applications should not access it.

create_wRadioSet This is the constructor for the wRadioSet_t class. If you call this as a class procedure (e.g., "wRadioSet_t.create_wRadioSet") then this procedure will allocate storage for a new wRadioSet_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRadioSet will initialize that object in-place.

wrsName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: this is the caption text that will be drawn in the upper-left-hand corner of the wRadioSet_t’s panel rectangle. Windows makes an internal copy of this string, so the value need only exist for as long as the constructor call is in progress.

parent: this is the handle of the wView_t or wForm_t object on which the radio set group box will be drawn.

x, y, width, height: These arguments form a bounding box in which the radio button and caption will be drawn.

processMessage This is a private method. Applications must not call it.

destroy This is the class constructor. Usually, a container object will call this destructor automatically for you; applications don’t normally call this destructor unless they create a wRadioSet_t object and don’t insert it into some container’s widget list.

set_width,

set_height,

resize These fields are overriden from the wVisual_t class. See the description there for more details.

You will want to call the insertWidget method (inherited from wContainer_t ) in order to add wRadioSetButton_t or wRadioSetButtonLT_t objects to a wRadioSet_t object.

wRadioSetButton_t

A wRadioSetButton_t is a standard radio set button that appears within a wRadioSet_t group box. wRadioSetButton_t objects are identical to wRadioButton_t objects except that they support automatic radio button control on a wRadioSet_t group box. You can actually specify wRadioSetButton_t objects outside of a wRadioSet_t group box; however, HOWL will only maintain automatic radio button operation on those buttons you declare (in the HOWL declarative language) in a sequence without any other intervening widget types (except wRadioSetButtonLT_t objects, which can be intermixed with wRadioSetButton_t objects).

wRadioSetButton_t:

class inherits( wCheckable_t );

procedure create_wRadioSetButton

(

wrbName :string;

caption :string;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wRadioSetButton

This is the consructor for the wRadioSetButton_t class. If you call this as a class procedure (e.g., "wRadioSetButton_t.create_wRadioSetButton") then this procedure will allocate storage for a new wRadioSetButton_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRadioSetButton will initialize that object in-place.

wrbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the radio button will be drawn.

x, y, width, height: These arguments form a bounding box in which the radio button and caption will be drawn.

wRadioSetButtonLT_t

A wRadioSetButtonLT_t is identical to a wRadioSetButton_t object except it draws the caption text to the left of the button rather than to the right of the button.

wRadioSetButtonLT_t:

class inherits( wCheckable_t );

procedure create_wRadioSetButtonLT

(

wrbltName :string;

caption :string;

style :dword;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

endclass;

create_wRadioSetButtonLT

This is the consructor for the wRadioSetButtonLT_t class. If you call this as a class procedure (e.g., "wRadioSetButtonLT_t.create_wRadioSetButtonLT") then this procedure will allocate storage for a new wRadioSetButton_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wRadioSetButtonLT will initialize that object in-place.

wrbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the radio button will be drawn.

x, y, width, height: These arguments form a bounding box in which the radio button and caption will be drawn.

Editors and Edit Boxes

The HOWL edit widgets allow users to enter passwords, single lines of text, or text documents (up to 32KB long). Users can cut and paste data between edit widgets and perform many other text-editing functions. Applications can select text from an edit widget, insert text into the widget, or extract text from the widget. Indeed, with just a little extra code, it’s quite possible to create a fully-featured text editor using the HOWL edit widgets.

Perhaps the biggest limitation to these widgets is their 32K text limitation. A future version of HOWL will include an extended text editor that overcomes this limitation.

All of the HOWL edit widgets are subclasses of the wabsEditBox_t class and, therefore, inherit all the fields and methods from that abstract base class. You should take a moment to review that abstract base class before looking at the following derived class definitions.

wEditBox_t

A wEditBox_t object allows a user to enter a single string (a single line of text) from the keyboard.

wEditBox_t:

class inherits( wabsEditBox_t );

procedure create_wEditBox

(

webName :string;

initialTxt :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

endclass;

create_wEditBox This is the consructor for the wEditBox_t class. If you call this as a class procedure (e.g., "wEditBox_t.create_wEditBox") then this procedure will allocate storage for a new wEditBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wEditBox will initialize that object in-place.

webName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

initialTxt: HOWL will initialize the edit box’s text entry field with this string. This is commonly an empty string in most objects.

parent: this is the handle of the wView_t or wForm_t object on which the edit box will be drawn.

x, y, width, height: These arguments form a bounding box in which the edit box will be drawn.

style: This argument is zero or more of the Windows edit box styles logically OR’d together (or zero, to use the default edit box style). See the discussion of Windows edit box styles in the section on the wEditBox object earlier in this document (in the HOWL declaration language description).

onChange: this is the name of a widgetProc that HOWL will call whenever you change any text in the edit box widget. If this field contains NULL, HOWL will not call any widgetProc procedure. Generally, this field will contain NULL and you will process the text in an edit box in response to some other system event (such as a button press or loss of focus).

wPasswdBox_t

A wPasswdBox_t object is almost identical to a wEditBox_t object. The difference is that Windows substitutes asterisks (or some other user-defined character) for the characters the user types at the keyboard to protect passwords from prying eyes.

wPasswdBox_t:

class inherits( wabsEditBox_t );

procedure create_wPasswdBox

(

wpwbName :string;

initialTxt :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

method get_passwordChar; @returns( "eax" ); external;

method set_passwordChar( pwc:char ); external;

endclass;

create_wPasswdBox

This is the consructor for the wPasswdBox_t class. If you call this as a class procedure (e.g., "wPasswdBox_t.create_wPasswdBox") then this procedure will allocate storage for a new wPasswdBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wPasswdBox will initialize that object in-place.

webName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

initialTxt: HOWL will initialize the password box’s text entry field with this string. This is commonly an empty string in most objects.

parent: this is the handle of the wView_t or wForm_t object on which the password box will be drawn.

x, y, width, height: These arguments form a bounding box in which the password box will be drawn.

onChange: this is the name of a widgetProc that HOWL will call whenever you change any text in the password box widget. If this field contains NULL, HOWL will not call any widgetProc procedure. Generally, this field will contain NULL and you will process the text in a password box in response to some other system event (such as a button press or loss of focus).

wTextEdit_t

A wTextEdit_t object allows the user to enter multiple lines of text in a text editor format. If the text editor string data contains more lines (or more characters on a given line) than will fit in the text editor window, Windows will automatically attach scroll bars to the window so the user can scroll through the text data.

wTextEdit_t:

class inherits( wabsEditBox_t );

procedure create_wTextEdit

(

wteName :string;

initialTxt :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

method getLineCount; @returns( "eax" ); external;

method getLineIndex( charIndex:dword );

@returns( "eax" ); external;

method getCharIndex( lineIndex:dword );

@returns( "eax" ); external;

method getLine( lineIndex:dword; txt:string ); external;

method a_getLine( lineIndex:dword );

@returns( "eax" ); external;

method scroll( horz:int32; vert:int32 ); external;

method scrollCaret; external;

method setTabStops( tabstops:dword ); external;

endclass;

create_wTextEdit

This is the consructor for the wTextEdit_t class. If you call this as a class procedure (e.g., "wTextEdit_t.create_wTextEdit") then this procedure will allocate storage for a new wTextEdit_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wTextEdit will initialize that object in-place.

webName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

initialTxt: HOWL will initialize the text editor’s text entry field with this string. This is commonly an empty string in most objects.

parent: this is the handle of the wView_t or wForm_t object on which the text editor will be drawn.

x, y, width, height: These arguments form a bounding box in which the text editor will be drawn.

onChange: this is the name of a widgetProc that HOWL will call whenever you change any text in the text editor widget. If this field contains NULL, HOWL will not call any widgetProc procedure. Generally, this field will contain NULL and you will process the text in a text editor widget in response to some other system event (such as a button press or loss of focus).

get_lineCount This method returns the number of lines of text in the text editor widget.

get_lineIndex Given a zero-based character index into the text editor’s string (up to 32K), this function will return a zero-based line number for that index (that is, the line number of the line that contains that particular character).

get_charIndex Given a (zero-based) line number into the text editor’s data string, this function returns the (zero-based) character index (into the text editor’s string data) of the first character on that line.

get_line Given a line index into the text editor’s data string, this function returns the specified string.

lineIndex This is the zero-based line index into the text editor’s data string.

txt: this is a string object wher get_line will copy the string data for the specified line. This string must be previously allocated and have sufficient storage to hold the string or HOWL will raise an exception.

a_get_line Given a line index, this method makes a copy of the specified text editor line on the heap and returns a pointer to this string in the EAX register. It is the caller’s responsibility to free the storage associated with this string with the application is done using it.

scroll This function will scroll the text editor window the number of characters specified by the two arguments in the horizontal and vertical directions.

horz: this is the number of characters to scroll in the horizontal direction.

vert: this is the number of characters to scroll in the vertical direction. Windows will not let you scroll beyond the last line in the text editor’s string; if you attempt to do so, Windows will simply display the last line of text at the top of the editor’s window.

scrollCaret Positions the text display window so that the text containing the insertion caret is visible on the screen.

setTabStops This function sets tabstops every ’tabstops’ characters, where ’tabstops’ is the argument you pass to this method.

List, Drag, and Combo Boxes

List and drag boxes are tables of data from which the user can select an item (a row) by clicking on the line of text associated with that item. Applications can add, delete, or rearrange lines of text in list and drag boxes. End users can rearrange data in a drag box with no interaction from the application.

wListBox_t

A wListBox_t object is a table of strings created by the application. The user can click or double-click on these strings. The application can insert and delete strings in the list box. If there are too many strings to display in the window, then Windows will attach a vertical scroll bar to the list box and allow the user to scroll through the list box entry.

A list box will either display the strings in the order the application inserts them into the list box, or it can display them in a sorted order. You specify whether you want a sorted or unsorted list box when you create it.

wListBox_t:

class inherits ( wClickable_t );

var

align( 4 );

wListBox_private:

record

textColor :dword;

endrecord;

procedure create_wListBox

(

wlbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

sort :boolean;

onClick :widgetProc

); external;

method add_string( s:string ); external;

method insert_string( index:dword; s:string ); external;

method delete_string( index:dword ); external;

method reset; external;

method find_prefix

(

s :string;

startIndex :dword

); @returns( "eax" ); external;

method find_string

(

s :string;

startIndex :dword

); @returns( "eax" ); external;

method get_count; @returns( "eax" ); external;

method get_curSel; @returns( "eax" ); external;

method get_itemData( i:dword ); @returns( "eax" ); external;

method a_get_text( i:dword ); @returns( "eax" ); external;

method get_text( i:dword; s:string ); external;

method set_curSel(index:dword); @returns( "eax" ); external;

method set_itemData

(

index :dword;

data :dword

); external;

method load_dir

(

pathname :string;

attributes :dword

); external;

method get_textColor; @returns( "eax" ); external;

method set_textColor( textColor:dword ); external;

override method processMessage; external;

endclass;

textColor This is the RGB color that Windows will use to draw the text on the listbox. This is a private data field; applications should only access this value using the associated access and mutator. The constructor initializes the text color to black.

create_wListBox

This is the consructor for the wListBox_t class. If you call this as a class procedure (e.g., "wListBox_t.create_wListBox") then this procedure will allocate storage for a new wListBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wListBox will initialize that object in-place.

wlbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the list box will be drawn.

x, y, width, height: These arguments form a bounding box in which the list box will be drawn.

sort: if this field is true, then the constructor will create a sorted list box. If this value is false, then the constructor will create an unsorted list box.

onClick: this is the name of a widgetProc that HOWL will call whenever select a (new) line in a list box.

add_string This method appends a string (specified as the argument) to the end of an unsorted list box. It will insert the string at the proper position within a sorted list box. Note that Windows will make an internal copy of the string’s data.

insert_string This method inserts a string before some other entry in the list box. This method ignores the sorted/unsorted state of the list box and always inserts the string at the specified index. The index must be in the range 0..count where count is the number of entries in the list box. If you specify the value count as the index, then this method appends the item to the end of the list (similar to add_string , except no sorting).

index: the line number before which the string is to be inserted. This is a zero-based index.

s: this is the string data to insert into the list box.

delete_string This method deletes the string at the specified index in the list box.

reset This method deletes all the strings in the list box.

find_prefix This method searches for a line of text in the list box that begins with some string. This method begins searching starting with an application-defined line index into the list box. This method returns the index into the list box where the string prefix was found, or the constant w.LB_ERR if it could find no string with the specified prefix.

s: the string prefix to search for in the list box.

startIndex: the starting line index to begin the search.

find_string This method searches for a line of text in the list box that matches some string. This method begins searching starting with an application-defined line index into the list box. This method returns the index into the list box where the string was found, or the constant w.LB_ERR if it could not find the string.

s: the string to search for in the list box.

startIndex: the starting line index to begin the search.

get_count This method returns the number of lines in the list box (in EAX).

get_curSel This method returns the index of the currently selected item in the list box (in EAX).

get_itemData Each line of text in a list box has a 32-bit user-defined data value associated with it. You could, for example store a pointer to some object or other data type in this field and retrieve it when the user selects an item in the list box. The get_itemData method retrieves this user data from the list box. The single argument is the index of the list box entry for which you want the user data (you would typically supply the data returned by get_curSel as this argument).

a_get_text This method makes a copy of the string data (on the heap) for the line in the list box at the index specified by the argument. It returns a pointer to this new string in EAX. It is the caller’s responsibility to free the storage for this string when the caller is done with it.

get_text This method makes a copy of the string data for the line in the list box at a user-supplied index. It stores the string data into a string object whose address the caller passes as an argument. That string must have sufficient storage allocated for it or HOWL will raise an exception.

i: index of the line in the list box whose string data this method will extract.

s: pointer to a string object where this method will store the result.

set_curSel This methods highlights the line at the specified index in the list box (it becomes the "currently selected" item).

set_itemData This method allows you to associate a user-defined 32-bit data value with an item in the list box. If 32 bits is insufficient for your needs, you can always store a pointer to the actual data in this data area.

index: this is the (zero-based) index of the line in the list box that you want to attach the data to.

data: this is the 32-bit value you want to associate with the line in the list box.

load_dir This method populates the list box with the file names from the directory specified by the pathname argument.

pathname: an ambiguous pathname (e.g., "c:\*.*" that specifies the path to the files and the files at that path tha t you want to load into the list box.

attributes: either zero, or the logical OR of one or more of the following Windows’ attribute constants:

w.DDL_ARCHIVE Includes archived files.

w.DDL_DIRECTORY Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).

w.DDL_DRIVES Includes drives. Drives are listed in the form [-x-], where x is the drive letter.

w.DDL_EXCLUSIVE Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.

w.DDL_HIDDEN Includes hidden files.

w .DDL_READONLY Includes read-only files.

w.DDL_READWRITE Includes read-write files with no additional attributes.

w.DDL_SYSTEM Includes system files.

get_textColor,

set_textColor These accessor/mutator functions get and set the text color that the widget uses.

processMessage This is a private method. Applications must not call it.

wDragListBox_t

A wDragListBox_t object is a special kind of list box that allows the user to rearrange the items in the list box without any interaction from the application. An application uses drag list boxes exactly like list boxes (except, of course, for the object’s type name). As the wDragListBox_t class is derived from wListBox_t , all of the list box methods are available to wDragListBox_t objects. Note that HOWL does not offer drag list boxes the "sort" option, which makes little sense as the end user will probably rearrange their drag list boxes thus defeating the purpose of the sort option.

wDragListBox_t:

class inherits ( wListBox_t );

var

align( 4 );

wDragListBox_private:

record

// The following is a private field.

// External code should not access it.

startDragIndex :dword;

endrecord;

procedure create_wDragListBox

(

wlbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

onClick :widgetProc

); external;

override method processMessage; external;

endclass;

create_wDragListBox

This is the consructor for the wDragListBox_t class. If you call this as a class procedure (e.g., "wDragListBox_t.create_wDragListBox") then this procedure will allocate storage for a new wDragListBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wDragListBox will initialize that object in-place.

wlbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the drag list box will be drawn.

x, y, width, height: These arguments form a bounding box in which the drag list box will be drawn.

onClick: this is the name of a widgetProc that HOWL will call whenever the user selects a (new) line in a drag list box.

wComboBox_t

The wComboBox_t object is a combination of an edit box, a list box, and a pull-down menu. The user can type text directly into a list box or click on a button attached to the combo box and select an item from a list box that appears in a pull-down menu.

wComboBox_t:

class inherits ( wListBox_t );

var

align( 4 );

wComboBox_private:

record

onEditChange :widgetProc;

onCancel :widgetProc;

onSelEndOk :widgetProc;

endrecord;

procedure create_wComboBox

(

wcbName :string;

caption :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

sort :boolean;

onSelChange :widgetProc

); external;

method get_onEditChange; @returns( "eax" ); external;

method get_onCancel; @returns( "eax" ); external;

method get_SelEndOk; @returns( "eax" ); external;

method set_onEditChange( onEditChange:widgetProc ); external;

method set_onCancel( onCancel:widgetProc ); external;

method set_SelEndOk( onSelEndOk:widgetProc ); external;

method a_get_editBoxText; @returns( "eax" ); external;

method get_editBoxText( theText:string ); external;

method set_editBoxText( theText:string ); external;

override method load_dir; external;

override method processMessage; external;

override method add_string; external;

override method insert_string; external;

override method delete_string; external;

override method reset; external;

override method find_prefix; external;

override method find_string; external;

override method get_count; external;

override method get_curSel; external;

override method get_itemData; external;

override method a_get_text; external;

override method get_text; external;

override method set_curSel; external;

override method set_itemData; external;

endclass;

onEditChange This is a pointer to a widgetProc that HOWL will call whenever the user makes a change to the edit box component of a combo box. If this field is NULL, HOWL will ignore it. Note that applications should only access or modify this field using the associated accessor/mutator methods.

onCancel This is a pointer to a widgetProc that HOWL will call whenever the user cancels a change to the edit box component of a combo box. If this field is NULL, HOWL will ignore it. Note that applications should only access or modify this field using the associated accessor/mutator methods.

onSelEndOk This is a pointer to a widgetProc that HOWL will call whenever the user selects and item from the pull-down list box and the application should select that entry. If this field is NULL, HOWL will ignore it. Note that applications should only access or modify this field using the associated accessor/mutator methods.

create_wComboBox

This is the consructor for the wComboBox_t class. If you call this as a class procedure (e.g., "wComboBox_t.create_wComboBox") then this procedure will allocate storage for a new wComboBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wComboBox will initialize that object in-place.

wcbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

caption: This is the initial string data for the combo box’s edit box field.

parent: this is the handle of the wView_t or wForm_t object on which the combo box will be drawn.

x, y, width, height: These arguments form a bounding box in which the combo box will be drawn.

sort: like list boxes, combo boxes offer the option of sorting the list for you. If this field is true, HOWL will create a sorted list in the combo box; if this field is false, the list in the combo box will be unsorted.

onSelChange: this is the name of a widgetProc that HOWL will call whenever the user selects a (new) line in the list of a combo box.

get_onEditChange,

get_onCancel,

get_onSelEndOk These are the accessor functions for the combo box’s data fields.

set_onEditChange,

set_onCancel,

set_onSelEndOk These are the mutator functions for the combo box’s data fields.

a_get_editBox_text This method returns a copy of the string data currently held in the combo box’s edit box component. HOWL allocates storage for this string and returns a pointer to the new string in the EAX register. It is the caller’s responsibility to free the storage for this string.

get_editBox_text This method retrieves the string from the combo box and stores the string data in the string object passed as a parameter. The destination string must have sufficient storage or HOWL will raise an exception.

set_editBox_text This function replaces the combo box’s string data with the string passed as an argument.

The remaining methods listed in the wComboBox_t declaration above are overriden methods from the wListBox_t class. The overriding occurs for internal technical reasons. To an application, these methods are used exactly like those in a list box. Please see the discussion in the list box section for more details on the operation of these methods.

Progress Bars

A progress bar is a bar graph that shows the progress of some lengthy operation during the execution of an application.

wProgressBar_t

The wProgressBar_t type implements Windows progress bars in HOWL. A progress bar has three main attributes: a current position (the current "progress"), a minimum position, and a maximum position. When drawing a progress bar, Windows will create a horizontal bar graph and will fill the bar graph from the left to the right based on the current position, minimum, and maximum values.

wProgressBar_t:

class inherits( wVisual_t );

var

align( 4 );

wProgressBar_private:

record

position :word;

align( 4 );

lowRange :word;

hiRange :word;

endrecord;

procedure create_wProgressBar

(

wpbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword

); external;

method get_position; @returns( "eax" ); external;

method set_position( position:word ); external;

method get_lowRange; @returns( "eax" ); external;

method get_hiRange; @returns( "eax" ); external;

method set_range( low:word; high:word ); external;

endclass;

position These data field is the current position of the track bar. Applications should never access this field directly. Instead, they should use the accessor/mutator methods to read or write this field’s data.

lowRange This is the minimum value for the progress bar’s position. It is usually zero, but you can set any minimum value you like as long as it is less than the value held in the hiRange data field. You should never set the value of the position data field to a value lower than the lowRange value. Applications should never access this field directly. Instead, they should use the accessor/mutator methods to read or write this field’s data.

hiRange This is the maximum value for the progress bar’s position. You can set any maximum value you like as long as it is greater than the value held in the lowRange data field. You should never set the value of the position data field to a value higher than the hiRange value. Applications should never access this field directly. Instead, they should use the accessor/mutator methods to read or write this field’s data.

create_wProgressBar

This is the consructor for the wProgressBar_t class. If you call this as a class procedure (e.g., "wProgressBar_t.create_wProgressBar") then this procedure will allocate storage for a new wProgressBar_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wProgressBar will initialize that object in-place.

wpbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the progress bar will be drawn.

x, y, width, height: These arguments form a bounding box in which the progress bar will be drawn.

get_position,

get_lowRange,

get_hiRange These are the accessor methods for the class’ data fields.

set_position,

set_lowRange,

set_hiRange These are the mutator functions for the class’ data fields. Note that changing any of these values (and in particular, changing the position value) will cause Windows to redraw the progress bar reflecting the new values.

Scroll Bars and Track Bars

Scroll bars and track bars are positional input devices. Applications generally use scroll bars to specify a position to view on a form (when the form’s contents are too large to fit in the window and one time) whereas a trackbar provides a generic numeric input device selectable by the position of the slider on the trackbar. Both widgets are available in horizontal and vertical orientations.

Note that Windows can automatically associate horizontal and vertical scroll bars with a window when you create that window. For window scrolling purposes, this is generally how you create and use scroll bars. However, you can create stand-alone scroll bars for use by your applications using the scrollbar widget.

wScrollBar_t

The wScrollBar_t class lets you create stand-alone scroll bars in your application. Scroll bars offer a large number of event notifications that tell you about various user interactions with the scroll bar.

Scroll bars in early versions of Windows were limited to 16-bit range and position values. For the most part, later versions of Windows extended all these values to 32 bits. However, one important pair of values, returned when tracking movements on scroll bars, is still limited to 16-bit values. Therefore, if you plan to make full use of the scroll bar’s feature set and notifications, you need to limit yourself to using 16-bit ranges and positions. In general, this is not a severe limitations because there aren’t enough pixels on the screen to provide a granularit of 16 bits, much less 32. However, just note that although you can set the low and high range values for a scroll bar to arbitrary 32-bit values, you should limit yourself to 16-bit values.

wScrollBar_t:

class inherits( wVisual_t );

var

align( 4 );

wScrollBar_private:

record

onChange :widgetProc;

onThumbPosn :widgetProc;

onThumbTrack :widgetProc;

onLineLeft :widgetProc;

onLineRight :widgetProc;

onLineDown :widgetProc;

onLineUp :widgetProc;

onEndScroll :widgetProc;

onPageDown :widgetProc;

onPageUp :widgetProc;

onPageLeft :widgetProc;

onPageRight :widgetProc;

onTop :widgetProc;

onBottom :widgetProc;

lineInc :uns32;

pageInc :uns32;

curPosn :dword;

info :w.SCROLLINFO;

textColor :dword;

endrecord;

procedure create_wScrollBar

(

wtbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

override method enable; external;

override method disable; external;

override method show; external;

override method hide; external;

method get_position; @returns( "eax" ); external;

method set_position( position:dword ); external;

method get_lowRange; @returns( "eax" ); external;

method get_hiRange; @returns( "eax" ); external;

method set_range( low:dword; high:dword ); external;

method get_onChange; @returns( "eax" ); external;

method get_onThumbPosn; @returns( "eax" ); external;

method get_onThumbTrack; @returns( "eax" ); external;

method get_onLineDown; @returns( "eax" ); external;

method get_onLineUp; @returns( "eax" ); external;

method get_onLineLeft; @returns( "eax" ); external;

method get_onLineRight; @returns( "eax" ); external;

method get_onEndScroll; @returns( "eax" ); external;

method get_onPageDown; @returns( "eax" ); external;

method get_onPageUp; @returns( "eax" ); external;

method get_onPageLeft; @returns( "eax" ); external;

method get_onPageRight; @returns( "eax" ); external;

method get_onTop; @returns( "eax" ); external;

method get_onBottom; @returns( "eax" ); external;

method get_lineInc; @returns( "eax" ); external;

method get_pageInc; @returns( "eax" ); external;

method set_onChange( onChange:widgetProc ); external;

method set_onThumbPosn( onThumbPosn:widgetProc ); external;

method set_onThumbTrack( onThumbTrack:widgetProc ); external;

method set_onLineDown( onLineDown:widgetProc ); external;

method set_onLineUp( onLineUp:widgetProc ); external;

method set_onLineLeft( onLineLeft:widgetProc ); external;

method set_onLineRight( onLineRight:widgetProc ); external;

method set_onEndScroll( onEndScroll:widgetProc ); external;

method set_onPageDown( onPageDown:widgetProc ); external;

method set_onPageUp( onPageUp:widgetProc ); external;

method set_onPageLeft( onPageLeft:widgetProc ); external;

method set_onPageRight( onPageRight:widgetProc ); external;

method set_onTop( onTop:widgetProc ); external;

method set_onBottom( onBottom:widgetProc ); external;

method set_lineInc( lineInc:dword ); external;

method set_pageInc( pageInc:dword ); external;

method get_textColor; @returns( "eax" ); external;

method set_textColor( textColor:dword ); external;

override method processMessage; external;

endclass;

onChange This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on the scroll bar (using any means to change the value). Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onThumbPosn This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on the scroll bar by dragging the thumb. HOWL calls this procedure after the user has released the mouse button while dragging the thumb control. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onThumbTrack This field, if non-NULL, points at a widgetProc procedure that HOWL will call while the user is dragging the thumb around the scroll bar. An application can use this notification to dynamically adjust the screen during thumb movement. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position. Note that this is the only notification that provides only a 16-bit value for the thumb position; if you don’t need to use this notification, it is possible to obtain 32-bit values for the thumb position (from the other notification calls).

onLineLeft This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a horizontal scroll bar by pressing the left arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onLineRight This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a horizontal scroll bar by pressing the right arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onLineDown This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a vertical scroll bar by pressing the down arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onLineUp This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a vertical scroll bar by pressing the up arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onEndScroll This field, if non-NULL, points at a widgetProc procedure that HOWL will call after any scroll operation is complete. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onPageDown This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a vertical scroll bar by clicking on the scroll bar between the thumb and the down arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onPageUp This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a vertical scroll bar by clicking on the scroll bar between the thumb and the up arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onPageLeft This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a horizontal scroll bar by clicking on the scroll bar between the thumb and the left arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onPageRight This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the thumb on a horizontal scroll bar by clicking on the scroll bar between the thumb and the right arrow on the scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onTop This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user moves the thumb all the way to the top on a vertical scroll bar or all the way to the left on a horizontal scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position (which should be the maximum value).

onBottom This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user moves the thumb all the way to the bottom on a vertical scroll bar or all the way to the right on a horizontal scroll bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position (which should be the maximum value).

lineInc This data field contains the number of positions that will be added to or subtracted from the scroll bar thumb’s current position when the user clicks on one of the scroll bar’s arrow buttons. Applications should not access this data field directly, they should use the standard class accessor/mutator functions to read and write this value.

pageInc This data field contains the number of positions that will be added to or subtracted from the scroll bar thumb’s current position when the user clicks on the scroll bar between the thumb and one of the arrow buttons. Applications should not access this data field directly, they should use the standard class accessor/mutator functions to read and write this value.

curPosn This is a private field used by the class. Applications should not access it.

info This is a private field used by the class. Applications should not access it.

textColor This is the RGB color that Windows will use to draw the text on the scrollbar. This is a private data field; applications should only access this value using the associated access and mutator. The constructor initializes the text color to black.

bkgColor This is the RGB color that Windows will use to paint the background of the scrollbar. This is a private data field; applications should only access this value using the associated access and mutator. The constructor initializes the backgroun color to white.

bkgBrush This is a private data field; applications should never access it.

create_wScrollBar

This is the consructor for the wScrollBar_t class. If you call this as a class procedure (e.g., "wScrollBar_t.create_wScrollBar") then this procedure will allocate storage for a new wScrollBar_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wScrollBar will initialize that object in-place.

wtbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the scroll bar will be drawn.

x, y, width, height: These arguments form a bounding box in which the scroll bar will be drawn.

style: HOWL logically ORs this value with the Windows styles (w.WS_CHILD | w.WS_VISIBLE) when creating the scroll bar. At the very least, this field should contain w.SBS_HORZ for a horizontal scroll bar or w.SBS_VERT for a vertical scroll bar. Please see the Windows documentation or the HLA w.hhf header file for additional scroll bar style ( SBS_*) constants.

onChange: this is the address (which can be NULL) of an onChange widgetProc procedure. The constructor will initialize the onChange field with this value.

enable,

disable These two methods will enable or disable the scroll bar on the form. A disabled scroll bar is still visible, but the user will be unable to interact with it.

show,

hide These two methos will make a scroll bar visible or invisible on the form.

get_position This function returns the current scroll bar position as a 32-bit value in the EAX register. Note that you can call this method from any of the event notification procedures except onThumbTrack to obtain the true 32-bit position of the thumb control (rather than limiting yourself to the upper 16 bits of the wParam parameter). If you call this method from the onThumbTrack notification procedure, it will not return the current position of the thumb, instead it will return the last position before the user started dragging the thumb around. Sadly, there is no way to obtain a 32-bit current thumb position while dragging the thumb.

set_position This method sets the current thumb position on the scroll bar. The argument you pass to this method must be between the low and high range values for the scroll bar.

get_lowRange This method returns (in EAX) the current lower range for the scroll bar. This is typically zero, but you can program any 32-bit value you desire (see set_range ).

get_hiRange This method returns (in EAX) the current upper range for the scroll bar.

set_range This method lets you set the low and high range values for the scroll bar. The default range is 0..100, but you can set any 32-bit values you like. Note that if you intend to use the onThumbTrack notification, you should limit the range to 16-bit values.

low: the lower bound of the scroll bar range

high: the upper bound of the scroll bar range.

get_onChange,

get_onThumbPosn,

get_onThumbTrack,

get_onLineDown,

get_onLineUp,

get_onLineLeft,

get_onLineRight,

get_onEndScroll,

get_onPageDown,

get_onPageUp,

get_onPageLeft,

get_onPageRight,

get_onTop,

get_onBottom These are the accessor methods for the corresponding widgetProc pointer data fields in this class.

get_lineInc,

get_pageInc These are the accessor methods for the corresponding data fields in the class. Applications should always use these accessor methods to read the values of the lineInc and pageInc fields.

set_onChange,

set_onThumbPosn,

set_onThumbTrack,

set_onLineDown,

set_onLineUp,

set_onLineLeft,

set_onLineRight,

set_onEndScroll,

set_onPageDown,

set_onPageUp,

set_onPageLeft,

set_onPageRight,

set_onTop,

set_onBottom These are the mutator functions for all the widgetProc pointer fields in the class.

set_lineInc,

set_pageInc These are the mutator methods for the corresponding data fields in the class. Applications should always use these accessor methods to write the values of the lineInc and pageInc fields.

get_textColor,

set_textColor,

get_bkgColor,

set_bkgColor These accessor/mutator functions get and set the text and background colors that the widget uses.

processMessage This is a private method in the class. Applications must not call this method.

wTrackBar_t

wTrackBar_t objects are very similar in use to a scroll bar insofar as they provide a slider control that the user can move between two extremes on the widget. However, whereas scroll bars have a specific user interface purpose (moving the view through a window), track bars are generalized numeric input devices. Their purpose is to input a numeric value between a low range and a high range via a slider control.

Like scroll bars, you should limit the range of trackbar responses to 16 bits if you intend to use the onThumbTrack notification.

wTrackBar_t:

class inherits( wVisual_t );

var

align( 4 );

wTrackBar_private:

record

onChange :widgetProc;

onThumbPosn :widgetProc;

onThumbTrack :widgetProc;

onBottom :widgetProc;

onLineDown :widgetProc;

onLineUp :widgetProc;

onTop :widgetProc;

onEndtrack :widgetProc;

onPageDown :widgetProc;

onPageUp :widgetProc;

endrecord;

procedure create_wTrackBar

(

wtbName :string;

parent :dword;

x :dword;

y :dword;

width :dword;

height :dword;

style :dword;

onChange :widgetProc

); external;

method get_position; @returns( "eax" ); external;

method set_position( position:dword ); external;

method get_lowRange; @returns( "eax" ); external;

method get_hiRange; @returns( "eax" ); external;

method set_range( low:dword; high:dword ); external;

method get_onChange; @returns( "eax" ); external;

method get_onThumbPosn; @returns( "eax" ); external;

method get_onThumbTrack; @returns( "eax" ); external;

method get_onBottom; @returns( "eax" ); external;

method get_onLineDown; @returns( "eax" ); external;

method get_onLineUp; @returns( "eax" ); external;

method get_onTop; @returns( "eax" ); external;

method get_onEndtrack; @returns( "eax" ); external;

method get_onPageDown; @returns( "eax" ); external;

method get_onPageUp; @returns( "eax" ); external;

method set_onChange( onChange:widgetProc ); external;

method set_onThumbPosn( onThumbPosn:widgetProc ); external;

method set_onThumbTrack( onThumbTrack:widgetProc ); external;

method set_onBottom( onBottom:widgetProc ); external;

method set_onLineDown( onLineDown:widgetProc ); external;

method set_onLineUp( onLineUp:widgetProc ); external;

method set_onTop( onTop:widgetProc ); external;

method set_onEndtrack( onEndtrack:widgetProc ); external;

method set_onPageDown( onPageDown:widgetProc ); external;

method set_onPageUp( onPageUp:widgetProc ); external;

override method processMessage; external;

endclass;

onChange This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on the track bar (using any means to change the value). Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

onThumbPosn This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on the track bar by dragging the slider. HOWL calls this procedure after the user has released the mouse button while dragging the slider control. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current scroll bar position.

onThumbTrack This field, if non-NULL, points at a widgetProc procedure that HOWL will call while the user is dragging the slider around the track bar. An application can use this notification to dynamically adjust the system during slider movement. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar slider position.

onBottom This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user moves the slider all the way to the bottom on a vertical track bar or all the way to the left on a horizontal track bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position (which should be the maximum value).

onLineDown This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on a track bar by pressing the down arrow or the right arrow key on the keyboard. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

onLineUp This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on a track bar by pressing the up arrow or left arrow key on the keyboard. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

onTop This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user moves the slider all the way to the top on a vertical track bar or all the way to the left on a horizontal track bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position (which should be the maximum value).

onEndTrack This field, if non-NULL, points at a widgetProc procedure that HOWL will call after any trackbar operation is complete. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

onPageDown This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on a vertical scroll bar by clicking on the track bar between the slider and the left or bottom end of the track bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

onPageUp This field, if non-NULL, points at a widgetProc procedure that HOWL will call whenever the user changes the position of the slider on a track bar by clicking on the track bar between the slider and the top or right side of the track bar. Upon entry into the widgetProc procedure, the H.O. word of the wParam argument contains the current track bar position.

create_wTrackBar

This is the consructor for the wTrackBar_t class. If you call this as a class procedure (e.g., "wTrackBar_t.create_wTrackBar") then this procedure will allocate storage for a new wTrackBar_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wTrackBar will initialize that object in-place.

wtbName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the track bar will be drawn.

x, y, width, height: These arguments form a bounding box in which the track bar will be drawn.

style: HOWL logically ORs this value with the Windows styles (w.WS_CHILD | w.WS_VISIBLE | w.TBS_AUTOTICKS) when creating the scroll bar. At the very least, this field should contain w.TBS_HORZ for a horizontal track bar or w.TBS_HORZ for a vertical track bar. Please see the Windows documentation or the HLA w.hhf header file for additional track bar style ( TBS_*) constants.

onChange: this is the address (which can be NULL) of an onChange widgetProc procedure. The constructor will initialize the onChange field with this value.

get_position This function returns the current track bar position as a 32-bit value in the EAX register. Note that you can call this method from any of the event notification procedures except onThumbTrack to obtain the true 32-bit position of the slider control (rather than limiting yourself to the upper 16 bits of the wParam parameter). If you call this method from the onThumbTrack notification procedure, it will not return the current position of the slider, instead it will return the last position before the user started dragging the slider around. Sadly, there is no way to obtain a 32-bit current thumb position while dragging the thumb.

set_position This method sets the current thumb position on the track bar. The argument you pass to this method must be between the low and high range values for the track bar.

get_lowRange This method returns (in EAX) the current lower range for the track bar. This is typically zero, but you can program any 32-bit value you desire (see set_range ).

get_hiRange This method returns (in EAX) the current upper range for the track bar.

set_range This method lets you set the low and high range values for the track bar. The default range is 0..100, but you can set any 32-bit values you like. Note that if you intend to use the onThumbTrack notification, you should limit the range to 16-bit values.

low: the lower bound of the track bar range

high: the upper bound of the track bar range.

get_onChange,

get_onThumbPosn,

get_onThumbTrack,

get_onLineDown,

get_onLineUp,

get_onLineLeft,

get_onLineRight,

get_onEndtrack,

get_onPageDown,

get_onPageUp,

get_onPageLeft,

get_onPageRight,

get_onTop,

get_onBottom These are the accessor methods for the corresponding widgetProc pointer data fields in this class.

set_onChange,

set_onThumbPosn,

set_onThumbTrack,

set_onLineDown,

set_onLineUp,

set_onLineLeft,

set_onLineRight,

set_onEndtrack,

set_onPageDown,

set_onPageUp,

set_onPageLeft,

set_onPageRight,

set_onTop,

set_onBottom These are the mutator functions for all the widgetProc pointer fields in the class.

processMessage This is a private method in the class. Applications must not call this method.

Up/Down Arrows

An up/down arrow control is a pair of (stacked) arrow buttons that that user can click on in order to increment or decrement a value. Up/down arrow widgets can be stand-alone or they can be attached to a "buddy" edit box widget (wUpDownEditBox_t widgets_. When attached to a buddy edit box, the up/down arrow control reflects the current value of the control in the edit box.

wUpDown_t

The wUpDown_t class is used to create up/down arrow objects on a form.

wUpDown_t:

class inherits( wClickable_t );

procedure create_wUpDown

(

wudName :string;

parent :dword;

alignment :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lowerRange :dword;

upperRange :dword;

initialPosn :dword;

onClick :widgetProc

); external;

method get_lowerRange; @returns( "eax" ); external;

method get_upperRange; @returns( "eax" ); external;

method get_position; @returns( "eax" ); external;

method set_lowerRange( lowerRange:word ); external;

method set_upperRange( upperRange:word ); external;

method set_position( position :word ); external;

override method processMessage; external;

endclass;

create_wUpDown

This is the consructor for the wUpDown_t class. If you call this as a class procedure (e.g., "wUpDown_t.create_wUpDown") then this procedure will allocate storage for a new wUpDown_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wUpDown will initialize that object in-place.

wudName: HOWL assigns this string to the _name data field of the object. This string’s value should be constant over the execution lifetime of the newly initialized object.

parent: this is the handle of the wView_t or wForm_t object on which the track bar will be drawn.

alignment: this is one of the following Up/Down window styles:

UDS_ALIGNRIGHT Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.

UDS_ARROWKEYS Causes the up-down control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.

UDS_AUTOBUDDY Automatically selects the previous window in the Z order as the up-down control's buddy window.

UDS_HORZ Causes the up-down control's arrows to point left and right instead of up and down.

UDS_NOTHOUSANDS Does not insert a thousands separator between every three decimal digits.

UDS_WRAP Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.

x, y, width, height: These arguments form a bounding box in which the up/down arrow will be drawn. If buddy contains a non-NULL value, then Windows will ignore these values and will, instead, attach the arrows to the buddy edit box.

lowerRange: This is the minimum value that the up/down arrow control will decrement to. This value is typically zero, but it can be any 16-bit value that is less than the upperRange value. If the up/down control’s current value is equal to lowerRange and the user presses on the down arrow, Windows will ignore the decrement request.

upperRange: This is the maximum value that the up/down arrow control will increment to. This value can be any 16-bit value that is greater than the lowerRange value. If the up/down control’s current value is equal to upperRange and the user presses on the up arrow, Windows will ignore the increment request.

initialPosn: This is the initial value of the up/down arrow control. It must be a 16-bit value in the range lowerRange..upperRange .

onClick: this is the address (which can be NULL) of an onClick widgetProc procedure. The constructor will initialize the onClick field with this value. (Note that the onClick field is inherited from the wClickable_t parent class).

get_lowerRange This method retrieves the 16-bit lower range value for the up/down arrow control. It returns this 16-bit value (zero extended) in the EAX register.

get_upperRange This method retrieves the 16-bit upper range value for the up/down arrow control. It returns this 16-bit value (zero extended) in the EAX register.

get_position This method retrieves the 16-bit position value for the up/down arrow control. It returns this 16-bit value (zero extended) in the EAX register.

set_lowerRange This method sets the 16-bit lower range value for the up/down arrow control. Applications should limit the parameter to a 16-bit value.

set_upperRange This method sets the 16-bit upper range value for the up/down arrow control. Applications should limit the parameter to a 16-bit value.

set_position This method sets the 16-bit position value for the up/down arrow control. Applications should limit the parameter to a 16-bit value.

processMessage This is a private method. Applications must not call this method.

wUpDownEditBox_t

The wUpDownEditBox_t class is used to create a combination edit box and up/down arrow on a form.

wUpDownEditBox_t:

class inherits( wabsEditBox_t );

var

wUpDownEditBox_private:

record

lowerRange :dword;

upperRange :dword;

upDownHandle :dword;

upDownStyle :dword;

onUpDown :widgetProc;

endrecord;

procedure create_wUpDownEditBox

(

wudName :string;

initialTxt :string;

parent :dword;

style :dword;

upDownStyle :dword;

x :dword;

y :dword;

width :dword;

height :dword;

lowerRange :dword;

upperRange :dword;

initialPosn :dword;

onChange :widgetProc;

onUpDown :widgetProc

); external;

method get_lowerRange; @returns( "eax" ); external;

method get_upperRange; @returns( "eax" ); external;

method get_position; @returns( "eax" ); external;

method set_lowerRange( lowerRange:word ); external;

method set_upperRange( upperRange:word ); external;

method set_position( position :word ); external;

override method show; external;

override method hide; external;

override method enable; external;

override method disable; external;

override method processMessage; external;

endclass;

create_wUpDownEditBox

This is the consructor for the wUpDownEditBox_t class. If you call this as a class procedure (e.g., "wUpDownEditBox_t.create_wUpDown") then this procedure will allocate storage for a new wUpDownEditBox_t object on the heap and return a pointer to that object in ESI. If you make a standard object call to this constructor, then create_wUpDown will initialize that object in-place.