





						   Macro Directives



		 8.1  Introduction

		 This chapter explains how to create and use macros
		 in  your  source  files.   There are the following
		 macro directives:

		      MACRO		  LOCAL		      PURGE
		      REPT	       IRP	  IRPC	      EXITM
		      ENDM

		 The MACRO directive lets you write a  named  block
		 of  source  statements, then use that name in your
		 source	file to	 represent  the	 statements.   MASM
		 automatically	replaces each occurrence of a macro
		 name  with  the  statements  given  in	 the  macro
		 definition.   This  means you can place a block of
		 statements any	 where	in  your  source  file	any
		 number	 of  times by simply defining it once, then
		 giving	the name where	you  need  it.	 The  LOCAL
		 directive  lets  you  define  unique  labels for a
		 macro,	and the	PURGE directive	 lets  you  control
		 the macros you	define.

		 The REPT, IRP,	and IRPC directives  also  let	you
		 create	 contiguous  blocks of repeated	statements.
		 You control the number	of times the statements	are
		 repeated.   You  can repeat them a given number of
		 times,	once for each parameter	in a list, or  once
		 for each character in a string.

		 The macro directives use a special  set  of  macro
		 operators:

		      &	      Ampersand
		      ;;      Double semicolon
		      !	      Exclamation mark
		      %	      Percent sign

		 When used in a	macro definition,  these  operators
		 carry out special control operations, such as text



								8-1


















	      XENIX Macro Assembler Reference Manual



	      substitution.


	      8.2  MACRO and ENDM Directives

	      Syntax

		   name	   MACRO   [dummy-parameter,,, ]
			   statements		   ENDM

	      The MACRO	 and  ENDM  directives	create	a  macro
	      having  the  given  name	and containing the given
	      statements.

	      The name must be a valid name and	must be	 unique.
	      It is used in the	source file to invoke the macro.
	      The dummy-parameter is  a	 name  that  acts  as  a
	      placeholder  for	values to be passed to the macro
	      when it is called.  Any number of	dummy parameters
	      can  be  given, but they must all	fit on one line.
	      If you give more than one, you must separate  them
	      with  commas  (,).   The	statements are any valid
	      MASM statements, including other MACRO directives.
	      Any  number  of statements can be	used.  The dummy
	      parameter	can be used any	number of times	in these
	      statements.

	      A	macro is ``called'' any	time  the  macro's  name
	      appears in a source file (macros names in	comments
	      are ignored). MASM copies	the  statements	 in  the
	      macro  definition	 to the	point of call, replacing
	      any dummy	 parameters  in	 these	statements  with
	      values  passed  in the call.  Dummy parameters are
	      replaced	according  to	their	order	in   the
	      definition.   Thus,  the dummy parameter occupying
	      the  fourth  parameter  position	in   the   macro
	      definition   is  replaced	 by  the  fourth  actual
	      parameter	in the macro call.

	      Macro definitions	can be	nested.	  This	means  a



	      8-2


















						   Macro Directives



		 macro	can  be	defined	within another macro.  MASM
		 does not  process  nested  definitions	 until	the
		 outer	macro  has  been  called, therefore, nested
		 macros	cannot be called until the outer macro	has
		 be called at least once.  Macro definitions can be
		 nested	to any depth.  Nesting is limited  only	 by
		 the  amount  of  memory  available when the source
		 file is assembled.

		 Macro	definitions  can  contain  calls  to  other
		 macros. These nested macro calls are expanded like
		 any other macro call,	but  only  when	 the  outer
		 macro	 is  called.   A  macro	 definition  cannot
		 contain a call	to itself.

		 __________________________________________________
		 Notes

		   Remember that MASM replaces all occurrences of a
		   dummy-parameter's  name,  even  if  you  do	not
		   intend  it  to.   For  example,  if	you  use  a
		   register name such as AX or BH for a	dummy, MASM
		   replaces all	occurrences of that  register  name
		   when	  it  expands  the  macro.   If	 the  macro
		   definition  contains	 statements  that  use	the
		   register,  not  the	dummy,	the  macro  will be
		   incorrectly expanded.

		   MASM	assembles the statements in the	macro  only
		   if  the  macro  is called, and only at the point
		   they	are inserted into the  source  file.   This
		   means  all  addresses  in the assembled code	are
		   relative  to	 the  macro  call,  not	 the  macro
		   definition.	 The  macro  definition	 itself	 is
		   never assembled.

		   You must be careful when using  the	word  MACRO
		   after  the  TITLE,  SUBTTL, and NAME	directives.
		   Since  the  MACRO  directive	  overrides   these
		   directives,	placing	 the word immediately after



								8-3


















	      XENIX Macro Assembler Reference Manual



		these directives causes	MASM to	begin to  create
		macros	named TITLE, SUBTTL, and NAME.	To avoid
		this problem, you should alter the word	MACRO in
		some  way when using it	in a title or name.  For
		example, add a hyphen to the word, ``- MACRO.''
	      __________________________________________________

	      Examples

		   add	   MACRO   xx,yy,zz
			   mov	   ax, xx
			   add	   ax, yy
			   mov	   zz, ax	       ENDM

	      This example defines a macro named  ``add'',  that
	      contains	three  statements  and	uses three dummy
	      parameters.   The	 dummy	parameters  are	 ``xx,''
	      ``yy,''  and  ``zz.''  These  parameters	will  be
	      replaced with actual  values  when  the  macro  is
	      called.


	      8.3  Macro Calls

	      Syntax

		   name	[ actual-parameter,,, ]

	      A	macro call directs MASM	to copy	 the  statements
	      of  the  macro  name  to	the point of call and to
	      replace any dummy	parameters in  these  statements
	      with  the	 corresponding	actual-parameters.   The
	      name must	be the name of a macro	defined	 earlier
	      in  the  source file.  The actual-parameter can be
	      any name,	number,	or other value.	 Any  number  of
	      actual  parameters can be	given, but they	must all
	      fit on one  line.	  Multiple  parameters	must  be
	      separated	with commas, spaces, or	tabs.




	      8-4



















						   Macro Directives



		 MASM replaces the first dummy parameter  with	the
		 first	 actual	 parameter,  the  second  with	the
		 second, and so	on.   If  a  macro  call  has  more
		 actual	parameters than	dummy parameters, the extra
		 actual	parameters are	ignored.   If  a  call	has
		 fewer	 actual	 parameters,  any  remaining  dummy
		 parameters are	replaced with nothing.	This  means
		 MASM  removes	the  dummy  parameter  name for	the
		 macro statements, but does nothing else.

		 If you	wish to	pass a list of values as  a  single
		 actual	parameter, you must place angle	brackets (<
		 >) around the list.  The items	in the list must be
		 separated by commas.

		 Examples

		      ALLOCBLOCK 1,2,3,4,5
		 This example passes five numeric parameters to	the
		 macro ALLOCBLOCK.

		      ALLOCBLOCK <1,2,3,4,5>

		 This example passes one parameter  to	ALLOCBLOCK.
		 This parameter	is a list of five numbers.

		      add     1, inc, linecount
		 This example passes three parameters to the  macro
		 ``add.''  The first parameter is a number, but	the
		 second	and third are symbols.	MASM  replaces	the
		 corresponding	dummy  parameters with exactly what
		 is typed here.


		 8.4  LOCAL Directive

		 Syntax





								8-5



















	      XENIX Macro Assembler Reference Manual



		   LOCAL dummy-name,,,

	      The LOCAL	directive creates unique names	for  use
	      in  macros.   The	 dummy-name  is	 a  name  for  a
	      placeholder that is to be	replaced by  the  unique
	      name  when  the  macro  is expanded.  At least one
	      dummy-name is required.  If  you	give  more  than
	      one,  you	 must separate the names with commas.  A
	      dummy name can be	used in	any statement within the
	      macro.

	      MASM creates a new name for a dummy each time  the
	      macro is expanded.  The name has the form

		   ??xxxx

	      where xxxx is a hexadecimal number  in  the  range
	      0000 to FFFF.

	      The LOCAL	directive is typically	used  to  create
	      unique  labels  for  macros.  Normally, if a macro
	      containing a label is used more  than  once,  MASM
	      will   display   a  multiply-defined  label  error
	      message since the	same label will	appear	in  both
	      expansions.  To avoid this problem, all labels can
	      be local dummy names.  MASM guarantees that  these
	      names  will be replaced with unique names	whenever
	      the macro	is expanded, no	 matter	 how  often  the
	      macro is expanded.

	      __________________________________________________
	      Note

		The directive  can  be	used  only  in	a  macro
		definition,   and  it  must  precede  all  other
		statements in the definition.
	      __________________________________________________





	      8-6



















						   Macro Directives



		 Example

		      loop    MACRO   count, y
			      LOCAL   A		      mov     ax, y
		      A:      mov     cx, count
			      inc     ax		  jnz	  A
			      ENDM

		 In this example, the  LOCAL  directive	 defines  a
		 dummy	name  ``A''  that is replaced with a unique
		 name each time	the macro  is  expanded.  ``A''	 is
		 used  in  two	places in the macro: as	a statement
		 label,	and as the target of a JNZ instruction.


		 8.5  PURGE Directive

		 Syntax

		      PURGE macro-name ,,,

		 The PURGE directive deletes the current definition
		 of   the   macro   macro-name	from  memory.	Any
		 subsequent call  to  that  macro  causes  MASM	 to
		 generate an error.

		 The PURGE directive is	intended  to  clear  memory
		 space	no longer needed by a macro.  If the macro-
		 name is an instruction	or directive mnemonic,	the
		 directive restores its	previous meaning.

		 The PURGE directive is	often used with	 a  ``macro
		 library''  to let you choose those macros from	the
		 library you really need in your  source  file.	  A
		 macro	library	 is  simply a file containing macro
		 definitions.  You add this library to your  source
		 file  using  the  INCLUDE  directive,	then remove
		 unwanted definitions using the	PURGE directive.

		 It is	not  necessary	to  PURGE  a  macro  before



								8-7


















	      XENIX Macro Assembler Reference Manual



	      redefining   it.	 Any  redefinition  of	a  macro
	      automatically  purges  the  previous   definition.
	      Also, any	macro can purge	itself.

	      Examples

		   PURGE     add

	      This example deletes the macro named ``add''  from
	      the assembler's memory.

		   PURGE     mac1, mac2, mac9

	      This example deletes the	macros	named  ``mac1,''
	      ``mac2,''	and ``mac9.''


	      8.6  REPT	and ENDM Directives

	      Syntax

		   REPT	 expression		      statements
		   ENDM

	      The REPT and ENDM	directives  define  a  block  of
	      statements  that	are  to	 be  repeated expression
	      number of	times.	The expression must evaluate  to
	      a	 16-bit	 unsigned  number.   It	must not contain
	      external or undefined symbols.  The statements can
	      be any valid statements.

	      Example

		   X	   =	   0
			   REPT	   10
		   X	   =	   X+1		       DB      X
			   ENDM

	      This example repeats the = and  DB  directives  10
	      times.   The  resulting statements create	10 bytes



	      8-8


















						   Macro Directives



		 of data whose values range from 1 to 10.


		 8.7  IRP and ENDM Directives

		 Syntax

		      IRP dummy, <parameter,,, >
			      statements      ENDM

		 The IRP and ENDM  directives  define  a  block	 of
		 statements  that  are to be repeated once for each
		 parameter in the list enclosed	by  angle  brackets
		 (<  >).   The dummy is	a name for a placeholder to
		 be  replaced  by  the	current	  parameter.	The
		 parameter   can   be  any  legal  symbol,  string,
		 numeric, or character	constant.   Any	 number	 of
		 parameters  can  be  given.  If you give more than
		 one, you must	separate  them	with  commas.	The
		 statements  can be any	valid assembler	statements.
		 The dummy can be used any number of times in these
		 statements.

		 When MASM encounters an IRP  directive,  it  makes
		 one  copy  of the statements for each parameter in
		 the enclosed list.   While copying the	statements,
		 it  replaces  all  occurrences	 of dummy  in these
		 statements with the current parameter.	 If a  null
		 parameter  (<>) is found in the list, the dummy is
		 replaced with a null value.  If the parameter list
		 is  empty,  the  IRP  directive  is ignored and no
		 statements are	copied.










								8-9



















	      XENIX Macro Assembler Reference Manual



	      Example

		   IRP	   X,<1,2,3,4,5,6,7,8,9,10>
		   DB	   X	  ENDM

	      This example repeats the DB  directive  10  times,
	      once  for	 each number in	the list.  The resulting
	      statements create	10  bytes  of  data  having  the
	      values 1 through 10.

	      __________________________________________________
	      Notes

		If an empty parameter is found in the list, MASM
		repeats	the statements once, replacing the dummy
		with no	value.	If the	entire	list  is  empty,
		MASM skips the repeat block.

		If an IRP  directive  is  used	inside	a  macro
		definition  and	 the  parameter	 list of the IRP
		directive is  also  a  dummy  parameter	 of  the
		macro,	you  must  enclose  that dummy parameter
		within angle  brackets.	  For  example,	 in  the
		following  macro definition, the dummy parameter
		``X'' is used as the parameter list for	the  IRP
		directive:

		     alloc   MACRO   X
				     IRP     Y,<X>
				     DB	     Y
				     ENDM		 ENDM

		If this	macro is called	with

		     alloc <1,2,3,4,5,6,7,8,9,10>

		the macro expansion becomes





	      8-10



















						   Macro Directives



			IRP	Y,<1,2,3,4,5,6,7,8,9,10>
			DB	Y	 ENDM

		   That	is, the	macro removes the brackets from	the
		   actual  parameter  before  replacing	 the dummy.
		   This	means you must provide the  angle  brackets
		   for the parameter list yourself.
		 __________________________________________________



		 8.8  IRPC and ENDM Directives

		 Syntax

		      IRPC  dummy,string		 statements
		      ENDM

		 The IRPC and ENDM directives  define  a  block	 of
		 statements   that   are  repeated  once  for  each
		 character in the string.  The dummy is	a name	for
		 a  placeholder	 to  be	 replaced  by  the  current
		 character in the string.  The string  can  be	any
		 combination   of   letters,   digits,	 and  other
		 characters.  The string should	 be  enclosed  with
		 angle	brackets  (<  >)  if  it  contains  spaces,
		 commas,  or  other  separating	 characters.	The
		 statements  can be any	valid assembler	statements.
		 The dummy can be used any number of times in these
		 statements.

		 When MASM encounters an IRPC directive,  it  makes
		 one  copy  of the statements for each character in
		 the string.   While  copying  the  statements,	 it
		 replaces   all	 occurrences  of  dummy	  in  these
		 statements with the current character.






							       8-11



















	      XENIX Macro Assembler Reference Manual



	      Example

		   IRPC	   X,0123456789		     DB	     X+1
		   ENDM

	      This example repeats the DB  directive  10  times,
	      once    for   each   character   in   the	  string
	      ``0123456789.'' The resulting statements create 10
	      bytes of data having the values 1	through	10.


	      8.9  EXITM Directive

	      Syntax

		   EXITM

	      The EXITM	 directive  directs  MASM  to  terminate
	      macro  or	 repeat	 block	expansion  and	continue
	      assembly with the	next statement after  the  macro
	      call or repeat block.   The directive is typically
	      used  with  IF  directives  to  allow  conditional
	      expansion	 of  the  last	statements in a	macro or
	      repeat block.

	      When an EXITM is encountered, MASM exits the macro
	      or   repeat   block  immediately.	  Any  remaining
	      statements  are  not  processed.	 If   EXITM   is
	      encountered  in  a macro or repeat block nested in
	      another, MASM returns to expanding the outer level
	      block.











	      8-12



















						   Macro Directives



		 Example

		      alloc   MACRO   times		  x  =	  0
				      REPT    times
				      IFE     x-0FFH
					      EXITM
				      ELSE
					      DB      x
				      ENDIF
				      x	 =    x+1
				      ENDM		ENDM

		 This example defines a	macro that creates no  more
		 than 255 bytes	of data.  The macro contains an	IFE
		 directive that	checks the  expression	``x-0FFh''.
		 When  this  expression	 is 0 (x equal to 255),	the
		 EXITM directive is processed and expansion of	the
		 macro stops.


		 8.10  Substitute Operator

		 Syntax

		      &dummy-parameter		or	     dummy-
		 parameter&

		 The substitute	operator (&) forces MASM to replace
		 the  given  dummy-parameter with its corresponding
		 actual	parameter  value.   The	 operator  is  used
		 anywhere a dummy parameter immediately	precedes or
		 follows other characters, or anytime the parameter
		 appears in a quoted string.









							       8-13



















	      XENIX Macro Assembler Reference Manual



	      Example

		   errgen	   MACRO   Y, X
		   error&X	   db	   'Error &Y - &X'
				   ENDM

	      In this example, MASM  replaces  ``&X''  with  the
	      value  of	the actual parameter passed to the macro
	      ``errgen.''  If  the  macro  is  called  with  the
	      statement

		   errgen 1, wait

	      the macro	is expanded to

		   errorwait	   db	   'Error 1 - wait'


	      __________________________________________________
	      Note

		For complex, nested macros, you	 can  use  extra
		ampersands  to delay the actual	replacement of a
		dummy parameter.  In general, you need to supply
		as  many  ampersands  as  there	 are  levels  of
		nesting.

		For example, in	the following macro  definition,
		the  substitute	operator is used twice with Z to
		make sure its replacement occurs while	the  IRP
		directive is being processed.

		     alloc   MACRO   X
				     IRP     Z,<1,2,3>
			     X&&Z    DB	     Z
				     ENDM
			     ENDM





	      8-14



















						   Macro Directives



		   In this example, the	dummy  parameter  ``X''	 is
		   replaced  immediately  when the macro is called.
		   The	dummy  parameter  ``Z,''  however,  is	not
		   replaced  until  the	IRP directive is processed.
		   This	means the parameter is	replaced  once	for
		   each	 number	 in the	IRP parameter list.  If	the
		   macro is called with

			alloc VAR

		   the expanded	macro will be

			VAR1	DB	1
			VAR2	DB	2
			VAR3	DB	3

		 __________________________________________________



		 8.11  Literal Text Operator

		 Syntax

		      <text>

		 The literal text operator directs  MASM  to  treat
		 text  as  a  single literal.  The operator is most
		 often used with macro calls and the IRP  directive
		 to  ensure  that  values  in  a parameter list	are
		 treated as a single parameter.

		 The literal text operator  can	 also  be  used	 to
		 force	MASM  to treat special characters such as ;
		 or & literally.  For example, the semicolon inside
		 angle	brackets  <;>  becomes	a  semicolon, not a
		 comment indicator.

		 MASM removes one set of angle brackets	 each  time



							       8-15



















	      XENIX Macro Assembler Reference Manual



	      the  parameter  is  used	in  a macro.  When using
	      nested macros, you will need  to	supply	as  many
	      sets  of	angle  brackets	 as  there are levels of
	      nesting.


	      8.12  Literal Character Operator

	      Syntax

		   !character

	      The literal  character  operator	forces	MASM  to
	      treat  character	as a literal.	For example, you
	      can force	MASM to	treat special characters such as
	      ;	 or & literally.  Therefore, !;	is equivalent to
	      <;>.


	      8.13  Expression Operator

	      Syntax

		   %text

	      The expression operator (%) causes MASM  to  treat
	      text   as	  an   expression.   MASM  computes  the
	      expression's value, using	numbers	of  the	 current
	      radix, and replaces text with this new value.  The
	      text must	represent a valid assembler expression.

	      The expression operator is typically used	in macro
	      calls  where  the	 programmer  needs  to	pass the
	      result of	an expression to the  macro  instead  of
	      the actual expression.







	      8-16



















						   Macro Directives



		 Example

		      printe  MACRO   msg,n
			      %OUT   * msg,n *		       ENDM
		      sym1    EQU     100	sym2	EQU	200
			      printe  <sym1 + sym2 = >,%(sym1 +	sym2)

		 In this example, the macro call

		      printe  <sym1 + sym2 = >,%(sym1 +	sym2)

		 passes	the text literal ``sym1	+ sym2 =''  to	the
		 dummy	parameter  ``msg.'' It passes the value	300
		 (the result of	the expression ``sym1 +	sym2'')	 to
		 the dummy ``n.''


		 8.14  Macro Comment

		 Syntax

		      ;;text

		 The  macro  comment  is  any  text  in	  a   macro
		 definition  that does not need	to be copied in	the
		 macro expansion. All  text  following	the  double
		 semicolon  (;;)  is  ignored  by the assembler	and
		 will appear only in the macro definition when	the
		 source	listing	is created.

		 Regular comments, unlike macro	 comments,  can	 be
		 copied	 to  each macro	expansion by specifying	the
		 .XALL directive in the	source file.









							       8-17























	      Chapter 8


	      Macro Directives
	      __________________________________________________



	      8.1  Introduction	 8-1

	      8.2  MACRO and ENDM Directives  8-2

	      8.3  Macro Calls	8-4

	      8.4  LOCAL Directive  8-6

	      8.5  PURGE Directive  8-7

	      8.6  REPT	and ENDM Directives  8-8

	      8.7  IRP and ENDM	Directives  8-9

	      8.8  IRPC	and ENDM Directives  8-11

	      8.9  EXITM Directive  8-12

	      8.10 Substitute Operator	8-13

	      8.11 Literal Text	Operator  8-15

	      8.12 Literal Character Operator  8-16

	      8.13 Expression Operator	8-16

	      8.14 Macro Comment  8-17





















