Building External Libraries of Procedures

You'll notice that the EAT3.ASM program given at the end of the previous section had most of its bulk devoted to procedures. This is as it should be, with the caution that the procedures it uses are the kind you're likely to use in any and all of your assembly language programs. Keeping cursor movement and screen-clearing routines in source code form in every single program you write is a waste of space and can clutter up the program in a way that makes it less easy to understand.

The answer is to break the utility procedures out into an external library that you can assemble only once, and then link into every program that uses its procedures without assembling the library every time you assemble the program. This is called modular programming, and it is an extremely effective tool for programming efficiently in any language, assembly language not excluded.

I describe this process briefly back in Chapter 4 and show it pictorially in Figures 4.4 and 4.5. A program might consist of three or four separate .ASM files, each of which is assembled separately to a separate

.OBJ file. To produce the final executable .EXE file, the linker weaves all of the .OBJ files together, resolving all of the references from one to the other, finally creating an .EXE file.

Each .ASM file is considered a module, and each module contains one or more procedures and possibly some data definitions. When all the declarations are done correctly, all of the modules may freely call one another, and any procedure may refer to any data definition.

The trick, of course, is to get all the declarations right.

Public and External Declarations

If you reference a label in your program (by, say, including a CALL instruction to that label) without defining that label anywhere in the program, the assembler will gleefully give you an error message. (You've probably already experienced this if you've begun writing your own programs in assembly.) In modular programming, you're frequently going to be calling procedures that don't exist anywhere in the program that you're actually working on. How to get past the assembler's watchdogs?

The answer is to declare a procedure external. This works very much like it sounds: The assembler is told that a given label will have to be found outside the program somewhere, in another module. Once told that, that assembler is happy to give you a pass on an undefined label. You've promised the assembler that you'll provide it later, and the assembler accepts your promise and keeps going without flagging the undefined label.

The promise looks like this:

EXTERN ClrScr

Here, you've told the assembler that the label ClrScr represents a procedure and that it will be found somewhere external to the current module. That's all the assembler needs to know to withhold its error message.

And having done that, the assembler's part is finished. It leaves in place an empty socket in your program where the external procedure may later be plugged in. I sometimes think of it as an eyelet where the external procedure will later hook in.

Over in the other module where procedure ClrScr exists, it isn't enough just to define the procedure. An eyelet needs a hook. You have to warn the assembler that ClrScr will be referenced from outside the module. The assembler needs to forge the hook that will hook into the eyelet. You forge the hook by declaring the procedure global, meaning that other modules anywhere in the program may freely reference the procedure. Declaring a procedure global is simplicity itself:

GLOBAL ClrScr

That done, who actually connects the hook and the eyelet? The linker does that during the link operation. After all, why call it a linker if it doesn't link anything? At link time, the linker takes the two .OBJ files generated by the assembler, one from your program and the other from the module containing ClrScr,

