Chapter 9.2: The emu8086.inc Library
Introduction
Learning Outcomes
Explain how a library file is pulled into the source and where the assembler looks for it.
Show what macros such as PUTC, GOTOXY, PRINT and PRINTN expand to.
Use the ready-made procedures (number input/output, string printing) with DEFINE_… and CALL.
Write programs that read numbers, compute with them and lay out the screen using library macros and procedures.
The Library and INCLUDE
A Library of Common Functions
- Frequently used routines come ready-made, so you don't have to write them yourself.
- Routines defined in other files are brought in with the INCLUDE directive.
- To use anything in
emu8086.inc, putinclude 'emu8086.inc'at the top of the source file. - The library covers the screen, keyboard and number routines most emu8086 programs need.
INCLUDE is a directive: it generates no machine code, it just inserts text at assembly time.
The Library and INCLUDE
The Source After INCLUDE
; in place of the include line: PUTC MACRO char ; template: 0 bytes ... ENDM GOTOXY MACRO col, row ... ENDM DEFINE_SCAN_NUM MACRO ... ; procedure template ENDM ; the program itself: ORG 100h PUTC 'A' ; 8 bytes here RET
- The assembler replaces the
includeline with the file's text, then assembles the result as one source. - A macro definition is only a template: an unused macro adds no bytes at all.
- Code appears where the macro is used:
PUTC 'A'expands into 8 bytes of instructions. - Procedures are wrapped in macros too (
DEFINE_…): without its DEFINE_ line, a procedure never enters the program. - Including the whole library costs nothing: program size depends only on the macros you use and the procedures you define.
The Library and INCLUDE
What's in the Library?
| Macro | Purpose |
|---|---|
PUTC char | print one character |
GOTOXY col, row | position the cursor |
PRINT string | print a string |
PRINTN string | print a string + newline |
CURSOROFF | hide the cursor |
CURSORON | show the cursor |
| Procedure | Purpose |
|---|---|
PRINT_STRING | print the string at DS:SI |
PTHIS | print the string after the CALL |
GET_STRING | read a string from the keyboard |
CLEAR_SCREEN | clear the screen |
SCAN_NUM | read a number → CX |
PRINT_NUM | print AX as signed |
PRINT_NUM_UNS | print AX as unsigned |
CALL.Macros
Screen Macros
| Macro | What it does | Under the hood |
|---|---|---|
PUTC char | Prints one ASCII character at the cursor. | INT 10h, AH = 0Eh |
GOTOXY col, row | Moves the cursor to the given column and row. | INT 10h, AH = 02h |
PRINT string | Prints the given string. | 0Eh, one character at a time |
PRINTN string | Like PRINT, then adds CR + LF (13, 10) to start a new line. | 0Eh, one character at a time |
CURSOROFF | Turns the text cursor off (hides it). | INT 10h, AH = 01h |
CURSORON | Turns the text cursor back on. | INT 10h, AH = 01h |
PUTC 65, PUTC 'B', PUTC AL.Macros
What Do PUTC and GOTOXY Expand To?
PUTC 'A'
PUSH AX ; save AX MOV AL, 'A' ; argument MOV AH, 0Eh ; teletype INT 10h POP AX ; restore AX
5 instructions, 8 bytes. Registers are preserved; the calling code is unaffected.
GOTOXY 10, 5
PUSH AX PUSH BX PUSH DX MOV AH, 02h ; set cursor MOV DH, 5 ; row MOV DL, 10 ; column MOV BH, 0 ; page 0 INT 10h POP DX POP BX POP AX
Macros · Step through the code
Code Trace: PRINT, GOTOXY, PUTC
include: macro definitions are inserted at assembly time; no code is generated.
ORG 100h: a COM program starts at 100h.
PRINT: 12 characters printed (columns 0–11); the cursor is at column 12.
GOTOXY 10, 5: the cursor moves to column 10, row 5. Nothing is printed.
PUTC 65: 65 = 41h = 'A' is printed; the cursor moves to column 11.
PUTC 'B': a character literal works too.
RET: return to DOS. END just tells the assembler the source ends here.
include emu8086.inc ORG 100h PRINT 'Hello World!' GOTOXY 10, 5 PUTC 65 ; 65 - is an ASCII code for 'A' PUTC 'B' RET ; return to operating system. END ; directive to stop the compiler.
Macros
PRINTN and the Cursor Macros
PRINT 'a' then PRINT 'b' → ab on one line.
PRINTN 'a' then PRINT 'b' → a and, on the next line, b.
CR (13) moves the cursor to the start of the line, LF (10) moves it down a line; a newline needs both.
They use INT 10h, AH = 01h (cursor shape): CH = start, CL = end scan line.
Setting bit 5 of CH hides the cursor; CURSORON restores the normal shape.
Handy for hiding the blinking cursor on game or menu screens.
PRINTN 'Full name:' ; print, then newline CURSOROFF GOTOXY 30, 12 PRINT 'Hello' CURSORON
Macros
Control Characters with PUTC
| Code | Name | PUTC effect |
|---|---|---|
07h | BEL | A short beep from the speaker; the cursor doesn't move. |
08h | BS (backspace) | Cursor steps left; it does not erase the character. No effect in column 0. |
0Ah | LF (line feed) | Cursor moves down a row; the column stays. On the last row the screen scrolls up one line. |
0Dh | CR (carriage return) | Cursor returns to column 0 of the same row; the text stays put. |
The 13, 10 pair that PRINTN appends combines both moves: line start, then down a line. In reverse order (10, 13) the cursor ends up in the same place.
To erase a character, use the triple PUTC 8, PUTC ' ', PUTC 8: step left, overwrite with a space, step left again. The library procedures that handle backspace fix the screen the same way.
Macros · Step through the code
Code Trace: CR and LF Separately
AH = 0Eh is loaded only once here; INT 10h prints the 'a' in AL and moves the cursor right to (1, 0).
'b' is printed; cursor at (2, 0).
LF alone (10): the cursor drops one row but stays in column 2: (2, 1).
'c' lands in column 2 of the next row: the text “staircases”.
CR alone (13): the cursor returns to the start of the same row, (0, 1). The c is not erased.
'd' goes into column 0. The screen shows “ab” with “d c” below. A proper newline needs both 13 and 10.
ORG 100h MOV AH, 0Eh ; teletype MOV AL, 'a' INT 10h MOV AL, 'b' INT 10h MOV AL, 10 ; LF only INT 10h MOV AL, 'c' INT 10h MOV AL, 13 ; CR only INT 10h MOV AL, 'd' INT 10h RET
Macros
Line Wrap and Scrolling
- After writing column 79, service 0Eh moves the cursor to the start of the next row by itself, so PRINT continues a long string without a break.
- If the cursor has to move down from the last row (24), the whole screen scrolls up one row: the top row disappears and a blank row appears at the bottom.
- Example:
GOTOXY 75, 24thenPRINT 'Welcome'. “Welco” fills columns 75–79; for “me” the screen scrolls. In the end “Welco” is on row 23, “me” at the start of row 24, and the cursor at (2, 24). - GOTOXY and PUTC do no bounds checking: keep positions within 0–79 (column) and 0–24 (row).
Macros
Demo: The GOTOXY Screen
Click a cell on the 80 × 25 text screen to see the macro that moves the cursor there, the BIOS registers it sets and the matching video memory address.
Macros · Step through the code
Code Trace: Two Digits with AAM and PUTC
AL = 58 (3Ah). Goal: print it as two decimal digits.
AAM divides AL by 10: AH = 5 (tens), AL = 8 (ones). Only AL is divided, so the number must be 0–99.
ADD AX, 3030h adds 30h to both bytes at once: AH = '5' (35h), AL = '8' (38h).
PUTC AH expansion: first AX (3538h) is pushed, SP = FFFCh.
MOV AL, AH and MOV AH, 0Eh: AX = 0E35h; the ones digit is gone from the register. INT 10h prints 5.
POP AX: AX = 3538h is back; '8' is in AL again.
PUTC AL expands the same way (MOV AL, AL is harmless). The screen shows 58; AX is still 3538h. Because PUTC preserves AX, both digits print without copying them to another register.
ORG 100h MOV AL, 58 AAM ; AH = 5, AL = 8 ADD AX, 3030h ; '5', '8' PUSH AX ; PUTC AH expanded MOV AL, AH MOV AH, 0Eh INT 10h POP AX ; AX back: 3538h PUSH AX ; PUTC AL expanded MOV AL, AL MOV AH, 0Eh INT 10h POP AX RET
Procedures
Using Procedures: DEFINE_ and CALL
include 'emu8086.inc' ORG 100h ... CALL print_num ; use ... RET DEFINE_PRINT_NUM ; define DEFINE_PRINT_NUM_UNS END
- Each procedure must be defined once, before the
ENDdirective, with its ownDEFINE_…macro. - A
DEFINE_…macro expands the procedure's code right where it appears. - Definitions usually go between
RETandEND. Every DEFINE_ macro starts with aJMPover the body, so execution never falls into the procedure. - In the code you
CALLa procedure by name, written in lower case (print_num). PRINT_NUMcallsPRINT_NUM_UNSinternally, so both must be defined.
Procedures
Input and Output Registers
| Procedure | Input | Output | Notes |
|---|---|---|---|
PRINT_STRING | DS:SI = string address | — | string must end in 0 |
PTHIS | string right after the CALL | — | advances the return address itself |
GET_STRING | DS:DI = buffer, DX = size | 0-terminated string in the buffer | at most DX − 1 characters |
CLEAR_SCREEN | — | — | cursor goes to (0, 0) |
SCAN_NUM | keyboard | CX (signed) | old value of CX is lost |
PRINT_NUM | AX (signed) | — | PRINT_NUM_UNS must be defined too |
PRINT_NUM_UNS | AX (unsigned) | — | 0 … 65,535 |
PUSH CX … POP CX).Procedures
String Procedures
- Prints a null-terminated (0) string at the cursor.
- Takes the string address from DS:SI.
- Defined by:
DEFINE_PRINT_STRING.
LEA SI, msg CALL print_string msg DB 'Hello', 0
- Prints a null-terminated string.
- Takes the address from the stack: the string is placed right after the
CALL. - Defined by:
DEFINE_PTHIS.
CALL pthis DB 'Hello', 0 ; execution resumes here
Procedures
Ways to Print a String
| Method | Where is the string? | Terminator | How is the address passed? | Best for |
|---|---|---|---|---|
PRINT 'text' | inside the code (macro expansion) | 0 (added by the macro) | handled by the macro (CS:SI) | a constant message printed once |
PRINT_STRING | in the data area | 0 | DS:SI | strings printed in several places or built at run time |
PTHIS | right after the CALL | 0 | return address on the stack | many short constant messages |
INT 21h, AH = 09h | in the data area | '$' | DS:DX | DOS programs without the library |
A '$'-terminated string cannot contain '$', and a 0-terminated one cannot contain a 0 byte: the string ends there.
The buffer GET_STRING fills ends in 0, so print it with PRINT_STRING. With AH = 09h, memory is dumped to the screen until a '$' turns up.
Procedures
GET_STRING and CLEAR_SCREEN
- Reads a null-terminated string from the user.
- The string is stored in the buffer at DS:DI.
- DX = buffer size; a 0 is appended, so at most DX − 1 characters are read.
- Enter ends the input.
- Defined by:
DEFINE_GET_STRING.
- Clears the screen and moves the cursor to the top-left corner (0, 0).
- Defined by:
DEFINE_CLEAR_SCREEN.
LEA DI, buf ; buffer MOV DX, 20 ; size CALL get_string CALL clear_screen LEA SI, buf CALL print_string RET buf DB 20 DUP(0)
Procedures · Step through the code
Code Trace: GET_STRING Logic (DX = 4)
A simplified GET_STRING read loop (the library version also handles backspace). DI = buffer, DX = 4 bytes; the user will type “Ece”.
4 > 1: room for a character plus the final 0 → JBE is not taken.
INT 21h, AH = 01h: 'E' is read and echoed. Not Enter (13) → JE is not taken.
'E' goes into the buffer; DI advances, room left DX = 3.
Second pass: 'c' is read and stored at buf+1; DX = 2.
Third pass: 'e' goes to buf+2; DX = 1.
DX = 1: room only for the final 0 → JBE done. Further keys are not read: at most DX − 1 = 3 characters.
The string gets its 0 terminator: buffer 'E','c','e',0 → ready for PRINT_STRING.
LEA DI, buf ; buffer address MOV DX, 4 ; buffer size get_key: CMP DX, 1 ; keep 1 byte for the 0 JBE done MOV AH, 01h INT 21h ; AL = key (echoed) CMP AL, 13 ; Enter? JE done MOV [DI], AL ; store in buffer INC DI DEC DX JMP get_key done: MOV BYTE PTR [DI], 0 RET buf DB 4 DUP(?)
Procedures
GET_STRING Details
The library version reads keys without echo (INT 16h, AH = 0) and echoes only the characters it stores, so rejected keys leave no trace on screen.
After DX − 1 characters, further letters are ignored; the procedure waits for Enter or backspace. Unlike the simplified trace, it does not stop by itself.
If the buffer holds a character, DI steps back and 8, ' ', 8 is printed. On an empty buffer the key is ignored: the cursor never moves left of the input start.
It is not stored; a 0 goes in its place and the procedure returns. With DX ≤ 1 nothing is read at all, since there is room only for the final 0.
PUTC 13 and PUTC 10 to move down.Procedures · Step through the code
Code Trace: Reading with Backspace
Buffer buf is 6 bytes; DI points to its first byte. The user will press A, b, backspace, c and Enter.
INT 16h: AL = 'A' (41h); the key is read without echo, so the screen is still empty. Neither Enter (13) nor backspace (8): store.
'A' is stored and DI advances; then the echo: A on screen.
Same path for 'b': buffer A, b; DI = buf+2; the screen shows Ab.
Backspace: AL = 08h. CMP AL, 8 → ZF = 1, JNE store is not taken.
DI is not at the buffer start (buf+2 ≠ buf): there is a character to erase. DEC DI frees b's byte; it stays in memory but is no longer part of the string.
On screen, the triple: 8 moves the cursor left, a space overwrites b, the second 8 moves left again. Only A remains.
'c' goes into b's old byte: buffer A, c; the screen shows Ac.
Enter: JE done; a 0 is written where DI points. Buffer 'A', 'c', 0: the erased letter is gone.
ORG 100h LEA DI, buf get_key: MOV AH, 0 INT 16h ; AL = key (no echo) CMP AL, 13 ; Enter? JE done MOV AH, 0Eh CMP AL, 8 ; backspace? JNE store CMP DI, OFFSET buf JE get_key ; nothing to erase DEC DI INT 10h ; 8: cursor left MOV AL, ' ' INT 10h ; blank the char MOV AL, 8 INT 10h ; left again JMP get_key store: MOV [DI], AL INC DI INT 10h ; echo JMP get_key done: MOV BYTE PTR [DI], 0 RET buf DB 6 DUP(?)
Procedures
Number Procedures
| Procedure | What it does | Input / output | Defined by |
|---|---|---|---|
SCAN_NUM | Reads a multi-digit signed number from the keyboard (ends with Enter). | output: CX | DEFINE_SCAN_NUM |
PRINT_NUM | Prints the signed number in AX in decimal. | input: AX | DEFINE_PRINT_NUM + DEFINE_PRINT_NUM_UNS |
PRINT_NUM_UNS | Prints the unsigned number in AX. | input: AX | DEFINE_PRINT_NUM_UNS |
16 bits: −32,768 … 32,767
16 bits: 0 … 65,535
FFE7h = −25 (signed) = 65,511 (unsigned)
Procedures · Step through the code
Code Trace: SCAN_NUM Logic (input 307)
The core of SCAN_NUM: digits are read left to right, result = result × 10 + digit (the library version also handles a minus sign and overflow). CX = 0.
INT 21h, AH = 01h: key '3', AL = 33h; the character is echoed.
Not Enter. SUB AL, '0': 33h − 30h = 3.
CBW sets AX = 0003h; XCHG swaps: AX = old result (0), CX = digit (3).
MUL BX: 0 × 10 = 0; ADD CX, AX → CX = 3.
'0' is read: digit 0; after XCHG, AX = 3, CX = 0.
3 × 10 = 30 (1Eh) → CX = 30 + 0 = 30.
'7' is read: digit 7 into AX (CBW); the result 30 is still in CX.
XCHG: AX = 30, CX = 7. 30 × 10 = 300 (012Ch) → CX = 300 + 7 = 307 = 0133h.
Enter: AL = 0Dh = 13 → ZF = 1, JE done is taken.
As in SCAN_NUM, the result is in CX: 0133h = 307.
ORG 100h XOR CX, CX ; result = 0 get_key: MOV AH, 01h INT 21h ; AL = key (echoed) CMP AL, 13 ; Enter? JE done SUB AL, '0' ; ASCII → digit CBW ; AX = digit XCHG AX, CX ; AX=result, CX=digit MOV BX, 10 MUL BX ; AX = result × 10 ADD CX, AX ; CX = result×10 + digit JMP get_key done: RET
Procedures
What SCAN_NUM Checks
- The
-key sets a sign flag; on Enter, if the flag is set,NEG CXis applied. - A non-digit key is erased from the screen (8, ' ', 8) and ignored.
- Backspace drops the last digit: CX ← CX / 10.
- If the number would not fit in 16 bits (the × 10 or the addition overflows), the last digit is rejected.
- Enter is echoed too: the cursor returns to the line start (CR) but does not move down. That is why the PTHIS string in the example program starts with 13, 10.
| Input | CX | PRINT_NUM |
|---|---|---|
| 307 | 0133h | 307 |
| -25 | FFE7h | -25 |
| 12a3 | 007Bh | 123 |
| 40000 | 9C40h | -25536 |
| 70000 | 1B58h | 7000 |
| -40000 | 63C0h | 25536 |
Procedures · Step through the code
Code Trace: PRINT_NUM_UNS Logic (AX = 1205)
Equivalent code with the same output (the library version divides by 10000, 1000, …). AX = 1205 = 04B5h, divisor BX = 10.
DIV BX: DX:AX / 10 → AX = 120, remainder DX = 5. The last digit is pushed, CX = 1.
AX ≠ 0 → loop again: 120 / 10 = 12, remainder 0 pushed; CX = 2.
12 / 10 = 1, remainder 2 pushed; CX = 3.
1 / 10 = 0, remainder 1 pushed; CX = 4 digits.
OR AX, AX: AX = 0 → ZF = 1, JNZ is not taken. The most significant digit (1) is on top of the stack.
POP AX = 1; + '0' = 31h; INT 10h prints '1'. LOOP: CX = 3.
Next digit 2 → '2'. CX = 2.
0 → '0'. CX = 1.
5 → '5'. CX = 0, the loop ends; SP is back at FFFEh. The screen shows 1205.
ORG 100h MOV AX, 1205 ; number to print MOV BX, 10 XOR CX, CX ; digit counter divide: XOR DX, DX DIV BX ; AX=quot, DX=rem PUSH DX ; push the digit INC CX OR AX, AX ; quotient 0? JNZ divide emit: POP AX ; MSD first ADD AL, '0' MOV AH, 0Eh INT 10h LOOP emit RET
Procedures
The Library's Method: A Shrinking Divisor
- The divisor starts at 10,000 and is divided by 10 each pass; printing stops when it reaches 0.
- The quotient (0–9) is one digit, printed after
ADD AL, 30h; the remainder becomes the number for the next pass. - A flag (CX = 1) skips leading zeros; once the first digit is printed the flag is cleared and inner zeros are printed.
- A separate branch prints '0' directly when AX = 0.
- Since 65,535 ÷ 10,000 = 6, the quotient always fits in AL.
| Divisor | Number | Step | Screen |
|---|---|---|---|
| 10000 | 3007 | number < divisor, no digit yet: skip | — |
| 1000 | 3007 | 3007 ÷ 1000 = 3, rem. 7 | 3 |
| 100 | 7 | 7 ÷ 100 = 0, rem. 7 | 30 |
| 10 | 7 | 7 ÷ 10 = 0, rem. 7 | 300 |
| 1 | 7 | 7 ÷ 1 = 7, rem. 0 | 3007 |
Procedures · Step through the code
Code Trace: PRINT_NUM and the Minus Sign
AX = −25, which is FFE7h in two's complement. The code shown is equivalent to the library's PRINT_NUM.
CALL print_num: return address 0106h is pushed, SP = FFFCh.
PUSH AX saves the caller's value. OR AX, AX leaves the value unchanged but sets the flags: MSB is 1 → SF = 1.
JNS is not taken (the number is negative). NEG AX: 0 − FFE7h = 0019h = 25, the absolute value.
PUTC '-' expansion: AX is pushed, '-' is printed, AX = 0019h is restored.
CALL print_num_uns: the digits of 25 are printed (same digit loop as in the PRINT_NUM_UNS trace; the procedure saves the registers it uses).
POP AX: AX is FFE7h again. The number is still in AX after printing.
Both RETs: SP = FFFEh. The library's PRINT_NUM also prints '0' directly when AX = 0.
ORG 100h MOV AX, -25 ; AX = FFE7h CALL print_num RET print_num PROC PUSH AX OR AX, AX ; SF = sign bit JNS positive NEG AX ; AX = 0019h PUSH AX ; PUTC '-' expanded MOV AL, '-' MOV AH, 0Eh INT 10h POP AX positive: CALL print_num_uns POP AX ; AX = FFE7h again RET print_num ENDP
Procedures
Extracting Digits: Two Methods
| Criterion | Stack method (divide by 10, push, pop in reverse) | Shrinking divisor (10,000, 1000, …) |
|---|---|---|
| Divisions | one per digit | up to five, plus one each to shrink the divisor |
| Stack use | 2 bytes per digit | only the saved registers |
| Leading zeros | never appear | skipped with a flag |
Fixed width (00042) | needs extra code | free: just drop the flag |
| Other bases | use divisor 2, 8 or 16; in base 16, digits above 9 become 'A'–'F' | the divisor sequence depends on the base (4096, 256, 16, 1 for base 16) |
| Output order | digits go to the stack, then to the screen in reverse | left to right, as computed |
Procedures
Demo: PRINT_NUM and PRINT_NUM_UNS
Enter a value for AX (decimal, negative, or hex with an h suffix) to see what each procedure prints.
Example Program · Step through the code
Code Trace: Read and Print a Number
LEA SI, msg1: SI ← offset of the msg1 string.
CALL print_string: the return address is pushed (SP = FFFCh); the procedure prints the string at DS:SI up to the 0.
CALL scan_num: the user types -25 and presses Enter; the keys are echoed.
On return: CX = FFE7h = −25 (two's complement). SP is back at FFFEh.
MOV AX, CX: PRINT_NUM expects the number in AX.
CALL pthis: the “return address” it pushes is really the address of the string on the next line.
PTHIS prints the string: 13, 10 (newline) and “You have entered: ”. Then it moves the return address past the 0.
Execution returns past the string. CALL print_num: AX = FFE7h is printed as signed.
RET: 0000h is popped into IP, SP = 0000h; back to DOS. Lines 11–17 are data and procedure definitions, never executed in this flow.
include 'emu8086.inc' ORG 100h LEA SI, msg1 ; ask for the number CALL print_string ; CALL scan_num ; get number in CX. MOV AX, CX ; copy the number to AX. CALL pthis ; print the following string: DB 13, 10, 'You have entered: ', 0 CALL print_num ; print number in AX. RET ; return to operating system. msg1 DB 'Enter the number: ', 0 DEFINE_SCAN_NUM DEFINE_PRINT_STRING DEFINE_PRINT_NUM DEFINE_PRINT_NUM_UNS ; required for print_num. DEFINE_PTHIS END ; directive to stop the compiler.
Example Program
How PTHIS Works
In memory, the string bytes follow CALL pthis directly; the string ends in 0.
CALL pushes the address of the “next instruction”, which is really the address of 0Dh, the first byte of the string.
PTHIS reads that address from the stack and prints bytes from there up to the 0.
The address on the stack is replaced by the one just past the 0 byte: it now points to CALL print_num.
RET: the CPU skips the string and continues at CALL print_num. The data is never executed as code.
JMP.Example Program
Example: Adding Two Numbers
include 'emu8086.inc' ORG 100h CALL scan_num ; 1st number → CX MOV BX, CX ; save it PUTC 13 PUTC 10 ; next line CALL scan_num ; 2nd number → CX PUTC 13 PUTC 10 MOV AX, BX ADD AX, CX ; signed sum JO overflow CALL print_num RET overflow: PUTC '?' RET DEFINE_SCAN_NUM DEFINE_PRINT_NUM DEFINE_PRINT_NUM_UNS END
- The second SCAN_NUM also returns in CX, so the first number is saved in BX.
- Enter only returns to the line start;
PUTC 13,PUTC 10move the next input down a line. JOcatches signed overflow: 30,000 + 5000 = 35,000 exceeds the 16-bit signed range (32,767).
| Inputs | Screen (last line) |
|---|---|
| 120, -45 | 75 |
| -7, -8 | -15 |
| 30000, 5000 | ? |
Example Program
Example: A Framed Title
include 'emu8086.inc' ORG 100h CALL clear_screen GOTOXY 10, 2 CALL hline GOTOXY 10, 3 PRINT '| HEADER |' GOTOXY 10, 4 CALL hline GOTOXY 0, 6 ; cursor below RET hline PROC ; +----------+ PUTC '+' MOV CX, 10 dash: PUTC '-' LOOP dash PUTC '+' RET hline ENDP DEFINE_CLEAR_SCREEN END
- Our own procedure (
hline) works alongside the library macros; it is defined after RET. - The
PUTC '-'inside the loop is expanded once and runs 10 times: the code is not copied 10 times. - PUTC uses only AX and restores it; it never touches CX, so the loop counter is safe.
Example Program
Common Mistakes
CALL scan_num without DEFINE_SCAN_NUM: the assembler reports an undefined label.
Every DEFINE_ macro starts with JMP skip_proc_…, so even at the top of the program the CPU skips the body. The usual place is still between RET and END.
PRINT_STRING and PTHIS print until they see a 0; without one, random memory bytes spill onto the screen.
Procedures return results in specific registers (SCAN_NUM → CX). Don't assume any other register is preserved unless the documentation says so.
Example Program
Number and Screen Mistakes
SCAN_NUM returns in CX. Forget MOV AX, CX before PRINT_NUM and the stale AX is printed.
AX = 40,000 (9C40h) shows up as −25536 with PRINT_NUM. Unsigned values that can exceed 32,767 need PRINT_NUM_UNS.
After SCAN_NUM the cursor is at the start of the input line, so the next output overwrites the number. Put CR + LF in between.
GOTOXY 5, 10 moves the cursor to column 5, row 10, not the other way round.
GOTOXY AL, AH: the macro loads 02h into AH first, so the row becomes 02h. Move the position into other registers first.
If DX exceeds the real buffer size, GET_STRING overwrites the variables that follow the buffer.
Lab · library macros and procedures
Lab: The emu8086.inc Library
Summary
Summary
include 'emu8086.inc': searched in the source folder first, then in the Inc folder.
PUTC, GOTOXY (col, row), PRINT, PRINTN, CURSOROFF, CURSORON: built on INT 10h, expanded wherever they are used.
Define with DEFINE_… before END, call with CALL. Input/output registers: SI, DI, DX, CX, AX.
SCAN_NUM → CX (signed); PRINT_NUM prints AX as signed, PRINT_NUM_UNS as unsigned.
The string sits right after the CALL; the procedure moves the return address past it.
PRINT embeds the string in the code; PRINT_STRING and PTHIS print 0-terminated strings with one copy of the code; GET_STRING ends its buffer with 0.
Summary
Exercises
- With macros, print “CENTER” mid-screen (column 35, row 12).
- Read two numbers from the user and print their sum.
- If
PRINTis used 10 times, how many copies of the strings and loop code does the program hold? Compare with PRINT_STRING. - What do PRINT_NUM and PRINT_NUM_UNS print when AX = 8000h?
- What happens if
DEFINE_PTHISis placed right belowORG 100h? - Read the user's name with GET_STRING and print “Hello, name!”.
Hints / answers
GOTOXY 35, 12, thenPRINT 'CENTER',RET.CALL scan_num→MOV BX,CX→PUTC 13/10→CALL scan_num→MOV AX,BX,ADD AX,CX,CALL print_num; DEFINE_SCAN_NUM, DEFINE_PRINT_NUM, DEFINE_PRINT_NUM_UNS.- PRINT: 10 copies (each with its own string and loop). PRINT_STRING: one loop, 10 strings + 10 × (LEA + CALL).
- PRINT_NUM: −32768, PRINT_NUM_UNS: 32768.
- It still works: the macro's
JMP skip_proc_pthisskips the body; the only cost is one extra JMP. LEA DI,buf / MOV DX,20 / CALL get_string,PUTC 13/10,PRINT 'Hello, ',LEA SI,buf / CALL print_string,PUTC '!'.
Summary
References
- emu8086 help: the “emu8086.inc — library of common functions” and “Macros” pages.
- The
Inc/emu8086.incfile in the emu8086 installation (source code of the macros and procedures). - B. B. Brey, The Intel Microprocessors, 8th ed., Pearson, 2009 — procedures and macros.
- A. S. Tanenbaum, Modern Operating Systems, 3rd ed., Pearson, 2008.