Macro declarations and calls

Macro declarations give a name to a block of code. This block is called the macro body. A macro call is indicated by the use of a macro name as an instruction. The assembler textually inserts the macro body wherever the macro is called in an assembly language program. For example, consider the following macro declaration

	MACRO foo
	    add x, y
	    load z
	ENDM

Assume that the declaration appears in a file that includes the following 3 instruction statements:

	add a, b
	foo ; macro call
	store b

In this case, the text that is assembled is the following:

	add a, b
	add x, y
	load z
	store b

Macros can also have parameters, which get textually replaced by the arguments in the macro call. For example, consider the following variation on the macro foo, which has one parameter n:

	MACRO foo n
	    add x, n
	    load z
	ENDM

Assume that this declaration appears in a file that includes the following 3 instruction statements:

	add a, b
	foo a ; macro call with argument a
	store b

In this case, the text that is assembled is the following:

	add a, b
	add x, a
	load z
	store b

You can include arbitrary instructions inside a macro body, including labeled statements, data pseudoinstructions, and calls to other macros. Note that macro declarations are always local, which means that these macros can only be called in the file in which they are defined. Therefore, it is often useful to put the macro definitions in files that are then included (using the .include directive) in all files in which you wish to make macro calls.

Note: Because of the fact that macro calls are assembled via textual substitution, labels in macro bodies must be treated specially. To understand the problem, consider a macro body in which one line has a label L and suppose the macro is called twice in one file. If straight text substitution were performed, the label L would appear on two lines of that file, violating the necessary uniqueness of all labels in a program. Therefore, before the textual substitution of every macro call, the label and all references to the label in the macro body are automatically replaced with a unique label by the assembler. For this reason, the label cannot be referenced outside the macro body.