Installing and Running HLA Under Windows

HLA isn't quite yet a polished commercial application. Most of the development of HLA has gone into the development of the language and compiler itself, rather than ancillary tools. One area where this is painfull obvious is the installation of HLA. Correcting this deficiency has not been a high priority simply because installation is something you only have to fight with once (and installing updates to HLA is trivial once you install it the first time). The following information describes how to manually install and run HLA on a typical Windows system.

If You Are Installing HLA for the First Time (Quick Start!)

Most of this document involves installing HLA manually. For those who prefer painless installation, there is an HLA installer program available that automatically installs HLA and initializes the registry entries as required by HLA. This is probably the best solution for first time users of HLA under Windows. 95% of all installation problems occur because a first-time user decides to install HLA manually. Manual installation is not recommended if you've never before installed HLA; manual installation is intended for those who are upgrading HLA or those advanced users that want to understand every change made to their system. The decision to install manually should not be taken lightly. It's considerable more work and much more prone to error.

Note that automatic installation is available only to Windows users. Linux users, alas, will need to install HLA manually. If you're a Linux user, please check out the appropriate sections later in this document.

Automatic installation of HLA is done in two steps. In the first step, you will install the MASM32 package (which HLA uses) and then you will install HLA itself as the second step. Of course, you'll want to grab the latest versions of these two packages to install on your machine. You can find them both on the HLA download page at the following web page:

http://webster.cs.ucr.edu/Downloads.html

To download the MASM32 package, click on the appropriate link on this page. This will download an executable file (self-extracting ZIP file). Execute the file you download. Although this program gives you the option of installing MASM32 on different drives, installing MASM32 on any drive other than C:\ may create problems for you later on. Simply install MASM32 at the root level of your C drive (i.e., the installation should wind up in the "C:\MASM32" subdirectory).

Next, go to the HLA download page (following the link on the web page at the URL given above). Click on the "hlasetup.exe" link. This downloads a self-extracting version of the HLA installation program, RadASM, and other useful tools and documentation.

Note: make sure you download the "HLASETUP.EXE" file, not the "HLA Executables for Windows" module under "HLA Upgrade for Windows". This latter file is for those who want to upgrade an existing HLA installation. If you are a first time user, you want to use the setup program.

After downloading the HLASETUP.EXE program, simply execute it. You'll be asked a few simple questions about where you want to place the HLA files. Although it's possible to install HLA on any drive or within any subdirectory, most documentation and examples assume you've installed HLA on the C:\ drive in the root directory (that is, the files wind up in the C:\HLA subdirectory). If something goes wrong during installation, it's much easier to get help if you put HLA in your C:\ root subdirectory. The first time you install HLA, it's wise to put HLA in the C:\ root directory; after a successful installation, it's easy enough to move HLA, if you prefer to have it somewhere else.

Once you've run the MASM32 and HLA setup programs, you should be ready to try out the installation. You can follow the directions in the next couple of sections for trying out HLA once you've successfully installed the program.

Double-Clicking Doesn't Work!

Here's what the typical programmer does when they first decide to learn assembly programming with HLA:

