Macros and emu8086.inc: PUTC, PRINT and Friends

Beginner Emu8086 programs often start with a line that looks like magic: include 'emu8086.inc'. It is not magic. It pulls in a file of macro definitions, small text templates that the assembler expands before assembling your program. This tutorial explains the macros you will actually use and shows you how to write one of your own. It follows the Hello World tutorial, and Emu8086 setup is in the install guide.

The three macros you will use most

  • PUTC prints the single character in AL.
  • PRINT 'text' prints a string of text.
  • PRINTN prints a new line.

A complete program using all three

This program prints a word, a new line, and then a single character. It needs the include line, because without it the assembler has no definition of PRINT or PUTC and will report them as unknown symbols. That error message is the usual sign that the include line was deleted by accident.

include 'emu8086.inc'
ORG 100h

PRINT 'Hello'
PRINTN
MOV AL, '!'
PUTC
RET

What you should see

The emulator window should show Hello on one line and ! on the next. Note the order in the character case: PUTC reads AL, so AL must be loaded after the PRINTN, not before, if any macro in between changes AL. When a character prints wrong, check what AL held at the exact moment PUTC ran.

Defining your own macro

A macro is defined once and expanded everywhere it is used. The definition below prints a fixed greeting. Every time SAY_HI appears in the code, the assembler replaces it with the two macro lines before assembling. That is the key difference from a subroutine: a macro costs no CALL at run time, but it does make the assembled program longer each time it is used.

include 'emu8086.inc'
ORG 100h

SAY_HI
SAY_HI
RET

SAY_HI MACRO
PRINT 'Hi from a macro!'
PRINTN
ENDM

What you should see

The greeting should appear twice, on two lines. If it appears only once, check that the macro definition comes after the code that uses it in your file layout, or that you have not placed the definition after the final RET in a way that the assembler treats as unreachable data; the layout above, definition after the main code, is the standard Emu8086 arrangement.

Macros are not subroutines

A subroutine, covered in subroutines and the stack, exists once in the assembled program and is jumped to. A macro exists only in the source: the assembler copies its body to every use. Use macros for short, repeated text output and similar conveniences. Use subroutines for longer logic that you want to keep in one place and debug in one place.

One rule to remember

Only include emu8086.inc when your program actually uses one of its macros. Including it in a program that uses none of them is harmless but pointless, and it can confuse a reader who goes looking for a macro call that never comes. Conversely, never delete the include line from a program that uses PRINT, PUTC or PRINTN.

Next steps

Input and output without macros are covered in INT 21h input and output, and the subroutine alternative is subroutines and the stack. The opcode reference lists the underlying instructions, and the home page is the series index.

Similar Posts