





						       File Control



		 9.1  Introduction

		 This chapter describes	 File  Control	directives.
		 These	directives  provide  control of	the source,
		 object, and listing files read	and created by MASM
		 during	an assembly.

		 There are the following File Control directives:

		      INCLUDE Include a	Source File
		      .RADIX	      Alter Default Input Radix
		      %OUT	      Display Message on Console
		      NAME	      Copy Name	to Object File
		      TITLE	      Set Program Listing Title
		      SUBTTL  Set Program Listing Subtitle
		      PAGE	      Set Program Listing Page Size
		      .LIST	      List Statements in Program Listing
		      .XLIST	      Suppress Listing Statements
		      .LFCOND List False Conditional in	Program	Listing
		      .SFCOND Suppress False Conditional Listing
		      .TFCOND Toggle False Conditional Listing
		      .LALL	      List Macro Expansions in Program Listing
		      .SALL	      Suppress Listing Macro Expansion
		      .XALL	      Exclude Comments from Macro Listing
		      .CREF	      List Symbols in Cross Reference File
		      .XCREF  Suppress Symbol Listing

		 The following sections	describe the directives	 in
		 detail.


		 9.2  INCLUDE Directive

		 Syntax

		      INCLUDE filename

		 The INCLUDE directive inserts source code from	the
		 source	 file  given  by  filename into	the current
		 source	file during assembly.	The  filename  must



								9-1


















	      XENIX Macro Assembler Reference Manual



	      name  an	existing file.	A pathname must	be given
	      if  the  file  is	 not  in  the  current	 working
	      directory.   If  the named file is not found, MASM
	      displays an error	message	and stops.

	      When MASM	 encounters  an	 INCLUDE  directive,  it
	      opens  the  named	 file and begins to assemble its
	      source statements	immediately. When all statements
	      have   been  read,  MASM	resumes	 with  the  next
	      statement	following the directive.

	      Nested INCLUDE directives	are allowed.  This means
	      a	 file  named by	an INCLUDE directive can contain
	      its own INCLUDE directives.

	      When a program  listing  is  created,  MASM  marks
	      included statements with the letter C.

	      Examples

		   include entry	  include include\record
		   include \usr\include\as\stdio



	      9.3  .RADIX Directive

	      Syntax

		   .RADIX expression

	      The .RADIX directive sets	the default input  radix
	      for  numbers  in	the source file.  The expression
	      defines whether the  numbers  are	 binary,  octal,
	      decimal,	hexadecimal,  or  numbers  of some other
	      base.  It	must be	within the range 2 to  16.   The
	      following	lists some common values:





	      9-2



















						       File Control



		      2	      -	binary		    8	    - octal
		      10      -	decimal	     16	     - hexadecimal

		 The expression	 is  always  considered	 a  decimal
		 number	regardless of the current default radix.

		 Examples

		      .radix  16      .radix  2


		 __________________________________________________
		 Notes

		   The .RADIX directive	does not affect	the DD,	DQ,
		   or	DT  directives.	  Numbers  entered  in	the
		   expression  of  these  directives   are   always
		   evaluated  as decimal unless	a numeric suffix is
		   appended to the value.

		   The	.RADIX	directive  does	 not   affect	the
		   optional  radix  specifiers,	 B and D, used with
		   integers numbers.  When B or	D  appears  at	the
		   end	of  any	integer, it is always considered to
		   be a	radix specifier	even if	the  current  input
		   radix  is  16.   This means that numbers such as
		   ``0abcd'' and ``234b'' are illegal even when	the
		   input  radix	 is  set to 16.	( ``a,'' ``b,''	and
		   ``c'' are not legal digits for a decimal number;
		   similarly, ``2,'' ``3,'' and	``4'' are not legal
		   for a binary	number.)
		 __________________________________________________



		 9.4  %OUT Directive

		 Syntax




								9-3



















	      XENIX Macro Assembler Reference Manual



		   %OUT	text

	      The %OUT directive directs  MASM	to  display  the
	      text  at	the  user's  terminal.	The directive is
	      useful for  displaying  messages	during	specific
	      points of	a long assembly.

	      The  %OUT	 directive  generates  output  for  both
	      assembly passes. The IF1 and IF2 directives can be
	      used to control when the directive is processed.

	      Example

		   IF1			 %OUT First Pass -- Okay
		   ENDIF



	      9.5  NAME	Directive

	      Syntax

		   NAME	module-name

	      The NAME directive sets the name	of  the	 current
	      module  to  module-name.	A module name is used by
	      the linker when displaying error messages.

	      The module-name can be any combination of	 letters
	      and  digits.  Although the name can be any length,
	      only the first six characters are	used.  The  name
	      must be unique and not be	a reserved word.

	      Example

		   name	main

	      If the NAME directive is not used, MASM creates  a
	      default module name using	the first six characters
	      of a TITLE directive.  If	no  TITLE  directive  is



	      9-4


















						       File Control



		 found,	the default name ``A'' is used.


		 9.6  TITLE Directive

		 Syntax

		      TITLE text

		 The TITLE directive defines  the  program  listing
		 title.	  It directs MASM to copy text to the first
		 line of each new page in the program listing.	The
		 text can be any combination of	characters up to 60
		 characters in length.

		 No more than one TITLE	 directive  per	 module	 is
		 allowed.

		 Example

		      title PROG1 -- 1st Program

		 Note that the first six  non-blank  characters	 of
		 the  title  will be used as the module	name if	the
		 module	does not contain a NAME	directive.


		 9.7  SUBTITLE Directive

		 Syntax

		      SUBTTL text

		 The SUBTTL directive defines the listing subtitle.
		 It   directs	MASM  to  copy	text  to  the  line
		 immediately after the title on	each  new  page	 in
		 the   program	 listing.   The	 text  can  be	any
		 combination of	 characters.   Only  the  first	 60
		 characters  are used.	If no characters are given,
		 the subtitle line is left blank.



								9-5


















	      XENIX Macro Assembler Reference Manual



	      Any number of SUBTTL directives can be given in  a
	      program.	 Each new directive replaces the current
	      subtitle with the	new text.

	      Examples

		   subttl   SPECIAL I/O	ROUTINE

	      This example creates the	subtitle  ``SPECIAL  I/O
	      ROUTINE.''

		   subttl

	      This example creates a blank subtitle.


	      9.8  PAGE	Directive

	      Syntax

		   PAGE	  length, width	     PAGE +	  PAGE

	      The  PAGE	 directive  sets  the  line  length  and
	      character	width of the program listing, increments
	      section page numbering, or generates a page  break
	      in the listing.

	      If a length and width are	 given,	 PAGE  sets  the
	      maximum  number  of  lines per page to length, and
	      the maximum  number  of  characters  per	line  to
	      width.  The length must be in the	range 10 to 255.
	      The default is 50.  The width must be in the range
	      60  to  132.   The  default  is 80. A width can be
	      given without a length as	long as	 the  comma  (,)
	      precedes the width.

	      If a plus	sign (+) is given, PAGE	 increments  the
	      section  number  and  resets the page number to 1.
	      Program listing page numbers have	the form:



	      9-6



















						       File Control



		      section-minor

		 By default, page numbers start	at 1-1.

		 If no argument	is given, PAGE starts a	new  output
		 page  in  the	program	 listing.  It copies a form
		 feed character	to the file and	generates  a  title
		 and subtitle line.

		 Examples

		      PAGE

		 This example creates a	page break.

		      PAGE 58,60

		 This example sets the maximum page  length  to	 58
		 lines,	and the	maximum	width to 60 characters.

		      PAGE ,132

		 This  example	sets  the  maximum  width  to	132
		 characters.	The  current  page  length  remains
		 unchanged.

		      PAGE +

		 This example increments the current section number
		 and sets the page number to 1.












								9-7



















	      XENIX Macro Assembler Reference Manual



	      9.9  .LIST and .XLIST Directives

	      Syntax

		   .LIST      .XLIST

	      The .LIST	 and  .XLIST  directives  control  which
	      source  program  lines  are  copied to the program
	      listing.	The .XLIST directive suppresses	 copying
	      of subsequent source lines to the	program	listing.
	      The  .LIST  directive   restores	 copying.    The
	      directives  are typically	used in	pairs to prevent
	      a	section	of a given source file from being copied
	      to the program listing.

	      The .XLIST directive overrides all  other	 listing
	      directives.

	      Example

		   .XLIST
			   ;listing suspended here
		   .LIST		   ;listing resumes here



	      9.10  .SFCOND, .LFCOND,

	      Syntax

		   .SFCOND	.LFCOND	     .TFCOND

	      The  .SFCOND  and	 .LFCOND  directives   determine
	      whether	or  not	 conditional  blocks  should  be
	      listed.	The  .SFCOND  directive	 suppresses  the
	      listing of any subsequent	conditional blocks whose
	      IF condition  is	false.	 The  .LFCOND  directive
	      restores	 the   listing	of  these  blocks.   The
	      directives can be	used like .LIST	 and  .XLIST  to
	      suppress	listing	 of  the  conditional  blocks in



	      9-8


















						       File Control



		 sections of a program.

		 The .TFCOND directive sets the	 default  mode	for
		 listing  of  conditional  blocks.   This directive
		 works in conjunction with the	-X  option  of	the
		 assembler.   If  -X  is  given	in the MASM command
		 line, .TFCOND causes false conditional	 blocks	 to
		 be listed by default.	If -X is not given, .TFCOND
		 causes	false conditional blocks to be suppressed.

		 Examples

		      .SFCOND				       IF 0
			      ;This block will not be listed.
		      ENDIF		 .LFCOND	       IF 0
			      ;This block will be listed.
		      ENDIF



		 9.11  .LALL, .XALL, and .SALL Directives

		 Syntax

		      .LALL	  .XALL	      .SALL

		 The .LALL, .XALL, and .SALL directives	control	the
		 listing of the	statements in macros that have been
		 expanded in the source	file.	MASM  always  lists
		 the   full   macro  definition,  but  lists  macro
		 expansions only if the	 appropriate  directive	 is
		 set.

		 The .LALL directive causes MASM to  list  all	the
		 source	 statements  in	a macro, including comments
		 preceded by a single semicolon	(;) but	 not  those
		 preceded  by  a  double semicolon (;;).  The .XALL
		 directive lists only those source statements  that
		 generate code or data,	so comments are	ignored.



								9-9



















	      XENIX Macro Assembler Reference Manual



	      The .SALL	 directive  suppresses	listing	 of  all
	      macro  expansions.  That is, MASM	copies the macro
	      call to the source listing, but does not copy  the
	      source lines that	the call generates.

	      .XALL  is	 in  effect  when  MASM	  first	  begins
	      execution.

	      Example

		   .SALL		 ;No macros listed here.
		   .LALL		 ;Macros listed	in full.
		   .XALL
			   ;Macros listed by generated code or data only.



	      9.12  .CREF and .XCREF Directives

	      Syntax

		   .CREF      .XCREF name,,,

	      The  .CREF  and  .XCREF  directives  control   the
	      generation  of  cross  references	 for  the  macro
	      assembler's  cross-reference  file.   The	  .XCREF
	      directive	 suppresses  the  generation  of  label,
	      variable,	and symbol cross references.  The  .CREF
	      function restores	this generation.

	      If a name	is given with .XCREF, only  that  label,
	      variable,	or symbol will be suppressed.  All other
	      names will be cross referenced.  The named  label,
	      variable,	 or symbol will	also be	omitted	from the
	      symbol table of the program listing.   If	 two  or
	      more  names  are	be given, they must be separated
	      with commas.

	      Example



	      9-10



















						       File Control



		      .XCREF one, two, three









































							       9-11























	      Chapter 9


	      File Control
	      __________________________________________________



	      9.1  Introduction	 9-1

	      9.2  INCLUDE Directive  9-1

	      9.3  .RADIX Directive  9-2

	      9.4  %OUT	Directive  9-3

	      9.5  NAME	Directive  9-4

	      9.6  TITLE Directive  9-5

	      9.7  SUBTITLE Directive  9-5

	      9.8  PAGE	Directive  9-6

	      9.9  .LIST and .XLIST Directives	9-8

	      9.10 .SFCOND, .LFCOND,  9-8

	      9.11 .LALL, .XALL, and .SALL Directives  9-9

	      9.12 .CREF and .XCREF Directives	9-10

