1. The programmer eagerly downloads the HLA executables (and, if they've read anything about HLA, they download the MASM32 package too).

2. The programmer "unzips" the various packages they've downloaded.

3. The programmer double-clicks on the "HLA.EXE" icon.

4. The programmer sends me an email complaining that the program flashed up a console window briefly and then quit. They want to know why the environment didn't start up.

The answer I always send in reply to "where's the environment" is that there is none. HLA is an "old-fashioned" compiler that requires the use of a separate text editor to create HLA source files. Once you create an HLA source file, you've got to run the compiler from a command window (also known as a "shell" or "DOS box"). Momentarily, we'll discuss exactly how you do this. By now, you're probably thinking "How dumb! Why doesn't HLA provide an IDE like all decent languages?" Well, it does. The RadASM integrated development environment comes with HLA (HLASETUP.EXE, or you can download RadASM separately, if you prefer). But the HLA program itself is simply a compiler that you run from a command window prompt (which we'll discuss in a moment). See the RadASM documentation if you feel you can't work without an integrated development environment (IDE). This document will assume that you're using the command line tools, as HLA doesn't require the use of an IDE.

Okay, with the running commentary out of the way, let's go through the installation process and then figure out how to run this thing (one more time!).

Note: the following paragraphs describe the manual installation of HLA. If you've installed HLA using the HLASETUP.EXE installation program, you can skip over the following material:

Let's begin by discussing the files you'll need to grab in order to install HLA. The first step is to go to the HLA download page (at http://webster.cs.ucr.edu/Page_hla/0_hla_dnld.html as this was being written; go to http://webster.cs.ucr.edu and find HLA from Webster's main page if the former link is broken). As you scroll through this page you'll find a history of old HLA versions, listed from most recent to least recent. The HLA download page generally allows you to download the last three or four versions of the HLA system (the older versions are available in case modifications to HLA introduce some "show-stopper" defects and you need to back up a version or two in order to get a stable version). As this was being written, you're given links to download the following HLA modules:

• The HLA Executables,
• The HLA Library Source,
• The HLA Compiler Source Code,
• Some Example Code (Windows only at this time),
• Art of Assembly (AoA) Examples,
• HLA Documentation (PDF Format),
• HLA Documentation (HTML Format), and
• The MASM32 package.

Strictly speaking, the only downloads you absolutely need are the HLA executables, one of the documentation modules, and the MASM32 package (and MASM32 is necessary only if you don't already have MASM installed on your system).

The HLA Library Source module contains the source code to all the routines in the HLA Standard Library. This source code serves two purposes: (1) if you find a defect in one of the library modules and you need the problem corrected pronto, you've got the source code available, and (2) the HLA Standard Library provides a lot of sample HLA code for you to look at (around 50,000 lines of HLA code!).

The HLA Compiler Source Code module provides the Flex, Bison, C, and HLA source code for the compiler. This module also includes a few tools (like Flex and Bison) that you'll need to compile the program. Note that the HLA compiler source code is not for the feint of heart. It contains over 100,000 lines of code; this is not something you're going to learn over some weekend so you can hack in some feature you'd like. Still, the source code is available for those who are interested.

The Example code is a bunch of HLA examples I've written over the years in reponse to questions on various assembly newsgroups as well as some personal projects I've written. Most of this code will compile and run only under Windows, which is why this module isn't available for Linux users.

The AoA Examples modules contains all the sample code from the "Art of Assembly" textbook. Again, there is a lot of useful sample code here, though you should read this code concurrently with reading AoA.

The HLA documentation is available in two formats: PDF and HTML. PDF is, by far, the better of the two formats from a readability point of view. However, some users can't handle PDF for one reason or another (hard to believe since you may freely download Adobe Acrobat Reader for PDF files), hence the presence of the HTML files. For those paying for their downloads by the bit, the HTML version is a little shorter, as well.

The MASM32 package is Hutch's MASM32 development system. HLA requires MASM (for Windows development) which is a part of this package. Note that MASM32 is a complete development system for MASM that includes header files, some library routines, example programs, etc. Unfortunately, it's all MASM code, so it will be of little interest to someone learning HLA. Note, however, that the MASM32 package also includes a reasonable text editor and some other tools; you might want to read the accompanying documentation when you unpack MASM32 so see if there is anything else of interest to you in the package.

To unzip the HLA packages, you'll need a decompressor program like WinZip or PKunzip. The use of such programs is beyond the scope of this document; however, such tools are sufficiently ubiquitous that I can probably assume safely that you can deal with decompressing the HLA modules. Decompress the HLA executable module to the "c:\hla" subdirectory (this should be the default). If you absolutely, positively, have to put the HLA code somewhere else, I'll have to assume that you know what you're doing and will make all the appropriate adjustments to the directions that follow. If you're not absolutely confident that you can make all these adjustments, don't install HLA somewhere else.

When you decompress the HLA executables package, the "c:\hla" subdirectory (that's probably created by the decompression of the HLA executables) should contain the following:

• hla.exe -- This is part one of the HLA compiler's executable code.
• hlaparse.exe -- This is part two of the HLA compiler's executable code.
• include -- This is a subdirectory containing several ".hhf" files (hhf= HLA Header File).
• hlalib -- This is a subdirectory contain the "hlalib.lib" library file.

After decompressing the HLA executable module, double check that the files are were they belong in the "c:\hla" subdirectory. The remainder of the HLA installation and execution process will fail if this is not the case.

The HLA.EXE executable program is actually a "shell" program that runs the HLA compiler (HLAPARSE.EXE), the Microsoft Macro Assembler (MASM, or ml.exe), the Microsoft linker (link.exe), and, possibly, some other programs. Since HLA.EXE runs the ML.EXE (MASM) and link.exe programs, you need to install these files as well. The executables for these programs can be found in the MASM32 package. This zipfile contains a single executable, INSTALL.EXE (a professional installation program!) that will unpack and install MASM32 on your system. Run this program and install MASM32 at some appropriate spot (probably right on your C: drive). In the "bin" subdirctory where you've installed MASM32, you'll find the following files: ml.exe, ml.err, link.exe, and mspdb50.dll. Copy (copy, not move) these files to the "c:\hla" subdirectory so they appear with the HLA.EXE and HLAPARSE.EXE files. The "C:\hla" subdirectory should now contain the following:

• hla.exe
• hlaparse.exe
• ml.exe
• ml.err
• link.exe
• mspdb50.dll
• include (subdirectory)
• hlalib (subdirectory)

After copying the executables from the MASM32\bin directory, the next step is to copy some important library files from the MASM32\lib directory to the "c:\hla\hlalib" subdirectory. The files you need to copy are "kernel32.lib", "gdi32.lib", and "user32.lib" (ultimately, you may want to copy other Windows related lib files from the MASM\lib subdirectory as well, but these are the three needed for normal HLA console mode programming).

The next step is to tell the system where it can find all these files. This is done using the PATH, HLAINC, and HLALIB environment variables. You can set up these environment variables each time you open a command window (i.e., a "DOS" window), but this is a royal pain in the rear. Best to set up these environment variables just once. Unfortunately, the directions for doing so depend upon which version of Windows you're using. Windows 95 and 98 (and possibly Windows 2000 Me, I'm not sure since I've never used Me) generally require that you specify global environment variable settings in your "autoexec.bat" file (typically found in the root directory of your C: drive). Edit this file with a text editor (not a word processor) and add the following two lines to the file:

set hlainc=c:\hla\include

set hlalib=c:\hla\hlalib\hlalib.lib

Next, search for a line in the autoexec.bat file that contains something like "path= <<some text>>" (with a bunch of pathnames in place of '<<some text>>'). Edit this line of text so that it now reads:

path=c:\hla; <<some text>>

where '<<some text>>' represents the text that originally followed the "path=" statement. After making these changes, save the file back to disk. Warning: make sure you have a backup of the autoexec.bat file before you edit it. The correct operation of the system depends upon the consistency of this file. If you break something, you want to be able to replace the broken autoexec.bat file with the original file.

Finally, search for a line of text that takes the following form:

set lib= <<some text>>

Modify this line so that it reads as follows:

set lib=c:\hla\hlalib; <<some text>>

Where '<<some text>>' represents the text originally on the line.

If you're using Windows NT, 2000 Pro (or server), or Windows XP, you set up the environment variables differently. On these operating systems you go do the system control panel (select "control panels" from the Start menu and then select "system" from the control panel list or window) and select the "advanced" tab. At this point, click on the "Environment Variables" button. In one of the window panes that appears, you'll find the "PATH" environment variable. Edit it and add the "c:\hla;" prefix to the value, as was done for the autoexec.bat file above. Do the same for the "LIB" variable (supplying the library pathname). Once you save the "PATH" and "LIB" environment variables back (and verify the changes), add the two environment variables "hlainc" and "hlalib". For their values, specify "c:\hla\include" and "c:\hla\hlalib\hlalib.lib", respectively. Warning: be careful when editing environment variables. It's possible for you to mess up the system if you inadvertently change something you're not supposed to change.

In order to test the above, it's a good idea to reboot the system at this point (this is a mandatory step if you're using Win95/98 and had to edit the autoexec.bat file). Once the system has rebooted, start up a command prompt window. Microsoft excels at hiding the command prompt Window in various versions of Windows. If you can find it in the Start menu, the Start->Programs menu, or in the Start->Programs->Accessories menu, try selecting Start->Run and typing "cmd" as the name of the program to run (on really old OSes like Win95 and possibly 98, you may have to run the "command" program). This should bring up a window with a "C:>" prompt. Type "SET" followed by the enter key. In the text that scrolls by, ensure that the "PATH=..." line has the "c:\hla;" prefix and that the "hlalib" and "hlainc" variables appear with the appropriate paths to their subdirectories. If this is not the case, then check the changes you've made and try again. If trying again doesn't work, try asking for help on comp.lang.asm.x86 or alt.lang.asm (sorry, I can only personally help you if you're running the same OS I am; as I'm writing this, that's Win2K Pro).

If it turns out that the directions above don't work for you, please read the section "Installing HLA Under Windows" in the HLA Reference manual. It describes this same exact process, but a little differently; hopefully the different perspective will help you figure out what's wrong.

At this point you should be ready to write, compile, and run your first HLA program, but first...

What You've Just Done

Before describing how to write, compile, and run your very first HLA program, it's probably worthwhile to take a quick step back and carefully consider what we've accomplished in the previous section so it's easier to troubleshoot problems that may come up. This section describes how the steps you went through in the previous section affect the execution of HLA.

Note: This section is of interest to all HLA users; whether you've installed HLA via the HLASETUP.EXE program, or you've manually installed HLA.

In order to execute HLA.EXE, HLAPARSE.EXE, and various other programs needed to compile and run an HLA program, the operating system needs to be able to find all the executable files that HLA needs. In theory, the executable files that HLA needs could be spread out all over your system as long as you tell the OS where to find each and every file. In practice, however, this makes troubleshooting the setup a lot more difficult if something goes wrong. So it's best to put all the necessary executables in the same directory.

Note that Windows doesn't know anything at all about the "C:\HLA" subdirectory; it's not going to automatically look for the HLA executables in this subdirectory, you have to tell Windows about this directory. This is done using the "PATH" environment variable. Whenever you tell Windows to run a program from a command prompt window, the OS first looks for a program with the given name in the current directory. If it finds the program (with a ".EXE", ".COM", or ".BAT" suffix), it will run that program from the current directory. If it does not find a program with an allowable suffix in the current directory, then the OS will use the PATH environment variable to determine which subdirectories to search through in order to find the executable program. The PATH environment variable is a (possibly empty) string that takes the following form:

pathToDirectory; pathToDirectory; pathToDirectory;...

Each pathToDirectory item in the list above generally represents a full path to some directory in the system. Examples include "c:\hla", "c:\windows", and "c:\bin"; these are always paths to directories, not to individual files. A PATH environment string may contain zero or more such paths; if there are two or more paths, each subdirectory path is separated from the others by a semicolon (the ellipses ["..."] above signify that you may have additional paths in the string, you don't actually place three periods at the end of the list).

When Windows fails to find an executable program you specify on the command line in the current directory, it tries searching for the executable file in each of the directory paths found in the PATH environment variable. Windows searches for the executable file in the subdirectories in the order that they appear in the environment string. That is, it searches for the executable in the first directory path first; if it doesn't find the executable in that directory, it tries the second path in the environment string; then the third, then the fourth, etc. If Windows exhausts the list of directory paths withoutt finding the executable file, it displays an error message. For example, suppose your PATH environment variable contains the following:

c:\hla; c:\windows; c:\bin

If you type the command "xyz file1" at the command line prompt, Windows will first search for program "xyz.exe", "xyz.com", or "xyz.bat" in the current directory. Failing to find the program there, Windows will search for "xyz" in the "C:\HLA" subdirectory. If it's not there, then Windows tries the "C:\WINDOWS" subdirectory. If this still fails, Windows tries the "C:\BIN" subdirectory. If that fails, then Windows prints an error message and returns control to the command line prompt. If Windows finds the "xyz" program somewhere along the way, then Windows runs the program and the process stops at the first subdirectory containing the "xyz" program.

The search order through the PATH environment string is very important. Windows will execute the first program whose name matches the command you supply on the command line prompt. This is why the previous section had you put "c:\hla;" at the beginning of the environment string; this causes Windows to run programs like HLA.EXE, HLAPARSE.EXE, ML.EXE, and LINK.EXE from the "C:\HLA" subdirectory rather than some other directory. This is very important! For example, there are many versions of the "LINK.EXE" program and not all of them work with HLA (and chances are pretty good that you might find an incompatible version of LINK.EXE on your system). Were you to place the "C:\HLA" directory path at the end of the PATH environment string, the system might execute an imcompatible version of the linker when attempting to compile and link and HLA program. This generally causes the HLA compilation process to abort with an error. Placing the "C:\HLA" directory path first in the PATH environment variable helps avoid this problem1.

By specifying the PATH environment variable, you tell Windows where it can find the executable files that HLA needs in order to compile your HLA programs. However, HLA and LINK also need to be able to find certain files. You may specify the location of these files explicitly when you compile a program, but this is a lot of work. Fortunately, both HLA.EXE and LINK.EXE also look at some environment variable strings in order to find their files, so you can specify these paths just once and not have to reenter them every time you run HLA.

Most HLA programs are not stand-alone projects. Generally, an HLA program will make use of routines found in the HLA Standard Library. The HLA Standard Library contains lots of conversion routines, input/output routines, string functions, and so on. Calling HLA Standard Library routines saves a considerable amount of effort when writing assembly language code. However, the HLA compiler isn't automatically aware of all the routines you can call in the HLA Standard Library. You have to explicitly tell the compiler to make these routines available to your programs by including one or more header files during the compilation process. This is accomplished using the HLA #include and #includeonce directives. For example, the following statement tells the HLA compiler to include all the definitions found in the "stdlib.hhf" header file (and all the header files that "stdlib.hhf" includes):

#include( "stdlib.hhf" )

When HLA encounters a #include or #includeonce directive in the source file, it substitutes the content of the specified file in place of the #include or #includeonce . The question is "where does this file come from?" If the string you specify is a full pathname, HLA will attempt to include the file from the location you specify; if it cannot find the file in the specified directory, the HLA will report an error. E.g.,

#include( "c:\myproject\myheader.hhf" )

In this example, HLA will look for the file "myheader.hhf" in the "c:\myproject" directory. If HLA fails to find the file, it will generate an error during compilation.

If you specify a plain filename as the #include or #includeonce argument, then HLA will first attempt to find the file in the current directory (the one you're in when you issued the HLA command at the command line prompt). If HLA finds the file, it substitutes the file's contents for the include directive and compilation continues. If HLA does not find the file, then it checks out the "HLAINC" environment variable, whose definition takes the following form:

hlainc=c:\hla\include

Unlike the PATH environment variable, the HLAINC environment variable allows only a single directory path as an operand. This is the path to the HLA include files directory which is "c:\hla\include" (assuming you've followed the directions in the previous section). Since HLA header files usually come in two varieties: headers associated with library routines and header files associated with the current project, the fact that HLA only provides one include path is not much of a limitation. You should keep all project-releated header files in the same directory as your other source files for the project; the HLA library header files (and header files for any generic library modules you write) belong in the "C:\HLA\INCLUDE" directory. Note that if you want to place header files in some directory other than the current directory or the directory that the HLAINC environment variable specifies, you will have to specify the path to the include file in the #include or #includeonce statement.

If HLA cannot find the specified header file in the current directory or in the directory specified by the HLAINC environment variable, then you'll get an error to the effect that HLA cannot find the specified include file. Needless to say, most assemblies will fail spectacularly if HLA cannot find the appropriate header files.

Since most HLA programs will use one or more of the HLA Standard Library header files, chances are pretty good that the assembly won't be successful if the HLAINC environment string is not set up properly. Conversely, if HLAINC does contain the appropriate string, then HLA will be able to successfully compile your code to assembly and run MASM on the assembly code to produce an object file. The last step, converting the object file to an executable, introduces another possible source of problems. The LINK program combines the object file associated with your code with HLA Standard Library and Windows library modules. Even the most trivial HLA program will need to link with (at least) one or more Windows module (the most trivial HLA program is probably the one that immediately returns to the OS; such a program needs to call the Windows ExitProcess API in order to return to the OS, so at the very least you'll need to link with the Windows' kernel32.lib module to be able to call ExitProcess). Once again, however, the library modules that your program needs could be anywhere on the disk. You'll have to use some environment variables to tell HLA and the linker where it can find the library modules. You accomplish this using two environment variables: one for HLA and one for the linker. We'll discuss the HLALIB environment variable first, since it's the easiest to understand.

The HLA Standard Library contains hundreds of small little routines that have been combined into a single file: "hlalib.lib". Whenever you call a particular standard library routine, the linker extracts the specific routine you call from the "hlalib.lib" library module and links combines this code with your program2. Once again, the linker program (and HLA) don't know where to find this file, you have to tell them where to find it. This is done using the HLALIB environment variable; this environment variable contains a single pathname, the full path to the HLALIB.LIB file. I.e.,

set hlalib=c:\hla\hlalib\hlalib.lib

The important thing to note in this example is that the path is the full pathname of the HLALIB.LIB file including the filename at the end of the path. This is in direct contrast to the PATH and HLAINC environment objects where you specify only the subdirectory containing the desired files.

In addition to the "hlalib.lib" library file, you'll also need to link your HLA programs against various Windows library modules. Basic HLA programs will need to link against the Windows' kernel32.lib, user32.lib, and gdi32.lib library modules. These library modules (plus several other Windows related library modules) are found in the MASM32\lib subdirectory; though in the previous section you should have copied these three library modules to the "c:\hla\hlalib" subdirectory. You'll need to tell the LINK.EXE program where it can find these files, this is done with the LIB environment variable. The LIB environment variable's syntax is very similar to that for the PATH environment variable. You get to specify a list of directories in the LIB environment string and LINK.EXE will automatically search for missing library files in each of the paths you specify, in the order you specify, until it finds a matching filename. By prepending "c:\hla\hlalib;" to this environment string, you tell LINK.EXE to search for library modules like KERNEL32.LIB, USER32.LIB, and GDI32.LIB in the "C:\hla\hlalib" subdirectory if it doesn't find them in the current subdirectory3.

Note: in the future, if you make other Win32 API calls you may need to copy additional .LIB files from the MASM32\lib directory to the "c:\hla\hlalib" directory. However, for most basic HLA programs (and certainly, all console mode programs) you won't need to do this. Another alternative would be to add the path to the MASM\LIB directory to the LIB environment string.

Okay, with this explanation out of the way, it's time to write, compile, and run, our first HLA program!

Running Your First HLA Program

A long running convention is to write a "Hello World" programs as the very first program program in any language. This document will continue that cherished convention.

The first step is to enter the program into a text editor. HLA is not an "integrated development environment" (IDE) so you don't run HLA and enter the program into the editor that HLA provides; because HLA doesn't provide one. Instead, you use a separate text editing program (not a word processor) to create your HLA programs. You can generally use your favorite text editor you use for writing programs in other languages. For example, if you've got Microsoft's Visual Studio system (Visual C++, Visual BASIC, etc.) you can use that text editor to create HLA programs. You may also use the "QEdit" program that comes with MASM32 to create HLA programs. In a pinch, you can even use the "Notepad" program that comes with Windows to create HLA programs. Whatever you decide, the only rules is that your program must create ASCII-only text files since this is what HLA expects (word processors like Microsoft Word inject non-ASCII binary data into the output file, this is what makes them inappropriate for creating HLA programs). The use of one of these text editors is beyond the scope of this document. However, most computer users are familiar enough with text editors (e.g., Notepad) that this topic doesn't warrant any further discussion, anyway.

When writing HLA programs, the best approach is to create a single directory for each project you write. I'd suggest creating a subdirectory "c:\hla\projects" and then create a new subdirectory inside "c:\hla\projects" for each HLA project you write. For the example in this section, you might create the directory "c:\hla\projects\hw" (for "Hello World").

There are many different ways to create project directories. The most common way to do this under Windows is in the Windows Explorer (right click on a window and select "New->Folder"). However, since HLA is a command-line based tool, it's probably best to describe how to do this from the command line just to introduce some (possibly) new command line commands.

The first step is to bring up a command prompt window. Generally, this is done by selecting "Start->Programs->Accessories->Command Prompt"4 from the Windows Start menu. You may also select "Start->Run" and type "cmd" (or "command" in Win95) to bring up a command prompt shell. If you wind up righting a lot of HLA code, you'll want a faster and easier way to run the command prompt, so I recommend creating a shortcut to the command prompt program on your desktop. To do this, click on Start (and release the mouse button), then move the mouse cursor to select "Programs->Accessories->Command Prompt". Now right-click on the "Command Prompt" menu item and drag it onto your desktop. Select "Create Shortcut(s) Here" from the resulting pop-up menu. You should now have a shortcut to the command prompt shell program on your desktop and you can easily run the shell by double-clicking on its icon.

If you've created a shortcut, there are a couple of additional things you should do to make HLA development a little easier for you. Right click on the shortcut you've just created and select properties. In the window that pops up, you'll probably want to change the "Start In:" string to "c:\hla\projects". This tells the command prompt program to make the specified path the current directory whenever you run the command prompt program by double clicking on this icon. By starting off inside the c:\hla\projects" subdirectory, you'll find that you save some typing (assuming, of course, you wind up putting most of your projects in the "c:\hla\projects" directory; use a different path here if this is not the case). Next, select the "layout" tab in the Command Prompt Properties window. Under "Screen Buffer Size" you'll probably want to make the value larger (the default is 300 on my system). I've found that 3000 is a fairly good number here. This number specifies the number of lines of text that the system will save when data scrolls off the top of the screen. This lets you view up to 3,000 lines of text from program execution (including your program's output, HLA error messages, etc.). If you've got a large monitor, you might also want to change the Window Size values as well. The default 80 colums is probably fine, though you may want to expand the Height to 50 lines (or whatever your monitor allows). Once you've set up the command window properties, double-click on the command prompt icon to start it running.

The first step, before doing anything else, is to verify that you've properly set up the environment variables. To check out their values, simply type "set" followed by ENTER. The "set" command without any parameters tells the command shell to dump the current values of all the environment variables active in the command prompt window. Scan through this list (scrolling back using the scroll bar if there are too many definitions to all fit in the window at one time) and search for the PATH, LIB, HLAINC, and HLALIB environment variables. Verify that they are present and have the correct values (that you've entered in the previous sections). If they're not present or the values are incorrect, HLA will not execute properly and you need to fix this problem first (Win95/98 users, did you remember to reboot after changing the autoexec.bat file?). If the environment variables are present and correct, then you're ready to try writing and running your first HLA program.

Switch to the "C:\HLA" subdirectory by using the following DOS (command line prompt) command5:

cd c:\hla

"cd" stands for "Change Directory". This command expects a single command line parameter which is the path of the directory that you want to make the "current directory." If you ever want to know what the current directory is, simply type "cd" without any parameters and the Command Shell will display the current directory6

If you haven't done so already, it's time to create the "projects" directory where you will place the HLA projects you create. Do this with the following command:

mkdir projects

"mkdir" stands for "make directory" and this command requires a single argument - the name of the directory you want to create. If you do no specify a full pathname (as is the case in this example), the command shell creates the directory within the current directory. Verify that you've properly created the "projects" subdirectory by issuing the following DOS command:

dir

"dir" stands for "directory" and tells the command shell to display all the files in the current directory. This should list the projects directory you just created (plus all the other files and directories in the "c:\hla" directory). Note that you can also use the Windows Explorer to create directories and view the contents of directories. However, since HLA is a command prompt based application, it's useful to learn a few DOS commands that will prove useful.

Now, switch to the projects subdirectory by using the following DOS command:

cd projects

At this point, it's a good idea to create a new subdirectory for the "Hello World" project. Do this by using the following DOS command:

mkdir hw

CD into this directory once you've created it. Now you're ready to begin work on the "Hello World" program.

Leaving the command prompt Window open for the time being, run the editor of your choice (e.g., QEditor.exe that comes with the MASM32 package or NOTEPAD.EXE, if you don't have any other preferences). Enter the following HLA program into the editor:

program HelloWorld;

#include( "stdlib.hhf" )

begin HelloWorld;

stdout.put( "Hello, World of Assembly Language", nl );

end HelloWorld;

Scan over the program you've entered and verify that you've entered it exactly as written above. Save the file from your editor as hw.hla in the c:\hla\projects\hw subdirectory (generally using the File>Save or File>Save As menu item in the editor). Switch over the the command prompt window and verify that the file is present by issuing a "DIR" command; this should list the hw.hla file. If it's not present, try saving the file again and be sure to browse to the "c:\hla\projects\hw" before actually saving the file.

WARNING: NOTEPAD.EXE has a habit of tacking a ".txt" to the end of filenames you save to disk. Default installations of Windows do not display file suffixes of known file types (and ".txt" is a known type). Therefore, a directory window may show a program name like "hw.hla" when, in fact, the filename is "hw.hla.txt". Probably the number one problem people have when testing out their HLA installation is that the compiler claims it cannot find the file "hw.hla" when the user first attempts to compile the file. This is because it's really named "hla.hw.txt". You must change the filename to "hw.hla" before HLA will accept it. This is the number one HLA installation problem. Watch out for this!

Once you've properly saved the file as c:\hla\projects\hw\hw.hla, it's time to run the HLA compiler on this file. Switch to the command prompt window (I'm assuming here that c:\hla\projects\hw is still the current directory, if not, switch to that directory using the CD command). In the command prompt window, enter the following command:

hla hw

This command instructs Windows to run the HLA.EXE program in order to compile the hw.hla source file. Note that specifying the ".hla" suffix is optional. If you specify a filename argument to the hla command that does not have a (recognized) suffix, HLA automatically appends ".hla" to the filename prior to attempting to compile it. I.e., the above command is completely equivalent to

hla hw.hla

If all goes well, HLA should do its job without reporting any errors. If HLA reports some sort of problem with the source file, switch back to the editor program and correct the mistake (HLA generally lists the line number in the file near the cause of the problem). If there doesn't seem to be a problem with the source file, go to the next section (troubleshooting) and follow the directions there.

If you've followed and verified all the steps up to this point, you should be able to execute the HLA command above without incident. About the only message you'll see during compilation is "Assembling hw.asm" (this message is actually produced by MASM, not by HLA). Behind your back, however, HLA has accomplished quite a bit. You can verify this by typing the "DIR" command at the command prompt; you'll see a whole bunch of new files in the directory, these files include:

• hw.asm - This is the main assembly output file produced by HLA.
• hw.data.inc - This is an auxiliary assembly output file that HLA produces.
• hw.bss.inc - This is an auxiliary assembly output file that HLA produces.
• hw.ro.inc - This is an auxiliary assembly output file that HLA produces.
• hw.consts.inc - This is an auxiliary assembly output file that HLA produces.
• hw.link - This is a linker command file that HLA produces.
• hw.obj - This is the object file that MASM produces from the ASM and INC files.
• hw.exe - This is the executable file that the linker produces.

The hw.exe file is the one we're most interested in at this point. This is the actual executable program that HLA produced from the hw.hla source file. To execute this program, simply type "hw" from the command line prompt; hopefully, you see the text "Hello, World of Assembly Language" appear on the line following the execution of the hw command. If you've gotten this far, congratualations; you've successfully installed HLA and compiled and run your first HLA program. You can, therefore, skip the next section on troubleshooting.

Troubleshooting an HLA Installation

Although I've written the preceding sections on HLA installation and operation as simply as I can imagine, there's always the possibility that I forgot something or you've gotten off-track somewhere along the way. In this section I'll try to point out some of the more common installation problems I've encountered over the years.

Before describing common installation problems, I do want to point out some HLA features you may find handy when troubleshooting an HLA installation and I want to point out some resources you can use to resolve your problems. First, if you've gone through the above steps and HLA is still not running properly, but it is, at least, running, you can get more information about the cause of the problem by using the HLA "-v" (for verbose) option. I.e., run HLA as follows:

hla -v hw.hla

This will produce output that is similar to the following (though version and build numbers may be different):

HLA (High Level Assembler)

Released to the public domain by Randall Hyde.

Version Version 1.38 build 5946 (prototype)

Files:

1: hw.hla

Compiling "hw.hla" to "hw.asm"

Assembling hw.asm via "ml /c /coff /Cp hw.asm"

Microsoft (R) Macro Assembler Version 6.14.8444

Copyright (C) Microsoft Corp 1981-1997. All rights reserved.

Assembling: hw.asm

Linking via "link -subsystem:console /heap:0x1000000,0x1000000 /stack:0x1000000,0x1000000 /BASE:0x3000000 /machine:IX86 -entry:?HLAMain @hw.link -out:hw.exe kernel32.lib user32.lib c:\hla\hlalib\hlalib.lib hw.obj"

Microsoft (R) Incremental Linker Version 5.12.8078

Copyright (C) Microsoft Corp 1992-1998. All rights reserved.

/section:.text,ER

/section:readonly,R

/section:.edata,R

/section:.data,RW

/section:.bss,RW

Most of this information is of little use to you, but the important thing is that this verbose output will help you figure out where there error occurs (during HLA compilation, during MASM assembly, or during linking). Most errors due to installation problems occur during compilation (between the messages <<Compiling "hw.hla" to "hw.asm">> and <<Assembling hw.asm via "ml /c /coff /Cp hw.asm">> in the output above) or during linking (after the <<Linking via "link -subsystem:console /heap:0x1000000,0x1000000>> statement above). This provides an important clue to the source of your difficulties.

If you cannot even run HLA, that is, if the OS complains that it cannot find the hla.exe program, this generally indicates that the PATH environment variable is not properly set up (either you haven't added the "c:\hla;" path to the environment string or the path you supplied is incorrect), you've somehow deleted the hla.exe file, or you've not installed the HLA executables to the "c:\hla" directory. It could also mean that you've installed HLA properly and set the PATH environment variable in your autoexec.bat file (Win95/98) but you forgot to reboot afterwards. Verify that the "C:\hla" subdirectory contains all the HLA, MASM, and LINK files noted earlier and verify that the PATH environment variable contains "C:\HLA" as the first entry in the path (use the DOS "set" command to display the current environment variables' values). You might also try switcing to the "C:\hla" directory in a command shell window and try executing HLA directly from that directory (remember, Windows searches the current directory for an executable prior to trying the PATH). If you can execute HLA from within the "c:\hla" directory, but not outside it, you've definitely got a path-related problem. WinNT/2K/XP users should note that setting the PATH in an autoexec.bat file does not work. You must set the PATH environment variable using the System control panel applet. Please see the earlier section for details.

Probably the most common installation error is that HLA runs properly, but complains about being unable to find the stdlib.hhf header file when you compile the "Hello World" program. In every instance I've seen, this is due to not having properly set up the HLAINC environment variable. If you're getting this error while attempting to compile hw.hla, immediately type the following DOS command and then retry the HLA compilation:

set hlainc=c:\hla\include

Chances are pretty good that if you've not set up the HLAINC environment variable properly, you've most likely failed to set up the HLALIB environment variable, too. That means that you'll get some different errors if you recompile hw.hla after executing the set command above, but you shouldn't be getting the complaint about the stdlib.hhf file anymore. Note that type this set command at the command line prompt is only a temporary solution to verify that HLAINC was not set properly. This setting only lasts until you close the command prompt window. Since you probably don't want to have to enter this command (among others) every time you open a command line window, you should follow the previous directions and add this set command to the autoexec.bat file (Win95/98) or properly set up the path in the Control Panel System applet under other versions of Windows. If you've already done this, go back and check your work - there's probably a typo in there somewhere.

Generally, if someone has messed up the HLAINC environment variable, the HLALIB environment variable is toast as well. So it's a good idea to check the HLALIB environment variable at the same time you making corrections to the HLAINC item. If you attempt to compile an HLA source file and HLAINC is properly set up but HLALIB is not, then the linker will probably complain about being unable to openn the input file "hlalib.lib". This is your indication that the HLALIB environment variable needs correction. To verify that this is, indeed, the problem, enter the following DOS command and then retry the compilation:

set hlalib=c:\hla\hlalib\hlalib.lib

If, after you enter the command above, the compilation succeeds, don't forget that you've got to go change the HLALIB environment variable setting in the autoexec.bat (Win95/98 users) or in the Control Panel System Applet (WinNT/2K/XP) to make the correction permanent. Of course, you should check to verify that the hlalib.lib file actually is present in the c:\hla\hlalib subdirectory. Generally, it's difficult to get to this point in the installation process and not have the file present, but you never know...

If HLA complains that it cannot find or execute ML.EXE (or LINK.EXE) during compilation, this probably means that you've not installed the MASM32 package or you haven't moved the ml.exe, ml.err, link.exe, and mspdb50.dll files to the c:\hla subdirectory. Correct this problem and retry the assembly.

Another common installation problem manifests itself when the linker runs. If the linker starts producing strange errors about not being able to find certain ".OBJ" files, it complains about "fixups", or stack problems, chances are pretty good that the system is running an older, 16-bit, version of the linker. This generally happens if you copy the wrong link.exe program to c:\hla or the system finds a different version of link.exe in the execution path prior to finding the copy in c:\hla. The solution to this problem is to ensure that (1) the old version of link.exe is not present in your current directory (which is unlikely) and (2) make sure that c:\hla appears in the PATH environment string prior to any other directory entries.

Hopefully, you're not still writing 16-bit code, but be aware that if you need to switch between 16-bit development and 32-bit development (e.g., HLA), you may run into the same problem in reverse when working on the 16-bit code; that is, the system may find the 32-bit linker which may choke on the 16-bit code. The best solution to this problem is to do the following:

1) Create a file in the c:\hla directory, name it "ihla.bat" (initialize HLA), and give it the following contents:

set lib=c:\hla\hlalib;%lib%

set hlainc=c:\hla\include

set hlalib=c:\hla\hlalib\hlalib.lib

set path=c:\hla; %path%

2) Create a shortcut to the cmd.exe (command prompt) program on your desktop by clicking and releasing the mouse button on the Start menu and then moving the mouse cursor over "programs" then "accessories" and, finally "Command Prompt"7. With the mouse cursor over the "Command Prompt" menu item, press the right mouse button and drag the entry from the menu on to your desktop. Release the right mouse button. A pop-up menu should appear, select "Create Shortcut(s) Here" from the pop-up menu.

3) Right-click on the shortcut you've just created in step (2) above and select properties. The "Target:" text box should contain something similar to the following string:

%SystemRoot%\system32\cmd.exe

(the exact text is meaningless, though it should look similar to this). Append the following text to the end of the string in this text entry box (be sure there's at least one space between the end of the string above and the start of the following):

/k c:\hla\ihla.bat

This tells the operating system to run the ihla.bat file whenever it opens this command prompt window. The ihla.bat file sets up the environment variables only for the command window you've opened by double-clicking on this shortcut. It does not affect any other command prompt windows or applications. Therefore, you can use this short cut to open command prompt windows for HLA compilations and open different windows (or applications) for developing 16-bit code.

4) Change the text in the "Start In:" text box to "c:\hla\projects" (or whatever subdirectory you want to be the default current directory when the command shell window starts up).

5) Select the "Layout" tab in the Command Prompt Properties windows and set the Screen Buffer Size Height value to something more reasonable (like 3000). You might also want to change the size of the Window to something besides 80x25, assuming your screen is large enough.

6) Delete the references to c:\hla, c:\hla\hlalib, HLAINC, and HLALIB from your autoexec.bat file (Win95/98 users) or from the environment variable strings set in the Control Panel System applet. This is necessary to eliminate the conflict between the 16-bit and 32-bit linkers.

With the changes to the shortcut above, you've now got a shortcut that will automatically start up a command prompt window with HLA-friendly environment strings that do not create system problems because they are global. This will prevent competition for "the first LINK.EXE" program and competition for library files in the Windows search paths. If you do development in several other languages besides HLA, it's probably not a bad idea to use this scheme to prevent conflicts.

Note: I've recently added an "initHLA.exe" program to the HLA distribution (starting with HLA v1.53). This program automatically sets the registry entries for HLA when you run it (and you only need to run it once). If the system can't find HLA and you've placed it in the c:\HLA subdirectory, and you've installed MASM, just run the initHLA.exe program and it will set up the registry entries for you.

Where to Turn if All Else Fails

If you've tried everything up to this point and you still can't get HLA to run properly, here's my recommendations:

1) Read the HLA Reference manual. There's a lot of good information on installing HLA present there. Well over half the installation problems I've encountered were due to the fact that the HLA user simply tried to install HLA without reading the instructions first. Although much of the HLA installation information was duplicated in this document, it does provide another perspective and going through that process force you to do something you accidentally missed while following the directions in this documentation.

2) Check the HLA page on Webster (http://webster.cs.ucr.edu) to see if there are any installation issues you need to be aware of.

3) Try installing HLA using the HLAsetup.exe program rather than installing it manually.

4) Post a question to one of the assembly newsgroups (either comp.lang.asm.x86 or alt.lang.asm). I frequent these newsgroups all the time, and I prefer to answer your questions publicly rather than in private email so others may benefit from my replies. Furthermore, installation issues often are OS version specific and I don't have and don't use every version of Windows; so it could be that someone else has the answer that I simply can't provide.

5) If you do not have newsgroup access (hard to believe, but many people don't), you can send me an email at rhyde@cs.ucr.edu. Note that all such emails become my property and by sending me emails requesting help you are implicitly providing me permission to use that email any way I see fit (including posting its contents to a newsgroup or on Webster).

Updating HLA

HLA is under constant revision. At some point or another you're probably going to want to update your copy of HLA to the latest and greatest version. You might want to do this because you've encountered some defects in HLA and you want a corrected version, or it could be that you want to use some new features found in later versions of HLA. Fortunately, the update process is nowhere near as complex as your first installation.

Most of the time, all you'll really need to do when updating HLA is download the executables file and unzip it. Assuming (as this documentation does) that you've put HLA in the default c:\hla directory, unzipping the executables files will automatically replace the old HLA versions with the new ones. At the bare minimum, that's all you need to do to update HLA. Not much, eh?

To be on the safe side, it's probably a good idea to first make a copy of your c:\hla subdirectory before applying the update (by unzipping the executables file). Sometimes new HLA versions have radical changes that cause it to no longer compile older source files (usually, the changes needed to correct the source file are minor, but you may not have the time to make such changes if you're in crisis mode). Sometimes changes to HLA introduce new defects and your existing source code may break as a result of those defects. Having a back up of the old executables laying around can help you to back out of such a disaster. Note that I maintain several older versions of HLA on Webster, so you can always download something other than the most recent version of HLA if you've got problems with the latest version. However, if you've not updated your version in a while, your version may no longer be available on Webster (which is why it's a good idea to make a backup of your executables, the include files, and the library files prior to doing an update).

Note that the HLA download page contains descriptions of the corrected defects and the new features on a version by version basis. So you can always go to the HLA downloads page on Webster to determine if the latest version of HLA contains features you want or need; in a similar vein, those descriptions will also warn you if changes to HLA are likely to break old source code (that is, whether source code that compiles under older versions of HLA may need minor changes in the syntax to compile under the new version). This actually doesn't happen all that often, but it does occur on occasion. This is useful information when you're deciding whether you want to upgrade to the latest version8.

You probably don't have to download new HLA documentation with each upgrade unless there are a lot of new features you want to use in the upgrade. The documentation generally doesn't change that much between versions unless there are a lot of new features. If you're not going to use the new features, downloading the new documentation is probably a waste of time. Unless you're in the habit of recompiling the HLA Standard Library on a regular basis, you probably don't need to download any source code, either. Likewise, the example code doesn't change all that frequently, so you probably don't need to download that, either. For those who are reading "The Art of Asembly Language Programming" (AoA), I usually announce new versions of that text on one of the assembly newsgroups; updates to AoA are not done in sync with HLA, so you shouldn't bother downloading a new copy of AoA whenever a new version of HLA appears (and vice versa).

Once you get HLA up and running, maintaining it (by downloading and unzipping new versions) is a relatively trivial matter. Indeed, it's even easier than running a typical "professional" installation program. Someday, HLA may support a full installation program, but until then, I hope that this documentation provides everything you need to install, use, and update HLA.

Moving HLA

If, for some reason, you decide you don't want HLA on your C: drive, or that you want HLA installed in a different subdirectory than C:\HLA, there are only two steps needed to move HLA elsewhere. First, physically copy all the files in the C:\HLA subdirectory (or wherever you've put HLA) to the new destination directory. Once this is accomplished, simply modify your system's PATH, HLALIB, HLAINC, and LIB environment variables. The environment variables are most easily set (or changed) in your system control panel. Just select "Settings>Control Panel" from the START menu in Windows. Then run the "System" control panel object and press the "Advanced" tab. Hit the "Environment Variables" button and modify the "lib", "path", "hlainc", and "hlalib" environment variables appearing in the two window panes that appear.