and combines them into a single .EXE executable file. (The number of .OBJ files isn't limited to two; you can have almost any number of separately assembled external modules.) When the .EXE file is loaded and run, the program can call ClrScr as cleanly and quickly as though both had been declared in the same source code file.

This process is summarized in Figure 9.2.

Figure 9.2: Connecting globals and externals.

What works for procedures works for data as well, and it can work in either direction. Your program can declare a variable as GLOBAL, and that variable may then be used by any module in which the same variable name is declared as external with the EXTERN directive. I show you how this works in the VIDLIB.ASM library presented a little later in this chapter. Finally, procedure libraries themselves may share data and procedures in any combination, as long as the declarations are handled correctly.

We sometimes say that a program or module containing procedures or variables declared as public exports those items. Also, we say that a program or module that uses procedures or variables that are external to it imports those items.

The Mechanics of Globals and Externals

I've described the source code mechanics of assembly language programs in detail in the last few chapters. External modules are similar to programs. There are two major differences, concerning things that external modules lack:

External modules do not contain a main program and hence have no start address. That is, no label

..start: exists to indicate to the linker that this is the point at which code execution is to begin. External modules are not intended to be run by themselves, so a start address is both unnecessary and (if one were added) a temptation to chaos.

External modules have no stack segment. This is not an absolute requirement (there are few such requirements in assembler work), but for simple assembly language programming it's true enough.

Your stack segment should be defined in your main program module. External modules should have none—they use the one defined by the programs that call them. Recall that in real mode segmented model, there is only one stack in operation at any given time, and that the one you define in your program is used by everything running on your machine—including the operating system—while your program has control.

External modules may have a data segment. If the external is to define a variable that is to be shared by the main program or by other externals, it obviously must have a data segment for that variable to reside in. But less obviously, if the external is to share a variable with another external or with the main program, it must still define a data segment, even if that data segment is empty except for the external declaration.

If a segment (whether a code segment or a data segment) is to export anything, that segment must be declared public. This is done with the PUBLIC keyword, which instructs the linker to make access to the segment possible from outside the module that contains the segment:

SEGMENT data PUBLIC

SEGMENT code PUBLIC

This is easier to demonstrate than to explain. Take a look at the following external module, which is a library containing all of the simple display control procedures introduced in EAT3.ASM:

; Source name

: VIDLIB.ASM

;Compiled name : VIDLIB.OBJ

;Code model: : Real mode segmented model

; Version	: 1.0
; Created date	: 9/12/1999
; Last update	: 9/12/1999
; Author	: Jeff Duntemann
; Description	: A simple example of a separately assembled module
;	containing utility procedures for controlling the
;	PC display. Assembled using NASM 0.98. DOS programs
;	can link to these routines by declaring them EXTERN
;	and then linking the program .OBJ to VIDLIB.OBJ using
;	a linker like ALINK.
[BITS 16]	; Set 16 bit code generation
;	----------------------------BEGIN DATA SEGMENT	|
;		|
;----------------------------	SEGMENT data PUBLIC	|

;Note that the following items are defined externally to this module, and

;for certain routines in this module to function these data items must

;be linked in from a properly assembled external module.

EXTERN CRLF,LRXY

;Note also that there are no memory variables that reside in this data ; segment!

;The data segment must be here so that the EXTERN declarations may be ; made.

;	----------------------------BEGIN CODE SEGMENT	|
;		|
;----------------------------		|

SEGMENT code PUBLIC ; This segment may be accessed externally

;Note that the following items are GLOBAL, and may be accessed by

;external files that declare them EXTERN.

GLOBAL GotoXY,ClrScr,ClrWin,ScrlWin,VIDEO6

GLOBAL Write,Writeln

;---------------------------------------------------------------

; GOTOXY -- Positions the hardware cursor to X,Y

;Last update 9/12/99

;1 entry point:

;	GotoXY:
;
;	Caller must pass:
;	DL: X	value	These are both 0-based; i.e., they	by 80
;	DH: Y	value	assume a screen 24 by 79, not 25

;Action: Moves the hardware cursor to the X,Y position

;loaded into DL and H.

;	---------------------------------------------------------------
GotoXY:		AH,02H	; Select VIDEO service 2: Position cursor
	mov
	mov BH,0		; Stay with display page 0
	int	10H	; Call VIDEO
	ret		; Return to the caller
;---------------------------------------------------------------	CLRSCR	-- Clears or scrolls screens or windows
;
;	Last update 9/12/99
;

;4 entry points:

;ClrScr:

;No values expected from caller

;Action: Clears the entire screen to blanks with 07H as

;the display attribute

;

;ClrWin:

;Caller must pass:

;CH: Y coordinate, upper left corner of window

;CL: X coordinate, upper left corner of window

;DH: Y coordinate, lower right corner of window

;DL: X coordinate, lower right corner of window

;Action: Clears the window specified by the caller to

;blanks with 07H as the display attribute

;

;ScrlWin:

;Caller must pass:

;CH: Y coordinate, upper left corner of window

;CL: X coordinate, upper left corner of window

;DH: Y coordinate, lower right corner of window

;DL: X coordinate, lower right corner of window

;AL: number of lines to scroll window by (0 clears it)

;Action: Scrolls the window specified by the caller by

;the number of lines passed in AL. The blank

;lines inserted at screen bottom are cleared

;to blanks with 07H as the display attribute

;

;VIDEO6:

;Caller must pass:

;CH: Y coordinate, upper left corner of window

;CL: X coordinate, upper left corner of window

;DH: Y coordinate, lower right corner of window

;DL: X coordinate, lower right corner of window

;AL: number of lines to scroll window by (0 clears it)

;	BH: display attribute for blanked lines (07H is "normal")
;	Action: Generic access to BIOS VIDEO service 6. Caller
;		must pass ALL register parameters as shown above
;	---------------------------------------------------------------
ClrScr:			; Upper left corner of full screen
	mov CX,0
	mov DX,word [LRXY] ; Load lower - right XY coordinates into DX
ClrWin:		mov AL,0	; 0 specifies clear entire region
ScrlWin:		mov BH,07H	; "Normal" attribute for blanked line(s)
VIDEO6:		mov AH,06H	; Select VIDEO service 6: Initialize/Scroll
		int 10H	; Call VIDEO
		ret	; Return to the caller
;---------------------------------------------------------------	WRITE	-- Displays information to the screen via DOS
;

;service 9: Print String

;Last update 9/12/99

;	1 entry point:
;
;	Write:
;
;	Caller must pass:
;	DS: The segment of the string to be displayed
;	DX: The offset of the string to be displayed
;	String must be terminated by "$"
;	Action: Displays the string at DS:DX up to the "$" marker
;	---------------------------------------------------------------
Write:		; Select DOS service 9: Print String
	mov AH,09H
	int 21H	; Call DOS
	ret	; Return to the caller

;---------------------------------------------------------------

;WRITELN -- Displays information to the screen via DOS

;	service 9 and issues a newline
;	Last update 9/12/99
;

;1 entry point:

;Writeln:

;Caller must pass:

;DS: The segment of the string to be displayed

;DX: The offset of the string to be displayed

;String must be terminated by "$"

;Action: Displays the string at DS:DX up to the "$" marker

;marker, then issues a newline. Hardware cursor

;will move to the left margin of the following

;line. If the display is to the bottom screen

;line, the screen will scroll.

;Calls: Write

;---------------------------------------------------------------
Writeln:	; Display the string proper through Write
call Write
mov DX,CRLF	; Load address of newline string to DS:DX
call Write	; Display the newline string through Write
ret	; Return to the caller

VIDLIB.ASM has both a code segment and a data segment. Note well that both segments are declared

with the PUBLIC keyword. A common mistake made by beginners is to declare the procedures and variables public, but not the segments that they reside in. Nonobvious it may be, but essential nonetheless: Make your module segments public if they contain any public declarations!

The code segment contains all the procedures declared as GLOBAL. VIDLIB, after all, exists to offer these procedures to programs and other libraries. The data segment, on the other hand, contains only the following statement:

EXTERN CRLF,LRXY

VIDLIB.ASM declares no variables of its own—that is, variables that are defined and exist within VIDLIB. Instead, it uses two variables that are declared and reside within the main program module EAT4.ASM. (EAT4.ASM is identical to EAT3.ASM, save that it has had its procedures removed and declared as external and two of its variables declared public. The program's function is exactly the same as that of EAT3.ASM.)

The preceding EXTERN statement indicates that two variables referenced within the module are to be imported from somewhere. You don't have to specify from where. The names of the variables have to be there, and that's all. Unlike many assemblers, NASM is case-sensitive for variable names and labels (though not for keywords and instruction mnemonics), so be careful of character case.

NASM declines the variable-typing syntax Microsoft uses with MASM and does not require that external variable identifiers be typed. That is, with NASM you don't have to say whether a variable is a byte, a word, a double word, and so on. NASM assumes that the size of the item where it is declared governs its use in all places—and the burden of enforcing that falls on you. If you declare an EXTERN to be a byte (say, with DB) and then try to link that EXTERN to a GLOBAL that is in fact a word, what actually happens may not be what you want.

Dividing a Segment across Module Boundaries

Note that the names of the code segment and data segment in the external module are the same as the names of the code segment and data segment in the main program module. The data segment is named data in both, and the code segment is named code in both. This is not an absolute requirement, but it simplifies things greatly and is a good way to set things up while you're just learning your way around in assembly language. Regardless of the number of external modules that link with your main program, the program as a whole contains only one code segment and one data segment. Until your data requirements and code size get very large, you won't need more than a single code and data segment. There are ways to use multiple code and data segments within a single assembly language program, but that's an advanced topic that I won't be addressing in this book.

As long as the code and data segments are declared with the PUBLIC directive in all the modules sharing the segments, the linker will consider all to be part of the same code and data segments.

Your Main Program Module

So here's our backhanded advertising program, as modified for use with an external display control module:

; Source name	: EAT4.ASM
; Executable name : EAT4.EXE
; Code model:	: Real mode segmented model
; Version	: 1.0
; Created date	: 9/12/1999
; Last update	: 9/12/1999
; Author	: Jeff Duntemann
; Description	: A simple example of a DOS .EXE file programmed for
;	real mode segmented model, using NASM 0.98 and ALINK.
;	This program demonstrates how separately-assembled
;	modules sharing both code and data are linked into a
;	single executable module.

[BITS 16]	; Set 16 bit code generation
;	----------------------------BEGIN CODE SEGMENT	|
;		|
;----------------------------		|

;Note that the following items are external to EAT4.ASM, and must

;be linked from the external file VIDLIB.OBJ. Assemble VIDLIB.ASM

;first to VIDLIB.OBJ before attempting the link.

EXTERN GotoXY,Write,Writeln,ClrScr

SEGMENT code PUBLIC

;SEGMENT SETUP

;

;In real mode segmented model, a program uses three segments, and it must

;set up the addresses in the three corresponding segment registers. This

;is what the ASSUME directive does in MASM; we ASSUME nothing in NASM!

;Each of the three segments has a name (here, code, data, and stack) and

;these names are identifiers indicating segment addresses. It is the

;appropriate segment address that is moved into each segment register.

;Note that you can't move an address directly into a segment register;

;you must first move the address into a general purpose register. Also

;note that we don't do anything with CS; the ..start: label tells the

;linker where the code segment begins.

..start:			; This is where program execution begins:
	mov ax,data		; Move segment address of data segment into AX
	mov ds,ax		; Copy address from AX into DS
	mov ax,stack		; Move segment address of stack segment into AX
	mov ss,ax		; Copy address from AX into SS
	mov sp,stacktop		; Point SP to the top of the stack
	call ClrScr		; Clear the full display
	mov word [TextPos], 0914H ; 0914H = X @ 20, Y @ 9
	mov DX,[TextPos] ; TextPos contains X,Y position values
	call GotoXY		; Position cursor
	mov DX,Eat1		; Load offset of Eat1 string into DX
	call Write		;	and display it
	mov DX,[TextPos] ; Re-use text position variable
	mov DH,10		; Put new Y value into DH
	call GotoXY		; Position cursor
	mov DX,Eat2		; Load offset of Ear2 string into DX
	call Writeln		;	and display it
	mov AH,4CH		; Terminate process DOS service
	mov AL,0		; Pass this value back to ERRORLEVEL
	int 21H		; Control returns to DOS
;----------------------------|
;	BEGIN DATA SEGMENT			|
;----------------------------|
	SEGMENT data PUBLIC
	GLOBAL LRXY,CRLF
LRXY	DW	184FH ; 18H = 24D; 4FH = 79D; 0-based XY of LR screen corner
TextPos DW		0
Eat1	DB	"Eat at Joe's...",'$'
Eat2	DB	"...ten million flies can't ALL be wrong!",'$'
CRLF	DB	0DH,0AH,'$'

;	----------------------------END DATA SEGMENT	|
;		|
;----------------------------		|
;----------------------------	BEGIN STACK SEGMENT	|
;		|
;----------------------------		|

SEGMENT stack stack ;This means a segment of *type* "stack"

;that is also *named* "stack"! Some

;linkers demand that a stack segment

;have the explicit type "stack"

	resb 64	; Reserve 64 bytes for the program stack
stacktop:		; It's significant that this label points to
		; the *last* of the reserved 64 bytes, and
		; not the first!
;	---------------------------- END STACK SEGMENT	|
;		|
;----------------------------		|

EAT4.ASM differs in only a few ways from EAT3.ASM. First of all, the data and code segment declarations now include the PUBLIC directive:

SEGMENT data PUBLIC

SEGMENT code PUBLIC

This is easy to forget but you must keep it in mind: The segments containing imported or exported items as well as the imported or exported items themselves must be declared as public.

Take note of the declaration of two of the variables in the data segment as global:

GLOBAL LRXY,CRLF

This allows external modules to use these two variables. The other variables declared in the main program, Eat1, Eat2, and TextPos, are not declared as public and are inaccessible from external modules. We would say that those three variables are private to the main program module EAT4.ASM.

EAT4.ASM contains no procedure declarations of its own. All the procedures it uses are imported from VIDLIB.ASM, and all are therefore declared as external in the code segment, using this statement:

EXTERN GotoXY,Write,Writeln,ClrScr

Something to keep in mind is that while VIDLIB.ASM exports seven procedures (seven labels, actually, since four are entry points to the ClrScr procedure), EAT4.ASM only imports the four immediately previous. The ClrWin, ScrlWin, and VIDEO6 entry points to procedure ClrScr are declared as global in VIDLIB.ASM, but they are not declared as external in EAT4.ASM. EAT4.ASM only uses the four it imports. The other three are available, but the EAT4.ASM does not call them and therefore does not bother declaring them as external. If you were to expand EAT4.ASM to use one of the three other entry points to ClrScr, you would have to add the entry point to the EXTERN list.

Once all the external and global declarations are in place, your machine instructions may reference procedures and variables across module boundaries as though they were all within the same large program. No special qualifiers have to be added to the instructions. CALL ClrScr is written the same way, whether ClrScr is declared in the main program module or in an external module such as VIDLIB.ASM.

Linking Multiple Modules

The linker hasn't had to do much linking so far. Once you have multiple modules, however, the linker begins to earn its keep. To link multiple modules, you must specify the name of the .OBJ file for each module on the linker command line.

Up until now, the linker command line contained only the name of the main program module:

ALINK EAT3

Now you must add the names of all external modules to the linker command line:

ALINK EAT4 VIDLIB

Pretty obviously, if you forget to name an external module on the linker command line, the linker will not be able to resolve the external references involving the missing .OBJ file, and you will get linker error messages like this one, one for each unresolved external reference:

Undefined symbol 'CLRSCR' in module EAT4.ASM

Batch Files for Building Modular Programs

NASM-IDE was created for use with real mode flat model programs, which cannot, strictly speaking, be modular in nature and assembled with a linker from separately assembled modules. So, if you're going to be doing a lot of work in real mode segmented model, you might consider creating batch files containing the commands you need to issue to the assembler and the linker. This will save you a lot of typing: Instead of typing two full commands on the DOS command line every time you want to build a program, you type only the name of the batch file, and DOS executes any commands in the batch file just as though you had typed them by hand.

Here's a batch file I created (called BUILD4.BAT) to build EAT4.EXE:

NASM16 EAT4.ASM -f obj -o EAT4.OBJ

NASM16 VIDLIB.ASM -f obj -o VIDLIB.OBJ

ALINK EAT4.OBJ VIDLIB.OBJ

It's nothing more than a simple text file containing the three commands you would need to type separately: two for the assembler and a third to link the two assembled files together into the finished

.EXE program. To run this batch program, just type "BUILD4" at the DOS prompt. You'll be able to follow the progress of the three program runs, including any error messages or warnings.

External Module Summary

Here are some points to keep in mind when you're faced with splitting a single program up into a main program and one or more external modules. The assumption here is that the final program will consist of only one code segment and only one data segment. Larger arrangements of segments are possible (especially with multiple code segments) but require additional considerations I won't be covering in this book.

Declare the code segments PUBLIC in all modules, and give them all the same name.

Declare the data segments PUBLIC in all modules, and give them all the same name.

Declare all exported procedures, entry points, and variables as GLOBAL. Put the exported declaration statement inside the segment where the exported items are declared.

Declare all imported procedures, entry points, and variables as EXTERN. Put the imported declaration statement inside the segment where the imported items are to be used. Data is used in the data segment, code in the code segment.

Finally, don't forget to add the names of all external modules to the linker command line in the link step. For example, ALINK MYPROG MODULE1 MODULE2 MODULE3.

If this still seems fuzzy to you, follow VIDLIB.ASM and EAT4.ASM as a model. Certainly it would be worth

beefing up VIDLIB.ASM by adding more screen control procedures.