1  MACRO
   When used with the /ALPHA qualifier, the MACRO command invokes
   the MACRO-64 Assembler for OpenVMS Alpha Systems (provided it is
   installed).

   When used with the /MIGRATION qualifier, the MACRO command
   invokes the MACRO-32 Compiler for OpenVMS Alpha to compile one
   or more VAX MACRO assembly language source files into native
   OpenVMS Alpha object code.
 

2  /ALPHA
   Invokes the MACRO-64 Assembler for OpenVMS Alpha Systems. MACRO-64
   is an assembly language for programming Alpha computers.
   Source programs written in MACRO-64 are translated into object
   (or binary) code by the MACRO-64 Assembler, which produces an
   object module and, optionally, a listing file.

                                 NOTE

        The MACRO-64 product does not ship with the OpenVMS 
        operating system. (Only this help file and the DCL 
        command are included in the base system.) You must
        install MACRO-64 from the Freeware CD-ROM. 

   To invoke MACRO-64, enter the MACRO command and the /ALPHA
   command-line qualifier, using the following syntax:

   MACRO/ALPHA  file-spec[, . . . ]

   You must specify the /ALPHA command-line qualifier
   before any other command-line parameters, qualifiers, or file
   specifications.

   If you do not specify a file type for an input file, the
   assembler uses the default file type of .M64.

   You can specify one or more source files to be assembled. To
   assemble files individually, separate the file specifications
   with commas. To concatenate and assemble the files as a single
   input file, separate the file specifications with plus signs
   (+).

   Command-line qualifiers control special assembler options.
   Assembler options can apply to the entire MACRO/ALPHA
   command-line, or to the individual file being assembled. When
   the qualifier follows the MACRO/ALPHA command, it applies
   to all files listed. For more information on qualifiers, see the
   Qualifiers on-line help section.
 

3  Qualifiers
 

4  /ALIGNMENT=option
   The full command-line option is /[NO]ALIGNMENT=option.

   Controls the alignment of code and data. Valid options are:

   Option   Function

   CODE     Alignment of certain branch target labels.
   DATA     Natural alignment of data items.

   If you omit the qualifier from the command line, the default
   options are /NOALIGNMENT=(CODE, DATA). If more than one option
   is specified, the options must be enclosed in parentheses and
   separated by a comma.
 
4  /ARCHITECTURE=option
   Determines which instructions are legal.

   Option      Function

   GENERIC     All instructions are allowed; equivalent to EV4.	
   HOST        Instruction set is that of the host processor.
   EV4	       Instruction set is that of the EV4 base design processors
               (21064, 20164A, 21066, and 21068 chips).
   EV5         Instruction set is that of the EV5 processor
               (some 21164 chips).
   EV56        Instruction set is that of the EV56 processors
               (some 21164 chips).  Includes BWX extensions.
   PCA56       Instruction set is that of the PCA56 processor
               (21164PC chips).  Includes BWX and MAX extensions.
   EV6         Instruction set is that of the EV6 processor
               (21264 chips).  Includes BWX and MAX extensions and
               SQRT instructions.

4  /DEBUG[=(options)]
   The full command-line option is /[NO]DEBUG[=(options)].

   Specifies DEBUG support. Valid options are:

   Option   Function

   SYMBOL   Generates debug symbol information.
   TRACEBACKGenerates traceback information.
   ALL      Generates all previous debug information.
   NONE     Generates no debug information.

   The default qualifier is /NODEBUG. When you specify /DEBUG with
   no options, the default option is /DEBUG=ALL.
 

4  /DEFINE=(symbol_[=[=]value],...)
   The full command-line option is /[NO]DEFINE=(symbol [=
   [=]value],...).

   Performs the same function as direct symbol assignment in your
   source program. That is, the /DEFINE qualifier defines a numeric
   symbol.

   The Digital Command Language (DCL) converts all input to
   uppercase unless you enclose it within quotation marks.

   Use a single equal sign between the symbol and the value to
   define a local symbol. Use two equal signs between the symbol and
   the value to define a global symbol. The final value of a global
   symbol is output to the object module and is available during
   the linking process. A local symbol is only available during the
   assembly process.

   You cannot define a lexical string symbol with /DEFINE. The value
   you specify for a symbol must be an integer literal. You can
   specify this value using a binary, octal, decimal, or hexadecimal
   radix. The default radix is decimal. If you specify an alternate
   radix, you must use MACRO-64 radix syntax, not DCL radix syntax.

   If you do not specify a value for the symbol, it defaults to 1.

   The simplest form of a /DEFINE definition is as follows:

            /DEFINE=TRUE

   This definition is equivalent to the following definition:

            TRUE=1

   You can also specify more than one symbol definition as with the
   following command:

            /DEFINE=(CHIP==21064,UNROLL=4)

   This definition is equivalent to the following definitions:

            CHIP==21064
            UNROLL=4

   When more than one /DEFINE qualifier is present on the MACRO
   command line or in a single assembly unit, the assembler uses
   only the last one.

   The default qualifier is /NODEFINE.
 

4  /DIAGNOSTIC[=file-spec]
   The full command-line option is /[NO]DIAGNOSTIC[=file-spec].

   Controls whether diagnostics are created and stored in the
   specified optional file. If a file specification is not supplied,
   the assembler creates a diagnostic file using the same name
   as the source file. For example, if you use a source file
   named XXX.M64, the assembler creates a diagnostic file named
   XXX.DIA. You can use the diagnostic file with other Digital
   layered products including, but not limited to, the DEC Language-
   Sensitive Editor (LSE).

   The default qualifier is /NODIAGNOSTIC.
 

4  /ENVIRONMENT=[NO]FLOAT
   The full command-line option is /ENVIRONMENT=[NO]FLOAT.

   Controls whether the assembler generates floating-point
   instructions when optimizing code and performing code-label
   alignment.

   Currently, the only floating-point instruction generated by
   the assembler during optimization and alignment processing
   is FNOP, the floating-point no-operation instruction. If you
   specify /ENVIRONMENT=NOFLOAT, the assembler does not generate any
   floating-point instructions as part of optimization and alignment
   processing. Floating-point instructions that you specify in your
   source program are unaffected.
 

4  /LIBRARY
   The full command-line option is /LIBRARY[=file-spec].

   Searches macro libraries in the following order:

   1. The library designated by the /LIBRARY qualifier.

   2. The .LIBRARY directives.

   3. The MACRO64.MLB library. The assembler searches for the
      MACRO64.MLB macro library in the following locations:
      MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY.

   4. The STARLET.MLB library. The assembler searches for the
      STARLET.MLB macro library in the following locations:
      MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY.

   In addition, you can place the macro library definitions in the
   listing file by using the command-line qualifier /SHOW=LIBRARY.
 

4  /LIST[=file-spec]
   The full command-line option is /[NO]LIST[=file-spec].

   Controls whether a listing is created and optionally provides
   an output file specification for the listing file. Do not use
   wildcard characters in this file specification.

   If you enter the MACRO/ALPHA command interactively, the
   default qualifier is /NOLIST. The assembler sends output to
   the current output device rather than to a listing file. If you
   execute the MACRO/ALPHA command in a batch job, the default
   qualifier is /LIST.

   If you do not specify a file specification, the assembler creates
   a listing file using the same name as the source file. For
   example, if you use a source file named XXX.M64, the assembler
   creates a listing file named XXX.LIS.
 

4  /MACHINE_CODE
   The full command-line option is /[NO]MACHINE_CODE.

   Produces a binary machine code listing after the source text if a
   listing file is requested. The default qualifier is /NOMACHINE_
   CODE.
 

4  /NAMES=case_option
   The full command-line option is /NAMES=case_option.

   Specifies the alphabetic casing of identifiers in source code
   statements. Valid options are:

   Option   Function

   UPPER_   Converts all identifiers to upper alphabetic case.
   CASE
   LOWER_   Converts all identifiers to lower alphabetic case.
   CASE
   AS_IS    Causes all identifiers to remain in the case used in
            source statements.

   If you use the /NAMES qualifier in a command line, you must
   supply a case_option. If you omit the qualifier from the command
   line, the default option is /NAMES=UPPER_CASE.
 

4  /OBJECT[=file-spec]
   The full command-line option is /[NO]OBJECT[=file-spec].

   Controls whether an object file is created and optionally
   provides a file specification. Do not use wildcard characters
   in this file specification.

   If you do not specify a file specification, the assembler creates
   an object file using the same name as the source file. For
   example, if you use a source file named XXX.M64, the assembler
   creates an object file named XXX.OBJ.

   The default qualifier is /OBJECT.
 

4  /OPTIMIZE[=(option-list)]
   The full command-line option is /[NO]OPTIMIZE[=(option-list)].

   Specifies optional assembler optimizations. Valid items in the
   option-list are:

   Option   Function

   SCHEDULE Specifies instruction scheduling.
   PEEPHOLE Specifies peepholing.

   Specifying /OPTIMIZE with no options is the same as specifying
   /OPTIMIZE=(PEEPHOLE,SCHEDULE).

   The default qualifier is /NOOPTIMIZE.
 

4  /PREPROCESSOR_ONLY_[=filespec]
\BK_ADDED_27)
   The full command-line option is /PREPROCESSOR_ONLY [=filespec]).

   Causes the assembler to output a source file that is the result
   of the input source file after preprocessing. Suppresses
   diagnostic messages and does not produce diagnostic (.ANA) or
   object (.OBJ) files.

   The default option, /NOPREPROCESSOR_ONLY-MACRO-64, assembles your
   source files normally.

   If you specify /PREPROCESSOR_ONLY without a file specification
   argument, the output file name defaults to the name of the
   primary source input file. The output file type defaults to .ASM.

   The following MACRO-64 directives are executed by the
   preprocessor and screened from the preprocessor output file:

      .DISABLE PREPROCESSOR_OUTPUT
      .ENABLE PREPROCESSOR_OUTPUT
      .IF
      .ELSE
      .ENDC
      .IIF
      .IF_FALSE
      .IF_TRUE
      .IF_TRUE_FALSE
      .INCLUDE
      .LIBRARY
      .IRP
      .IRPC
      .REPEAT
      .ENDR
      .MACRO
      .ENDM
      .MCALL
      .MDELETE
      .MEXIT
      .NARG
      .NCHR

   Include files are inserted in place of the .INCLUDE directive
   into the preprocessor output file.

   Macro definitions and repeat block definitions are screened from
   the preprocessor output file.

   Macro expansion lines and repeat block expansion lines are
   inserted in place of the macro invocation line or repeat block,
   respectively, into the preprocessor output file.

   Lexical string-symbol assignment statements are screened from the
   preprocessor output file.

   Lines containing lexical operators are replaced with their
   equivalents after lexical operator processing.

   Lexical line continuations are processed into a single,
   uncontinued line.

   All other language elements, including directives not previously
   listed, label definitions, direct numeric-symbol assignments, and
   so forth are passed through unchanged to the preprocessor output
   file.
 

4  /SHOW=(item,...)
   The full command-line option is /[NO]SHOW=(item,...).

   Modifies the output listing file. This qualifier is meaningful
   only when /LIST is specified. Valid items are:

   Option         Function

   BINARY         Lists macro expansions that generate binary code.
                  BINARY is a subset of EXPANSIONS.
   CONDITIONALS   Shows sections of code conditionally skipped.
   EXPANSIONS     Shows macro expansions.
   INCLUDE        Shows all .INCLUDE files.
   LIBRARY        Shows macro library modules.

   The default option is /SHOW=CONDITIONALS.
 

4  /WARNINGS=(option-list)
   The full command-line option is /[NO]WARNINGS=(option-list).

   Controls the severity level of messages and diagnostics. Valid
   options are:

   Option          Function

   WARNINGS        Display/suppress warnings.
   INFORMATIONALS  Display/suppress informationals.
   ALL             Display/suppress warnings and informationals.
   NONE            Display/suppress nothing.

   The default options are /WARNINGS=(WARNINGS,INFORMATIONALS). If
   more than one option is specified, options must be enclosed in
   parentheses separated by a comma.
 

3  Source_Statement_Format
   MACRO-64 source statements can have a maximum of four fields, as
   follows:

   o  Label field-Symbolically defines a location in a program.

   o  Operator field-Specifies the action to be performed by the
      statement; this can be an instruction, an assembler directive,
      or a macro call.

   o  Operand field-Contains the instruction operands or the
      assembler directive arguments or the macro arguments.

   o  Comment field-Contains a comment that explains the meaning of
      the statement; this does not affect program execution.

   You can separate statement fields by either a space or a tab
   stop, but Digital recommends that you format statements with the
   Tab key to ensure consistency and clarity.

   Table 1 Using Tab Stops in Statement Fields

             Column
             in
             Which
             Field
   Field     Begins   Tab Stops to Reach Column

   Label     1        0
   Operator  9        1
   Operand   17       2
   Comment   41       5

   The following example shows a typical source statement:

   EXP:    .BLKL   50           ; Table stores expected values
   Rules for Coding Source Statements
   The following rules apply for coding source statements:

   o  You can continue a single statement on several lines by
      using a hyphen (-)  as the last nonblank character before
      the comment field, or at the end of line (when there is no
      comment).

   o  In most cases, you can continue a statement at any point. If a
      symbol name is continued and the first character on the second
      line is a tab or a blank, the symbol name is terminated at
      that character.

   o  Blank lines are legal, but they have no significance in the
      source program except that they terminate a continued line.

   The following sections describe each of the statement fields in
   detail.
 

4  Label_Field
   A label is a user-defined symbol that identifies a location in
   the program. The symbol is assigned a value equal to the location
   counter where the label occurs. The following rules apply when
   coding source statements with labels:

   o  If a statement contains a label, the label must be in the
      first field on the line.

   o  The user-defined symbol name can be up to 31 characters long
      and can contain any alphanumeric character, as well as the
      underscore (_),  dollar sign ($), and period (.)  characters.

   o  If a label extends past column 7, Digital recommends you place
      it on a line by itself so that the following operator field
      can start in column 9 of the next line.

   o  A label is terminated by a colon (:)  or a double colon (::).

   In the following source statement, EXP: is the label field:

   EXP:    .BLKL   50           ; Table stores expected values

   There are three types of labels:

   o  Global labels-Can be referenced by other object modules and
      are defined using a double colon (::).

   o  Local labels-Can be referenced only within the current module
      and are defined using a single colon (:).

   o  Temporary labels-Can be referenced only within the bounds
      of either two local labels, two global labels, two psects
      (program sections), or within the bounds of a temporary
      label scope, as defined by .ENABLE LOCAL_BLOCK and
      .DISABLE LOCAL_BLOCK. Temporary labels are defined using one
      to five digits followed by a dollar sign and a single colon
      ($:).

   The following example shows how these labels appear in use:

   EXP:    .BLKL   50           ; EXP is a local label used to
                                ; identify a 50-word block of storage
   DATA::  .BLKW   25           ; DATA is a global label used to
                                ; identify a 25-word block of storage
   10$:    .BLKW    5           ; 10$ is a temporary label used to
                                ; identify a five word block of
                                ; storage.
 

4  Operator_Field
   The operator field specifies the action to be performed by the
   statement. This field can contain an instruction, an assembler
   directive, or a macro call. If the operator is:

   o  An instruction, MACRO-64 generates the binary code for that
      instruction in the object module.

   o  A directive, MACRO-64 performs certain control actions or
      processing operations during source program assembly.

   o  A macro call, MACRO-64 expands the macro.

   Use either a space or a tab stop to terminate the operator
   field; however, Digital recommends that you use the tab stop
   to terminate the operator field.

   In the following source statement, .BLKL is the operator field:

   EXP:    .BLKL   50           ; Table stores expected values
 

4  Operand_Field
   The operand field can contain operands for instructions or
   arguments for either assembler directives or macro calls.

   Operands for instructions identify the memory locations or the
   registers that are used by the machine operation. The operand
   field for a specific instruction must contain the correct number
   and type of operands required by that instruction.

   Arguments for a directive must meet the format requirements of
   that directive.

   Operands for a macro must meet the requirements specified in the
   macro definition.

   Use a comma (,)  to separate operands for instructions and
   directives.

   The semicolon that starts the comment field terminates the
   operand field. If a line does not have a comment field, the
   operand field is terminated by the end of the line.

   In the following source statement example, 50 is the operand
   field supplied to the operator field, .BLKL:

   EXP:    .BLKL   50          ; Table stores expected values
 

4  Comment_Field
   The comment field contains text that explains the function of the
   statement. You can use comments to describe algorithms, reasons
   for selecting particular methods, and parameters passed to
   routines. Comments do not affect assembly processing or program
   execution.

   The comment field must be preceded by a semicolon (;)  and can
   contain any printable ASCII character. It is terminated by the
   end of the line.

   A comment can appear on a line by itself. If a comment does
   not fit on one line, it can be continued on the next, but the
   continuation must be preceded by another semicolon.

   In the following source statement example, "Table stores expected
   values" is the comment field. Note that the comment field begins
   with a semicolon.

   EXP:    .BLKL   50          ; Table stores expected values
 

3  Character_Set
   When coding source statements, you need to be aware of what
   characters are acceptable to the assembler, and how the assembler
   interprets them. The following numbers and characters are
   accepted by the assembler:

   o  The letters of the alphabet, A to Z, uppercase and lowercase.
      By default, the assembler converts all lowercase letters
      to uppercase. This means it considers lowercase letters
      equivalent to uppercase letters.

      The assembler can operate in a case-sensitive mode. In case-
      sensitive mode, the assembler does not convert lowercase
      letters to uppercase letters. On OpenVMS and OpenVMS Alpha
      systems, you can select case-sensitive mode from the command
      line with the /NAMES=AS_IS qualifier.

   o  The digits 0 to 9.

   o  The special characters listed in the Special Characters Table
      which follows.
 

   Table 2 Special Characters Used in MACRO-64 Statements

             Character
      CharactName       Function

      _      Underscore Character in symbol names.
      $      Dollar     Character in symbol names.
             sign
      .      Period     Character in symbol names, current location
                        counter, and decimal point.
      :      Colon      Local label terminator.
      ::     Double     Global label terminator.
             colon
      =      Equal      Local direct assignment operator and macro
             sign       keyword argument terminator.
      ==     Double     Global direct assignment operator.
             equal
             sign
      #      Number     Literal value indicator.
             sign
      @      At sign    Arithmetic shift operator.
      ;      Semicolon  Comment field indicator.
      +      Plus       Unary plus operator and arithmetic addition
             sign       operator.
      -      Minus      Unary minus operator, arithmetic subtraction
             sign or    operator, and line continuation indicator.
             hyphen
      *      Asterisk   Arithmetic multiplication operator.
      /      Slash      Arithmetic division operator.
      &      Ampersand  Logical AND operator.
      !      ExclamationLogical inclusive OR operator.
             point
      \      Backslash  Logical exclusive OR and numeric conversion
                        indicator in macro arguments.
      ^      Circumflex Unary operators and macro argument
                        delimiter.
      ( )    ParenthesesDisplacement and register field delimiter in
                        an instruction operand. Argument delimiter
                        to a lexical operator.
      <>     Angle      Argument or expression grouping delimiters.
             brackets
      ?      Question   Created local label indicator in macro
             mark       arguments.
      '      Apostrophe Macro argument concatenation indicator.
      "      Double     Quoted literal delimiter.
             quote
      %      Percent    Delimits the beginning of a lexical
             sign       operator.
      (space)Space or   Separates source statement fields. Spaces
             tab        within expressions are otherwise ignored.
      (tab)
      ,      Comma      Separates symbolic arguments within the
                        operand field. Multiple expressions in the
                        operand field must be separated by commas.
 

3  Numbers
   Numbers can be integers or floating-point numbers. The following
   sections describe these types of numbers.
 

4  Integers
   You can use integers in any expression, including expressions in
   operands and in direct assignment statements.
   FORMAT
   snn
 

s

   An optional sign: plus sign (+)  for positive numbers (the
   default), or minus sign (-) for negative numbers.
 

nn

   A string of numeric characters that is legal for the specified
   radix.

   MACRO-64 interprets all integers in the source program as decimal
   unless the number is preceded by a radix control operator.

   Integers must be in the range of -263 to +263 -1 for signed data

   or in the range of 0 to 264 -1 for unsigned data.

   Negative numbers must be preceded by a minus sign; MACRO-64
   translates such numbers into two's complement form. In positive
   numbers, the plus sign is optional.
 

4  Floating_Point_Number
   You can use a floating-point number in the .DOUBLE, .FLOAT,
   .F_FLOATING, .D_FLOATING, .G_FLOATING, .S_FLOATING, and
   .T_FLOATING directives. You cannot use a floating-point number
   in an expression or with a unary or binary operator except the
   unary plus and unary minus.

   You can specify a floating-point number with or without an
   exponent.
   FORMAT
   Floating-point number without exponent:

   snn
   snn.nn
   snn.

   Floating-point number with exponent (E):

   snnEsnn
   snn.nnEsnn
   snn.Esnn
 

s

   An optional sign.
 

nn

   A string of decimal digits in the range of 0 to 9.

   The decimal point can appear anywhere to the right of the first
   digit. A floating-point number cannot start with a decimal point
   because MACRO-64 treats the number as a user-defined symbol.
 

3  Quoted_Literals
   A quoted literal is a string of characters enclosed in double
   quotes (" ").  Use the following guidelines when specifying
   characters in a quoted literal:

   o  Any character except null, carriage return, and form feed can
      appear within the string.

   o  To include a double quote or backslash in a string, you must
      precede it with a backslash (\).

   o  To specify an arbitrary character, you can specify "\xhh",
      where each h represents a single hexadecimal digit. For
      example:

      "AB\\CD\"EF\x47"

      This string contains the following characters:

      AB\CD"EFG

   Also note that the assembler does not convert the case of
   alphabetic characters within a quoted literal.

   Quoted literals can be continued over several lines. Use the
   hyphen (-)  as the line continuation character and delimit the
   string with double quotes. For example:

   .ASCII "Strings are delimited with double quotes."
   .ASCII "The backslash is an escape character."
   .ASCII "Strings can be continued onto multiple lines -
   just as any other line."
   .ASCII "Use two backslashes (\\) to represent -
   the back-slash itself."
   .ASCII "Hexidecimal escape sequences use -
   lower or upper X: \x00 or \X00"
   .ASCII "Precede a double quote with a backslash (\") -
   to embed the quote."
 

3  Symbols
   You use symbols in MACRO-64 source statements to represent an
   instruction, directive, register name, or value. You can use four
   types of symbols in MACRO-64 source programs: permanent symbols,
   predefined symbols, user-defined symbols, and macro names.
 

4  Permanent_Symbols
   Permanent symbols consist of MACRO-64 directives and instruction
   mnemonics. You need not define directives before you use them in
   the operator field of a MACRO-64 source statement. It is also not
   necessary to define instruction mnemonics before using them in
   the instruction statements.
 

4  Predefined_Symbols
   Predefined symbols are MACRO-64 register symbols that are not
   permanently reserved. You can delete the definition of any of
   these predefined register symbols. You can also define your own
   register symbols.

   You can express the 32 general registers and the 32 floating-
   point registers of the Alpha processor in a source program as
   follows:

   Register
   Name   Description

   R0     General register 0.
   R1     General register 1.
   .      .
   .      .
   .      .
   R29    General register 29 or frame pointer. If you use R29 as a
   or FP  frame pointer, Digital recommends you use the name FP. If
          you use R29 as a general register, Digital recommends you
          use the name R29.
   R30    General register 30 or stack pointer. If you use R30 as a
   or     stack pointer, the name SP is recommended; if you use R30
   SP     as a general register, the name R30 is recommended.
   R31    General register 31.
   F0     Floating-point register 0.
   .      .
   .      .
   .      .
   F31    Floating-point register 31.

                                  NOTE

      When MACRO-64 operates in /NAMES=AS_IS mode, all of the
      previous register symbols are defined in all uppercase and
      all lowercase.

   To define your own register symbols, use either the .DEFINE_
   FREG or .DEFINE_IREG directive for floating-point or integer
   registers, respectively. For more information about the .DEFINE_
   FREG or .DEFINE_IREG directives, see .DEFINE_FREG and .DEFINE_
   IREG, respectively.

   You can delete a register symbol definition with the .UNDEFINE_
   REG directive. For more information about the .UNDEFINE_REG
   directive, see .UNDEFINE_REG.

   While an identifier is defined as a register symbol, it can only
   be used in those contexts that allow a register.
 

4  User-Defined_Symbols_and_Macro_Names
   You can use symbols to define labels, or you can equate them to a
   specific value by a direct assignment statement. You can also use
   these symbols in expressions.

   Use the following rules to create user-defined symbols:

   o  Use alphanumeric characters, underscores (_),  dollar signs
      ($),  and periods (.). Any other character terminates the
      symbol.

   o  The first character of a symbol cannot be a number.

   o  The symbol must be no more than 31 characters long and must be
      unique.

   o  The symbol must not be a register name.

   o  The symbol cannot be one of the following conditional or macro
      directives:

      .ELSE          .ENDC          .ENDM
      .ENDR          .IF            .IF_FALSE (.IFF)
      .IF_TRUE       .IF_TRUE_      .IIF
      (.IFT)         FALSE
                     (.IFTF)
      .INCLUDE       .IRP           .IRPC
      .LIBRARY       .MACRO         .MCALL
      .MDELETE       .MEXIT         .NARG
      .NCHAR         .REPEAT

   In addition, by Digital convention:

   o  The dollar sign ($)  is reserved for names defined by Digital.
      This convention ensures that a user-defined name (that does
      not have a dollar sign) will not conflict with a Digital-
      defined name (that does have a dollar sign).

   o  Do not use the period (.)  in any global symbol name because
      many languages, such as Fortran, do not allow periods in
      symbol names.

   Macro names follow the same rules and conventions as user-defined
   symbols. User-defined symbols and macro names do not conflict;
   that is, you can use the same name for a user-defined symbol and
   a macro.
 

4  Determining_Symbol_Values
   The value of a symbol depends on its use in the program. MACRO-64
   uses a different method to determine the values of symbols in the
   operator field than it uses to determine the values of symbols in
   the operand field.
 

4  Using_Symbols_in_the_Operator_Field
   A symbol in the operator field can be either a permanent symbol
   or a macro name. MACRO-64 searches for a symbol definition in the
   following order:

   1. Macro and conditional directives:

      .ELSE      .ENDC          .ENDM
      .ENDR      .IF            .IF_FALSE (.IFF)
      .IF_TRUE   .IF_TRUE_      .IIF
      (.IFT)     FALSE (.IFTF)
      .INCLUDE   .IRP           .IRPC
      .LIBRARY   .MACRO         .MCALL
      .MDELETE   .MEXIT         .NARG
      .NCHAR     .REPEAT

   2. Previously defined macro names

   3. Permanent symbols (instructions and other directives)

   This search order allows most permanent symbols, except
   conditional directives and macro directives, to be redefined
   as macro names. If a symbol in the operator field is not defined
   as a macro or a permanent symbol, the assembler displays an error
   message.
 

4  Using_Symbols_in_the_Operand_Field
   A symbol in the operand field must be either a user-defined
   numeric symbol, a label, or a register name.

   User-defined numeric symbols and labels can be either local
   (internal) symbols or global (external) symbols. Whether numeric
   symbols and labels are local or global depends on their use in
   the source program.

   You can reference a local numeric symbol or label only in the
   module in which it is defined. If local numeric symbols or labels
   with the same names are defined in different modules, the symbols
   and labels are completely independent. The definition of a global
   numeric symbol or label, however, can be referenced from any
   module in the program.

   MACRO-64 treats all user-defined numeric symbols and labels as
   local unless you explicitly declare them to be global by doing
   one of the following:

   o  Use the double colon (::)  in defining a label.

   o  Use the double equal sign (==) in a direct assignment
      statement.

   o  Use the .WEAK directive.

   You can only use user-defined lexical string symbols with the
   lexical string operators. You can define a macro using the same
   name as a previously defined local numeric symbol, global numeric
   symbol, or a lexical string symbol. However, you cannot define a
   lexical string symbol and a numeric symbol using the same name.

   In addition, you cannot use the same name for both a local and
   global numeric symbol. You cannot use the same symbol name for
   both a numeric symbol (local or global) and a label (local or
   global).
 

3  Temporary_Labels_Within_Source_Code
   Use temporary labels to identify addresses within a block of
   source code.
   Format
   nnnnn$:
 

nnnnn

   A decimal integer in the range of 1 to 65,535.

   In most cases, you can use temporary labels in the same way
   you use other labels that you define; however, there are some
   differences:

   o  Temporary labels cannot be referenced outside the temporary
      label block in which they are declared.

   o  Temporary labels can be redeclared in another block of source
      code.

   o  Temporary labels that occur within a psect with the MIX or
      NOMIX attribute do not appear in the debugger symbol table;
      thus, they cannot be accessed by the symbolic debugger.

   o  Temporary labels cannot be used in the .END or
      .PROCEDURE_DESCRIPTOR directives.

   By convention, temporary labels are positioned like statement
   labels: left-justified in the source text. Although temporary
   labels can appear in the program in any order, by convention,
   the temporary labels in any block of source code should be in
   increasing numeric order.

   Temporary labels are useful as branch addresses when you use
   the address only within the block. You can use temporary labels
   to distinguish between addresses that are referenced only in a
   small block of code and addresses that are referenced elsewhere
   in the module. A disadvantage of temporary labels is that their
   numeric names do not provide any indication of their purpose.
   Consequently, you should not use temporary labels to label
   sequences of statements that are logically unrelated; you should
   use user-defined symbols instead.

   Digital recommends that users create temporary labels only in
   the range of 0$ to 29999$ because the assembler automatically
   creates temporary labels in the range of 30000$ to 65535$ for use
   in macros.

   The temporary label block in which a temporary label is valid is
   delimited by the following statements:

   o  A user-defined label: global or local.

   o  A .PSECT directive.

      An example showing the correct and incorrect use of temporary
      labels follows:

      A:    ADDQ R1, R2, R3
            BEQ R3, 2$         ; correct use
            MULQ R2, R3, R4
      2$:   ADDQ R1, R4, R5    ; definition of temporary label
      B:    BNE R5, 2$         ; illegal
      C:    SUBQ R2, R4, R6

      In this example, 2$ is a temporary label defined in the
      block between A: and B:. The forward reference in the second
      instruction is properly resolved. The line labeled B: also
      references 2$, but the label B has already closed the range.
      The temporary label 2$ can be used later in the program, but
      its definition must appear within the same block as the label.

   o  The .ENABLE and .DISABLE directives, which can extend a local
      label block beyond user-defined labels and .PSECT directives.

   A temporary label block is usually delimited by two user-defined
   labels. However, the .ENABLE LOCAL_BLOCK directive starts a local
   block that is terminated by one of the following:

   o  A second .ENABLE LOCAL_BLOCK directive

   o  A .DISABLE LOCAL_BLOCK directive followed by a user-defined
      label or a .PSECT directive

   Temporary labels can be preserved with the context of the program
   section in which they are defined for future reference. See the
   descriptions of the .SAVE_PSECT [LOCAL_BLOCK] directive and the
   .RESTORE_PSECT directive.
 

3  Label_Addresses
   In the absence of optimization and automatic data alignment,
   label addresses are defined to be the psect and offset of the
   current location counter at the point where the label is defined.
   When either optimization or automatic data alignment are enabled,
   the following additional considerations apply.
 

4  Label_Addresses,_Optimization,_and_Code_Alignment
   Optimization and code alignment can affect the addresses
   assigned to labels defined in psects that have the EXE and NOMIX
   attributes. Optimization and code alignment are disabled by
   default, and can be enabled with the /OPTIMIZE and /ALIGNMENT
   command-line qualifiers and the .ENABLE directive In general, the
   assembler assigns the psect and offset of the current location
   counter before optimization or alignment of code labels. However,
   the assembler adjusts references to labels in branch instructions
   to the address of the label after optimization and code alignment
   processing. The assembler does not adjust references to labels
   where the label reference occurs in an expression with more than
   one term. The following example shows this:

           .PSECT CODE, EXE, NOMIX
           BSR     R0, 10$            ; R0 -> 10$ (postoptimization)
   10$:    LDA     R1, 20$-10$(R0)    ; R1 -> 20$ (preoptimization)
           JMP     (R1)
           [...]
   20$:

   In the previous example, the assembler adjusts the target
   address of the BSR instruction to be the location of 10$ after
   optimization and code alignment have taken place. Thus, the
   branch to 10$ functions as expected. However, when processing the
   LDA instruction, the assembler computes the offset between 20$
   and 10$ before optimization and code alignment. Thus, the address
   of 20$ that is stored in R1 is the address prior to optimization
   and code alignment. Depending on the sequence of instructions
   between 10$ and 20$, the address before optimization and code
   alignment may differ from the address after optimization and code
   alignment and the JMP instruction may not transfer control to the
   expected address.

   Note also that the assembler only performs postoptimization
   adjustment of label addresses when the label is the only term
   in the expression. For example:

           .PSECT CODE, EXE, NOMIX
           .BASE R27,LINKAGE
           LDQ     R26, ROUTINE1_ADDR
           JSR     R26, (R26)
           LDQ     R26, ROUTINE2_ADDR
           JSR     R26, (R26)
           RET     R28
           NOP
           NOP

   ROUTINE1:
           RET     (R26)
   ROUTINE2:
           RET     (R26)

           .PSECT LINKAGE, NOEXE
   LINKAGE:
   ROUTINE1_ADDR:
           .ADDRESS ROUTINE1
   ROUTINE2_ADDR:
           .ADDRESS ROUTINE2+0

   In the previous example, the assembler adjusts the address stored
   with the .ADDRESS ROUTINE1 directive to the address of label
   ROUTINE1 after optimization and code alignment. However, since
   the expression in the .ADDRESS ROUTINE2+0 directive is not a
   single term, the assembler adds the offset 0 and the address
   of ROUTINE2 before optimization and code alignment and stores
   the result. Since the address stored is the address before
   optimization and code alignment, the second JSR instruction may
   not transfer control to the address that is expected.
 

4  Label_Addresses_and_Automatic_Data_Alignment
   Automatic data alignment can affect the addresses assigned to
   labels in psects that have the NOEXE or MIX attributes. Automatic
   data alignment is enabled with the .ENABLE ALIGN_DATA directive
   or the /ALIGNMENT=data command-line option.

   A label that occurs in a statement with a data-storage directive
   is assigned the psect and offset of the storage allocated by the
   data-storage directive. If the data-storage directive requires
   automatic alignment, the address is assigned to the label after
   automatic alignment.

   The same is true of labels that occur in statements by themselves
   and that are followed by a data directive in a subsequent
   statement. However, if a label occurs in a statement by itself
   and is followed by a statement that is not a data-storage
   directive, a macro directive, a conditional directive, or a
   lexical-string symbol assignment, the label is assigned the psect
   and offset of the current location counter before any automatic
   alignment.

   The assembler only assigns addresses to labels after alignment
   under the conditions previously described and only with automatic
   alignment. If you place a label before a .ALIGN directive that
   manually aligns the current location counter, the assembler
   assigns the address of the label before performing the manual
   alignment. The following example shows the interaction of label
   address assignment and automatic data alignment:

       .ENABLE ALIGN_DATA
       .PSECT DATA, NOEXE
       .BYTE   1       ; The byte is stored in psect data at offset 0
   A:  .PRINT "Not aligned" ; Any non-macro, nonconditional
                       ; statement, including this .PRINT directive
                ; prevents A from being automatically aligned
                       ; -- A is assigned offset 1
   B:                  ; B is automatically aligned to offset 4
   C:  .LONG   2       ; C is automatically aligned to offset 4
   D:  .ALIGN 0        ; The .ALIGN global directive prevents D
                       ;  from being automatically aligned --
         ;  D is assigned offset 8
   E:  .OCTA 3         ; E is automatically aligned to offset 16

   Automatic data alignment and label-address assignment can be an
   important consideration when calculating the difference between
   two labels. For example, consider the following macro, which
   stores a string preceded by a word that contains the string's
   length:

           .MACRO VARYING_STRING STRING ?L1, ?L2
                   .WORD L2-L1
               L1: .ASCII "STRING"
               L2:
           .ENDM VARYING_STRING

   If an invocation of the VARYING_STRING macro is followed by a
   data-storage directive that requires automatic alignment, the
   VARYING_STRING macro will not store the correct string length.
   For example:

           .PSECT DATA, NOEXE, .OCTA
           .ENABLE ALIGN_DATA
           VARYING_STRING <Time for something sweet!> ; 25 bytes
   F:      .OCTA 4

   In this example, the intention is to make the L2 label generated
   by the VARYING_STRING macro be assigned the offset 27, 2 for
   the .WORD directive, plus 25 for the .ASCII directive. Instead,
   it is assigned the offset 32 along with the label F because
   the .OCTA directive requires automatic alignment to offset 32.
   Therefore, the string length is incorrectly stored as 30 rather
   25. To make this macro work as desired, you must include, in the
   macro definition, a macro directive that is not a data-storage,
   macro, or conditional directive after the generated label L2. In
   the following example, .ALIGN 0 is a good choice as it reflects
   the idea that the preceding label is not aligned:

    .MACRO VARYING_STRING STRING ?L1, ?L2
         .WORD L2-L1
        L1: .ASCII "STRING"
        L2: .ALIGN 0
    .ENDM VARYING_STRING

   With this change, the generated label L2 is assigned the offset
   27 before the assembler performs automatic data alignment for the
   .OCTA directive. As a result, the VARYING_STRING macro works as
   desired and stores the correct string length of 25.
 

3  Terms_and_Expressions
   A term can be any of the following:

   o  A number.

   o  A numeric symbol.

   o  A label.

   o  The current location counter.

   o  Any of the previously noted items preceded by a unary
      operator.


   MACRO-64 evaluates terms as quadword (8-byte) values. The current
   location counter (.)  has the value of the location counter at
   the start of the current operand.

   MACRO-64 considers unary operators part of a term and, thus,
   performs the action indicated by a unary operator before it
   performs the action indicated by a binary operator.

   Expressions are combinations of terms joined by binary operators
   and evaluated as quadword (8-byte) values. MACRO-64 evaluates
   expressions from left to right with no operator precedence rules.
   However, you can use angle brackets (<>)  to change the order
   of evaluation. Any part of an expression that is enclosed in
   angle brackets is first evaluated to a single value, which is
   then used in evaluating the complete expression. For example, the
   expressions A*B+C and A*<B+C> are different. In the first case, A
   and B are multiplied and then C is added to the product. In the
   second case, B and C are added and the sum is multiplied by A.
   You can also use angle brackets to apply a unary operator to an
   entire expression, such as -<A+B>.

   Expressions fall into four categories: relocatable, absolute,
   external (global), and complex. You can determine the type of
   expression by the following rules:

   o  An expression is relocatable if its value is fixed relative
      to the start of the psect in which it appears. The current
      location counter is relocatable in a relocatable psect.

   o  An expression is absolute if its value is an assembly-
      time constant. An expression whose terms are all numbers
      is absolute. An expression that consists of a relocatable
      term minus another relocatable term from the same psect is
      absolute, because such an expression reduces to an assembly-
      time constant.

   o  An expression is external if it is not complex, and it
      contains one or more symbols that are not defined in the
      current module.

   o  An expression is complex if it contains a relocatable or
      external term or subexpression that is operated upon by an
      operator other than the plus sign (+)  or the minus sign
      (-). An expression is also complex if it contains more than
      one term or subexpression that is relocatable or external.
      An exception to this rule is the difference between two
      relocatable subexpressions or terms where both relocatable
      values occur in the same psect. In this case, the expression
      is absolute.

   Complex expressions are constrained to use the following form:
   FORMAT
   term operator term
 

term

   Term is a relocatable or external subexpression.
 

operator

   Operator is any of the MACRO-64 operators.

   Neither term can itself be a complex subexpression. If you
   specify a complex expression that does not match the correct
   form, the assembler issues a diagnostic error message indicating
   that the expression is too complex. Note also that the assembler
   does not attempt to reorder expressions to make your expressions
   match the correct form. For example, the following expression is
   too complex:

    .external E1, E2
    .quad E1+5+E2+6  ; too complex

   Because the assembler has no precedence rules, it attempts to
   evaluate the previous expression as <<<E1+5>+E2>+6>. Since
   <<E1+5>+E2> is itself a complex term, <<<E1+5>+E2>+6> does not
   match the previous form and is too complex. However, you can
   regroup the expression using angle brackets (<>) to match the
   required form as follows:

    .external E1, E2
    .quad <E1+5>+<E2+6>  ; legal complex expression

   In this case, both <E1+5> and <E2+6> are simple, external terms.
   Since none of the terms are complex, the expression matches the
   correct form and the assembler accepts the complex expression.

   You can use any type of expression in most MACRO-64 statements,
   but restrictions are placed on expressions used in the following
   contexts:

   o  .BASE directive.

   o  .BLKx storage allocation directives.

   o  .IF conditional assembly block directives.

   o  .REPEAT repeat block directives.

   o  Direct assignment statements.

   o  Lexical string operator arguments.

   Expressions used in these contexts can contain only symbols or
   labels that have been previously defined in the current module.

   The .BASE directive accepts expressions that contain external
   symbols previously declared with the .EXTERNAL directive. The
   other contexts previously described cannot accept expressions
   that contain external symbols. Symbols defined later in the
   current module cannot be used in any of these contexts.

   Expressions in the .IF conditional directives, .REPEAT
   conditional directives, and lexical string operator arguments
   are relocatable. However, expressions in the .BLKx directives
   must be absolute.

   Expressions cannot contain floating-point numbers. The floating-
   point data-storage directives accept constant values. They do not
   accept floating-point expressions.

   The following example shows the use of expressions:

   A = 2*100                 ; 2*100 is an absolute expression
           .BLKB   A+50      ; A+50 is an absolute expression and
                             ;   contains no undefined symbols
   LAB:    .BLKW   A         ; LAB is relocatable
   HALF = LAB+<A/2>          ; LAB+<A/2> is a relocatable
                             ;   expression and contains no
                             ;   undefined symbols
   LAB2:   .BLKB   LAB2-LAB  ; LAB2-LAB is an absolute expression
                             ;   and contains no undefined symbols
 

3  Unary_Operators
   A unary operator modifies a term or an expression and indicates
   the action to be performed on that term or expression.
   Expressions modified by unary operators must be enclosed in
   angle brackets. You can use unary operators to indicate whether
   a term or expression is positive or negative. If unary plus or
   minus is not specified, the default value is plus. In addition,
   unary operators perform radix conversion and numeric control
   operations, as described in the following sections.

   Table 3 Summary of Unary Operators

   Unary  Operator
   OperatoName       Example  Operation

   +      Plus       +A       Results in the positive value of A.
          sign
   -      Minus      -A       Results in the negative (two's
          sign                complement) value of A.
   \      Value of   \symbol  Indicates that the value of the symbol
          Escape              should be used. In a string literal,
                              indicates an escape sequence. For
                              example:
                              "Bob\X0A"
   ^A or  ASCII      ^A       Specifies an ASCII constant.
   ^a                /ABCD/
   ^B or  Binary     ^B1100011Specifies that 11000111 is a binary
   ^b                         number.
   ^D or  Decimal    ^D127    Specifies that 127 is a decimal
   ^d                         number.
   ^O or  Octal      ^O34     Specifies that 34 is an octal number.
   ^o
   ^X or  Hexadecimal^XFCF9   Specifies that FCF9 is a hexadecimal
   ^x                         number.
   ^C or  Complement ^C24     Produces the one's complement value of
   ^c                         24 (decimal).
 

4  Radix_Control_Operators
   Radix control operators determine the radix of a term or
   expression. MACRO-64 accepts terms or expressions in four
   different radixes: binary, decimal, octal, and hexadecimal. The
   default radix is decimal.
   FORMATS

   ^Bnn
   ^Dnn
   ^Onn
   ^Xnn
 

nn

   A string of characters that is legal in the specified radix. The
   following are the legal characters for each radix:

          Radix
   Format Name       Legal Characters

   ^Bnn   Binary     0 and 1
   ^Dnn   Decimal    0 to 9
   ^Onn   Octal      0 to 7
   ^Xnn   Hexadecimal0 to 9 and A to F

   You can include radix control operators in the source program
   anywhere a numeric value is legal. A radix control operator
   affects only the term immediately following it, causing that
   term to be evaluated in the specified radix. For example:

   .WORD   ^B00001101              ; Binary radix
   .WORD   ^D123                   ; Decimal radix (default)
   .WORD   ^O47                    ; Octal radix

   Do not place spaces or tabs between the circumflex (^), the radix
   specifier (B, D, O, or X), or the numeric value.
 

4  Numeric_Complement_Operator
   The complement operator (^C)  produces the one's complement of
   the specified value.

   FORMAT
   ^Cterm
 

term

   Any term or expression. If an expression is specified, it must be
   enclosed in angle brackets.

   MACRO-64 evaluates the term or expression as an 8-byte value
   before complementing it. For example:

   .LONG      ^C^XFF      ; Produces FFFFFF00 (hex)
   .LONG      ^C25        ; Produces complement of
                          ;   25 (dec) which is
                          ;   FFFFFFE6 (hex)
 

3  Binary_Operators
   In contrast to unary operators, binary operators specify
   actions to be performed on two terms or expressions. You can
   enclose expressions in angle brackets to specify the order of
   evaluation.

   Table 4 Summary of Binary Operators

      BinaryOperator
      OperatName        ExampleOperation

      +     Plus sign   A+B     Addition
      -     Minus sign  A-B     Subtraction
      *     Asterisk    A*B     Multiplication
      /     Slash       A/B     Division
      @     At sign     A@B     Arithmetic shift
      &     Ampersand   A&B     Logical AND (product)
      !     Exclamation A!B     Logical OR (sum)
            point
      \     Backslash   A\B     Logical XOR (difference)

   All binary operators have equal priority. You can group terms or
   expressions for evaluation by enclosing them in angle brackets.
   The enclosed terms and expressions are evaluated first, and
   remaining operations are performed from left to right. For
   example:

   .LONG      1+2*3      ; Equals 9
   .LONG      1+<2*3>    ; Equals 7

   Note that a 64-bit result is returned from all binary operations.
   If you use the 64-bit result in a context requiring less than
   64 bits, only the lower-order bits of the result are used. If
   the truncation causes a loss of significance in a data-storage
   directive, the assembler displays an error message.

   The following sections describe the arithmetic shift, logical
   AND, logical inclusive OR, and logical exclusive OR operators.
 

4  Arithmetic_Shift_Operator
   Use the arithmetic shift operator (@)  to perform left and right
   arithmetic shifts of arithmetic quantities. The first argument
   is shifted left or right by the number of bit positions that
   you specify in the second argument. If the second argument is
   positive, the first argument is shifted left and the low-order
   bits are set to zero. If the second argument is negative, the
   first argument is shifted right and the high-order bits are set
   to the value of the original high-order bit (the sign bit). For
   example:

           .LONG   ^B101@4              ; Yields 1010000 (binary)
           .LONG   1@2                  ; Yields 100 (binary)
   A = 4
           .LONG   1@A                  ; Yields 10000 (binary)
           .LONG   ^X1234@-A            ; Yields 123(hex)
 

4  Logical_AND_Operator
   The logical AND operator (&)  takes the logical AND of two
   operands. For example:

   A = ^B1010
   B = ^B1100
           .LONG   A&B             ; Yields 1000 (binary)
 

4  Logical_Inclusive_OR_Operator
   The logical inclusive OR operator (!)  takes the logical
   inclusive OR of two operands. For example:

   A = ^B1010
   B = ^B1100
           .LONG   A!B             ; Yields 1110 (binary)
 

4  Logical_Exclusive_OR_Operator
   The logical exclusive OR operator (\)  takes the logical
   exclusive OR of two arguments. For example:

   A = ^B1010
   B = ^B1100
           .LONG   A\B             ; Yields 0110 (binary)
 

3  Direct_Assignment_Statements
   A direct assignment statement equates a symbol to a specific
   value. Unlike a symbol that you use as a label, you can redefine
   a symbol defined with a direct assignment statement as many times
   as you want.
   FORMATS

   symbol=expression

   symbol==expression

   symbol=quoted-literal
 

symbol

   A user-defined symbol.
 

expression

   An expression that does not contain any undefined symbols or
   forward references. The result must be either an absolute or
   relocatable value, whose value can be determined at the current
   point in the assembly. This form defines a numeric symbol.

   The format with a single equal sign (=)  defines a local symbol,
   and the format with a double equal sign (==) defines a global
   symbol.

   The following three syntactic rules apply to direct assignment
   statements:

   o  An equal sign (=)  or double equal sign (==) must separate
      the symbol from the expression that defines its value. Spaces
      preceding or following the direct assignment operators have no
      significance in the resulting value.

   o  Only one symbol can be defined in a single direct assignment
      statement.

   o  A direct assignment statement can be followed only by a
      comment field.

   For best results, Digital recommends you place the symbol in a
   direct assignment statement in the label field. For example:

   A == 1                  ; The symbol 'A' is globally
                           ;   equated to the value 1

   B = A@5                 ; The symbol 'B' is equated
                           ;   to 1@5 or 32(dec)

   C = 127*10              ; The symbol 'C' is equated
                           ;   to 1270(dec)

   D = ^X100/^X10          ; The symbol 'D' is equated
                           ;   to 10(hex)
 

quoted-literal

   A literal within double quotes. This form defines a lexical
   string symbol. You can only use lexical string symbols with
   lexical string operators.
 

3  Current_Location_Counter
   The current location counter is a counter kept by an assembler to
   determine the address assigned to an instruction or constant that
   is being assembled. The symbol for the current location counter,
   the period (.),  represents the address of the current byte.
   MACRO-64 sets the current location counter to 0 at the beginning
   of the assembly and at the beginning of each new program section.

   Every MACRO-64 source statement that allocates memory in the
   object module increments the value of the current location
   counter by the number of bytes allocated. For example, the
   directive, .LONG 0 increments the current location counter by 4.
   However, with the exception of the special form described later
   in this section, a direct assignment statement does not increase
   the current location counter because no memory is allocated.

   The current location counter can be explicitly set by a special
   form of the direct assignment statement. The location counter can
   be either incremented or decremented. This method of setting the
   location counter is often useful when defining data structures.
   Data-storage areas should not be reserved by explicitly setting
   the location counter; use the .BLKx directives.
   FORMAT

   .=expression
 

expression

   An expression that does not contain any undefined or external
   symbols.

   In a relocatable psect, the expression must be relocatable; that
   is, the expression must be relative to an address in the current
   psect. It also may be relative to the current location counter.
   For example:

   . = .+40        ; Moves location counter forward

   When a psect that you defined in the current module is continued,
   the current location counter is set to the last value of the
   current location counter in that psect.

   In a psect with the EXE and NOMIX attributes:

   o  The location counter cannot be changed.

   o  If optimization is enabled, the location counter represents
      the location before optimization.

   In a psect with either the EXE or NOMIX (or both) attributes:

   o  The location counter can be changed.

   o  If you store an initial data or instruction value in memory
      with a data directive such as .BYTE, .WORD, .LONG, or .QUAD
      or with an instruction statement, you can replace that initial
      value with a different initial value later in the assembly
      by assigning the appropriate address value to the current
      location counter and entering another data directive or
      instruction statement. However, the new value must be the
      same size and must start at exactly the same address as the
      value it replaces.
 

3  Lexical_Operators
 

4  Processing_with_Lexical_Operators
   Lexical operator processing is performed on all source lines
   and macro expansion lines before any other assembler processing.
   Thus, macro invocations, assembler directives, and instructions
   are subject to lexical operator processing before normal
   assembler processing.

   Lexical operators are recognized and processed within string
   literals. Lexical operator processing is suppressed during macro
   registration in order that lexical operator evaluation may occur
   during macro expansion. Lexical operator evaluation is also
   suppressed for a range of text that is conditionally excluded
   with one of the .IF directives. In addition, lexical operator
   processing is not performed within a comment.
 

4  Syntax
   You invoke a lexical string operator with a percent sign followed
   by the lexical operator name, a left parentheses, a list of
   arguments separated by commas, and a right parentheses. The
   following example shows the lexical operator syntax:

      .print "%EDIT(<Fred>,<upcase>)"

   Spaces are allowed between syntax elements in the general lexical
   operator syntax. For example, the following syntax, including
   spaces, is allowed:

   .print "%EDIT ( <Fred> , <upcase> )"

   Spaces are also allowed between the opening and closing percent
   signs in a lexical substitution operator.

   .print "% lexical_symbol_name %"

   Spaces are not allowed between the pair of percent signs
   indicating a lexical escape operator.

   You can specify lexical operator arguments in the same way as
   macro arguments:

   o  A numeric symbol name preceded by a backslash (\). This
      construct results in the decimal value of the numeric symbol,
      as shown in the following example:

         \N

   o  Any string of characters surrounded by left- and right-angle
      brackets, as shown in the following example:

      <Foo bar thud>

      You can nest angle brackets (<>).  For example:

      <<X+7>*17>

   o  Any string of characters surrounded by a delimiter specified
      after a caret character (^). You cannot nest delimiters. For
      example:

      ^%Foo bar thud%

   o  Any undelimited string of characters not separated by a space,
      tab, form feed, comma, equal sign, semicolon, or end of line.
      For example:

      A+B+C

   In addition to the formats allowed for a macro argument, you can
   also specify lexical operator arguments as follows:

   o  An undelimited string of characters may also contain a string
      of characters enclosed within left and right parentheses. The
      characters between the left and right parentheses may contain
      space, tab, or comma delimiters. For example:

      16( R27 )

   o  You can use a lexical operator as an argument to another
      lexical operator. For example:

      %EXTRACT( %LOCATE($,X), %LENGTH(X) - %LOCATE($,X) ,X)

   Except for the %TYPE lexical operator, a string symbol name
   supplied as a lexical operator argument is replaced with the
   value of the string symbol.

   Each lexical operator accepts a given number of arguments and
   each argument has a specific type. There are three different
   types of arguments-string, integer, and name:

   o  A string argument can be any arbitrary sequence of characters.

   o  An integer argument must be an absolute or relocatable
      expression that can be resolved at that point in the assembly.
      A relocatable expression represents a psect and an offset
      within that psect. If you specify a relocatable expression for
      an integer argument, the assembler uses only the value of the
      offset within the psect. The offset value is determined before
      optimization and code alignment, but after data alignment.

   o  The name argument type is used only by the %TYPE lexical
      operator. The %TYPE lexical operator accepts the name of a
      numeric symbol, string symbol, label, psect, or a permanent
      symbol as its argument. Unlike the other lexical operators, if
      a string symbol name is specified as an argument to %TYPE, the
      value of the string symbol is not substituted for its name.
      Instead, information about the name is returned.

   If you omit a string argument, the default is the empty string.
   An empty string is a string with no characters. If you omit an
   integer argument or specify an illegal expression, the default
   value is 0. The assembler does not issue diagnostic messages
   for illegal expressions used as arguments to lexical operators.
   If you omit the name argument or specify an illegal name to the
   %TYPE lexical operator, %TYPE returns a 0 value.
 

4  Numeric_Symbols_and_Lexical_String_Symbols
   Lexical string symbols are similar in concept and syntax to
   numeric symbols. MACRO-64 supports numeric symbols using the
   following syntax:

   numeric_symbol_name = numeric_expression

   MACRO-64 supports lexical string symbols using the following
   syntax:

   string_symbol_name = "any string of characters"

   The assembler differentiates between numeric symbol assignment
   and lexical string symbol assignment as follows:

   o  In a lexical string symbol assignment, a quoted string literal
      must appear after the equal sign.

   o  A lexical string symbol value is specified by the quoted
      string literal.

   The quotes are not included in the value of the lexical string
   symbol. You cannot use the same name for a lexical string symbol,
   numeric symbol, or label.

   Like numeric symbols, lexical string symbols are assembly time
   variables. After you assign a string value to a lexical string
   symbol, you can reassign a different value to that symbol later
   in the assembly.

   You can use lexical string symbols as arguments to lexical
   operators. In particular, you can use a lexical string symbol
   as an argument to the lexical substitution operator (%)  or the
   %STRING lexical operator to substitute the value of the lexical
   string symbol at any point in the text of your program.
 

4  Lexical_Substitution_Operator
   You can use the lexical substitution operator at any point in
   your program to cause the assembler to substitute the value of
   a lexical string symbol for the name of the symbol. The lexical
   substitution operator is the percent sign (%). Place the lexical
   substitution operator to the left and right of the name of the
   lexical string symbol that you wish to subsitute, as follows:

   %lexsym_name%

   For example:

        HORSES    = "All the king's horses"
        MEN       = "all the king's men"
        .print "%HORSES% and %MEN%"

   This example defines two lexical string symbols: HORSES and MEN.
   The third statement displays a message at assembly time. The text
   of the message specifies that the value of the HORSES and MEN
   lexical string symbols be substituted as indicated. After lexical
   processing, the third statement appears as:

        .print "All the king's horses and all the king's men"
 

4  Lexical_Escape_Operator
   It is possible to defer the processing of a lexical string
   operator by using the lexical escape operator, which is the
   percent sign (%).  Since all lexical string operators begin with
   a percent sign, the effect of placing two percent signs before
   the name of the lexical string operator defers the evaluation of
   the lexical string operator. If you want to defer processing of
   a lexical substitution operator, place two percent signs to the
   left and two percent signs to the right of the lexical string
   symbol name.

   This can be useful when you want the evaluation of a lexical
   string operator that you have used in a default macro argument
   to occur during macro expansion, rather than during macro
   definition. Lexical operator processing is suppressed during
   macro registration. Therefore, lexical operator processing is
   automatically deferred within the body of a macro. However, the
   .MACRO directive line that begins the macro definition is subject
   to normal lexical operator processing. Sometimes you may need
   to use the value of a lexical string symbol as the default for
   a macro argument, but you need to use the value of the lexical
   string symbol that is current when the macro expands, not when
   the macro is defined. Lexical Processing Without the Escape
   Operator shows an example of this, but it does not use an escape
   operator.

   Example 1  Lexical Processing Without the Escape Operator

       CODE_PSECT_NAME = "CODE1"
       .MACRO CODE_PSECT PSECT_NAME=%string(CODE_PSECT_NAME)
        .PSECT PSECT_NAME
       .ENDM CODE_PSECT
       CODE_PSECT
       CODE_PSECT_NAME = "CODE2"
       CODE_PSECT

   Lexical Processing Without the Escape Operator does not process
   correctly for the following reasons:

   o  The lexical operator in the .MACRO directive line is processed
      when the macro is defined, not when the macro expands.

   o  The CODE_PSECT macro always defaults to setting the psect
      to the CODE1 psect because the default for the PSECT_NAME
      argument will be set to CODE1, not %string(CODE_PSECT_NAME).
      This is because %string(CODE_PSECT_NAME) is evaluated when the
      CODE_PSECT macro is defined, not when it expands.

   Lexical Processing with Escape Operator is similar to Lexical
   Processing Without the Escape Operator except it uses the lexical
   escape operator.

   Example 2  Lexical Processing with Escape Operator

       CODE_PSECT_NAME = "CODE1"
       .macro CODE_PSECT PSECT_NAME=%%string(CODE_PSECT_NAME)
      .psect PSECT_NAME
       .endm CODE_PSECT
       CODE_PSECT
       CODE_PSECT_NAME = "CODE2"
       CODE_PSECT

   Lexical Processing with Escape Operator processes correctly for
   the following reasons:

   o  Lexical operator processing of %%string(CODE_PSECT_NAME)
      is deferred when the CODE_PSECT macro is defined. The
      default value for the PSECT_NAME argument is stored as
      %string(CODE_PSECT_NAME).

   o  During macro expansion, %string(CODE_PSECT_NAME) is evaluated,
      which results in the current value of the CODE_PSECT_NAME
      lexical string symbol as desired.
 

4  %EDIT
   Lexical operator for editing text strings.

   Format

     %EDIT  (string1,string2)
 

5  Arguments
 

string1

   The first argument, of type string, specifies the string to be
   edited.
 

string2

   The second argument, of type string, specifies a list of edits to
   perform, which are separated by commas.
 

5  Description
   %EDIT is modeled after the OpenVMS DCL lexical function F$EDIT.
   It is used to perform one or more edits on a specified string.
   %EDIT processes the string of arguments from left to right. %EDIT
   gives precedence to the last argument. %EDIT gives precedence to
   uppercase over lowercase.

   The list of edits may contain any combination of the following
   elements:

   Element    Function

   COLLAPSE   Removes all tabs and spaces.
   COMPRESS   Replaces multiple, consecutive tabs or spaces with a
              single space.
   LOWERCASE  Changes uppercase characters to lowercase.
   TRIM       Removes leading and trailing spaces and tabs.
   UPCASE     Changes lowercase characters to uppercase.
 

5  Examples
     Example 1
            .PRINT "%EDIT(< Fred Smith >, <TRIM,COLLAPSE,UPCASE>)"

     After lexical processing, the statement apears as the
     following:

            .PRINT "FREDSMITH"
     Example 2
            .PRINT "%EDIT(<AbCdEfG>,<upcase,lowercase>)
            .PRINT "%EDIT(<AbCdEfG>,<lowercase,upcase>)

     The first source statement produces the string "abcdefg" and
     the second source statement produces the string "ABCDEFG". Each
     of the edits in the edit list is performed in sequence, from
     left to right.
 

4  %ELEMENT
   Lexical operator for extracting elements from a list of elements.

   Format

     %ELEMENT  (integer,string1,string2)
 

5  Arguments
 

integer

   The first argument, of type integer, is the element number to
   extract. The first element is number 0.
 

string1

   The second argument, of type string, is the delimiter or
   delimiters that separate elements.
 

string2

   The third argument, of type string, is the list of elements.
 

5  Description
   %ELEMENT is modeled after the OpenVMS DCL lexical function
   F$ELEMENT. It is used to extract one element from a string of
   elements. Note that unlike F$ELEMENT, you may specify multiple
   delimiters. The result is the specified string element. If the
   specified element number is greater than the number of elements
   in the list, the delimiter argument is returned.
 

5  Example

            .PRINT "%ELEMENT (2, <+-*/>, JOE+FRED-TOM*BILL/ERIC)"

     After lexical processing, the statement appears as:

            .PRINT "TOM"
 

4  %EXTRACT
   Lexical operator for extracting a range of characters from a
   string of characters.

   Format

     %EXTRACT  (integer1,integer2,string)
 

5  Arguments
 

integer1

   The first argument, of type integer, is the offset at which to
   begin the extraction. The first character is at offset 0.
 

integer2

   The second argument, of type integer, is the number of characters
   to extract.
 

string

   The third argument, of type string, is the string from which to
   extract the characters.
 

5  Description
   %EXTRACT is modeled after VAX MACRO's %EXTRACT macro string
   operator and the OpenVMS DCL lexical function F$EXTRACT. %EXTRACT
   is used to extract a specified range of characters from a string.
 

5  Example

            .PRINT "%EXTRACT(3,4,ABCDEFGHIJKLMNOP)"

     After lexical processing, the statement appears as:

            .PRINT "DEFG"
 

4  %FREG
   Lexical operator for obtaining the floating-point register number
   associated with a symbol.

   Format

     %FREG  (symbol)
 

5  Argument
 

symbol

   The single argument, of type string, specifies a symbol that
   may or may not be currently defined as a floating-point register
   symbol.
 

5  Description
   %FREG returns the decimal number of the floating-point register
   when the specified symbol is defined as a floating-point register
   symbol. Otherwise, %FREG returns 32.
 

5  Example

           ; Is TARG_REG the same as F31?
           .IF EQ, <%FREG(TARG_REG)>, <%FREG(31)>

     If TARG_REG has been defined as floating-point register F5, the
     statements appear as follows after lexical processing:

           ; Is TARG_REG the same as F31?
           .IF EQ, <5>, <31>
 

4  %INTEGER
   Lexical operator for converting the value of an expression to a
   decimal value.

   Format

     %INTEGER  (integer)
 

5  Argument
 

integer

   The single argument, of type integer, is the expression to be
   converted.
 

5  Description
   %INTEGER is modeled after the OpenVMS DCL lexical function
   F$INTEGER. It is used to convert the value of an expression to
   a decimal value. The result is its decimal value. You can also
   use %INTEGER to convert a relocatable expression to an absolute
   value.
 

5  Example

            .PRINT "%INTEGER (<<X+7>*17>)"

     After lexical processing, if X has the value 3, the statement
     will appear as:

            .PRINT "170"
 

4  %IREG
   Lexical operator for obtaining the integer register number
   associated with a symbol.

   Format

     %IREG  (symbol)
 

5  Argument
 

symbol

   The single argument, of type string, specifies a symbol that may
   or may not be currently defined as an integer register symbol.
 

5  Description
   %IREG returns the decimal number of the integer register when
   the specified symbol is defined as an integer register symbol.
   Otherwise, %IREG returns 32.
 

5  Example

           ; Is SRC_REG the same as SP?
           .IF EQ, <%IREG(SRC_REG)>, <%IREG(SP)>

     If SRC_REG has been defined as integer register R16, the
     statements appear as follows after lexical processing:

           ; Is SRC_REG the same as SP?
           .IF EQ, <16>, <30>
 

4  %LENGTH
   Lexical operator for determining the length of a string.

   Format

     %LENGTH  (string)
 

5  Argument
 

string

   The single argument, of type string, is the string from which the
   length is to be computed.
 

5  Description
   %LENGTH is modeled after VAX MACRO's %LENGTH macro string
   operator and the OpenVMS DCL lexical function F$LENGTH. %LENGTH
   is used to determine the length of a string. The result is the
   length of the string expressed as a decimal number.
 

5  Example

            .PRINT "%LENGTH(<The quick brown fox>)"

     After lexical processing, the statement appears as:

            .PRINT "19"
 

4  %LOCATE
   Lexical operator for locating a string of text within another
   string of text.

   Format

     %LOCATE  (string1,string2)
 

5  Arguments
 

string1

   The first argument, of type string, is the string for which
   %LOCATE searches.
 

string2

   The second argument, of type string, is the string in which the
   search is performed.
 

5  Description
   %LOCATE is modeled after VAX MACRO's %LOCATE macro string
   operator and the OpenVMS DCL lexical function F$LOCATE. %LOCATE
   is used to locate one string within another. The value returned
   is the decimal offset to the first occurrence of the first string
   within the second string. The offset to the first character is 0.
   If the first string cannot be found within the second string, the
   length of the second string is returned.
 

5  Example

            .PRINT "%LOCATE (DEF,ABCDEFGHIJKLMNOP)"

     After lexical processing, the statement appears as:

            .PRINT "3"
 

4  %REPEAT
   Lexical operator for repeating a specified string a specified
   number of times.

   Format

     %REPEAT  (integer,string)
 

5  Arguments
 

integer

   The first argument, of type integer, is the number of times to
   repeat the string. If you specify a negative value, the string is
   repeated 0 times.
 

string

   The second argument, of type string, is the string to be
   repeated.
 

5  Description
   %REPEAT is used to repeat the specified string a specified number
   of times.
 

5  Example

            .PRINT "Never, %REPEAT (3, <ever, >)touch that button!"

     After lexical processing, the statement appears as:

            .PRINT "Never, ever, ever, ever, touch that button!"
 

4  %STRING
   Lexical operator for obtaining the value of a lexical string
   symbol.

   Format

     %STRING  (string)
 

5  Argument
 

string

   The single argument is of type string. If the argument is the
   name of the lexical string symbol, the value of the lexical
   string symbol is returned. Otherwise, the argument is returned
   unchanged.
 

5  Description
   %STRING is modeled after the OpenVMS DCL lexical function
   F$STRING. %STRING is generally used to obtain the value of
   a lexical string symbol, but you can use it with any string
   argument.
 

5  Example

            FOO = "All the king's horses"
            .PRINT "%STRING(FOO)"

     After lexical processing, the statement appears as:

            .PRINT "All the king's horses"
 

4  %TIME
   Lexical operator for obtaining the date and time of the assembly
   unit.

   Format

     %TIME  ()
 

5  Description
   %TIME is modeled after the OpenVMS DCL lexical function F$TIME.
   %TIME is used to obtain the time and date of the assembly unit.
   There are no arguments. The result is a string specifying the
   date and time of the assembly unit.
 

5  Example

            .PRINT "%TIME()"

     After lexical processing, the statement appears as:

            .PRINT " 8-OCT-1991 13:17:57"
 

4  %TYPE
   Lexical operator for obtaining information about a name.

   Format

     %TYPE  (name)
 

5  Argument
 

name

   The single argument is of type name. Information is returned
   about the name specified in the argument.
 

5  Description
   %TYPE is modeled after the OpenVMS DCL lexical function
   F$TYPE. %TYPE is used to obtain information about a name. The
   value returned is a numeric value with certain bit positions,
   either 0 or 1, depending on whether the specified name has the
   corresponding attribute. As described elsewhere, the decimal
   digits of the numeric value are substituted for the %TYPE lexical
   operator. %TYPE Attributes shows the symbolic names that are
   predefined for each attribute.

   Table 5 %TYPE Attributes

   Symbolic Name          Attribute

   MACRO64$TYPE_SYMBOL    Name is a numeric symbol name.
   MACRO64$TYPE_PROC_     Name is a procedure descriptor name.
   DESC
   MACRO64$TYPE_LABEL     Name is a label.
   MACRO64$TYPE_EXTERN    Name is an external name.
   MACRO64$TYPE_WEAK      Name is a weak name.
   MACRO64$TYPE_PSECT     Name is a psect.
   MACRO64$TYPE_MACRO     Name is a macro name.
   MACRO64$TYPE_STRING    Name is a lexical string symbol name.
   MACRO64$TYPE_OPCODE    Name is an opcode.
   MACRO64$TYPE_DIR       Name is a directive.
   MACRO64$TYPE_GENREG    Name is a general register.
   MACRO64$TYPE_FLTREG    Name is a floating register.

   A given name may have zero, one, or several attributes.
 

5  Example

            .macro IS_GR ARG
              .IF equal, %TYPE(ARG) & <MACRO64$TYPE_GENREG>
               .PRINT "ARG is not a general register"
              .ENDC
            .endm IS_GR
            IS_GR F11

     Initially, the first line of the IS_GR macro expands as the
     following:

            .IF equal, <%TYPE(F11) & MACRO64$TYPE_GENREG>

     After lexical processing, the statement appears as:

            .IF equal, <8192 & MACRO64$TYPE_GENREG>

     In this example, 8192 is the attribute value for a floating-
     point register. This value could change in subsequent releases.
     Use only the predefined attribute masks described in %TYPE
     Attributes. Since the attribute for a general register
     MACRO64$TYPE_GENREG is 4096, the expression evaluates as 0.

            <8192 & MACRO64$TYPE_GENREG>
 

3  Macros

   By using macros, you can use a single source statement to insert
   a sequence of source statements into a program.

   A macro definition contains the source statements of the macro.
   The macro definition may have formal arguments. You can use these
   formal arguments throughout the sequence of source statements
   within the definition. When the macro is called, the formal
   arguments are replaced by the actual arguments within the macro
   call.

   The macro call is a single source statement consisting of the
   macro name, optionally followed by arguments. When the macro
   is called, the assembler replaces the line containing the macro
   call with the source statements in the macro definition. The
   assembler replaces any occurrences of formal arguments in the
   macro definition with the actual arguments specified in the macro
   call. This process is called the macro expansion.

   By default, macro expansions are not printed in the assembly
   listing. To print the macro expansions, you must specify the
   /SHOW=EXPANSIONS qualifier and argument in the command line. Note
   that the examples of macro expansions used in this chapter are
   listed as they would appear using the /SHOW=EXPANSIONS qualifier
   and argument.

   Use .SHOW with a symbolic argument of EXPANSIONS in the source
   text of a program to specify the listing of expansions.
 

4  Arguments
   Macros have two types of arguments: actual and formal. Actual
   arguments are the text given in the macro call after the name
   of the macro. Formal arguments are specified by name in the
   macro definition; that is, after the macro name in the .MACRO
   directive. Actual arguments in macro calls and formal arguments
   in macro definitions can be separated by commas (,),  tabs, or
   spaces.

   The number of actual arguments in the macro call can be less
   than or equal to the number of formal arguments in the macro
   definition. If the number of actual arguments is greater than
   the number of formal arguments, the assembler displays an error
   message.

   Formal and actual arguments normally maintain a strict positional
   relationship. That is, the first actual argument in a macro call
   replaces all occurrences of the first formal argument in the
   macro definition. This strict positional relationship can be
   overridden by using keyword arguments. See the section on keyword
   arguments.

   An example of a macro definition using formal arguments follows:

   .MACRO  STORE  ARG1,ARG2,ARG3
   .LONG   ARG1                     ; ARG1 is first argument
   .WORD   ARG3                     ; ARG3 is third argument
   .BYTE   ARG2                     ; ARG2 is second argument
   .ENDM   STORE

   The following two examples show possible calls and expansions of
   the macro previously defined:

   STORE   3,2,1                    ; Macro call
   .LONG   3                        ; 3 is first argument
   .WORD   1                        ; 1 is third argument
   .BYTE   2                        ; 2 is second argument

   STORE   X,X-Y,Z                  ; Macro call
   .LONG   X                        ; X is first argument
   .WORD   Z                        ; Z is third argument
   .BYTE   X-Y                      ; X-Y is second argument
 

4  Default_Values
   Default values are values that are defined in the macro
   definition. They are used when no value for a formal argument
   is specified in the macro call.

   Default values are specified in the .MACRO directive as follows:

   formal-argument-name = default-value

   An example of a macro definition specifying default values
   follows:

   .MACRO  STORE   ARG1=12,ARG2=0,ARG3=1000
   .LONG   ARG1
   .WORD   ARG3
   .BYTE   ARG2
   .ENDM   STORE

   The following three examples show possible calls and expansions
   of the macro defined previously:

   STORE                   ; No arguments supplied
   .LONG   12
   .WORD   1000
   .BYTE   0

   STORE   ,5,X            ; Last two arguments supplied
   .LONG   12
   .WORD   X
   .BYTE   5

   STORE   1               ; First argument supplied
   .LONG   1
   .WORD   1000
   .BYTE   0
 

4  Keyword_Arguments
   Keyword arguments allow a macro call to specify the arguments
   in any order. In this case, the macro call must specify the
   same formal argument names that appear in the macro definition.
   Keyword arguments are useful when a macro definition has more
   formal arguments than necessary in the call.

   In any one macro call, it is good practice to specify the
   arguments as either all positional arguments or all keyword
   arguments. For example, the following macro definition specifies
   three arguments:

   .MACRO  STORE   ARG1,ARG2,ARG3
   .LONG   ARG1
   .WORD   ARG3
   .BYTE   ARG2
   .ENDM   STORE

   The following macro call specifies keyword arguments:

   STORE   ARG3=27+5/4,ARG2=5,ARG1=SYMBL
   .LONG   SYMBL
   .WORD   27+5/4
   .BYTE   5

   Because the keywords are specified in the macro call, the
   arguments in the macro call need not be given in the order they
   were listed in the macro definition.

   Positional and keyword arguments may be mixed. Usually,
   positional arguments are placed before keyword arguments. For
   example:

   .MACRO  STORE   ARG1,ARG2,ARG3=27+5/4
   .LONG   ARG1
   .BYTE   ARG2
   .WORD   27+5/4
   .ENDM   STORE

                                  NOTE

      Keyword arguments are not counted when positional arguments
      are parsed. This means that when positional and keyword
      arguments are used in the same macro, one argument can be
      specified twice. The last value specified for the argument
      is used.
 

4  String_Arguments
   If an actual argument is a string containing characters that
   the assembler interprets as separators (such as a tab, space,
   or comma), the string must be enclosed by delimiters. String
   delimiters for macro arguments are usually paired angle brackets
   (<>). A quoted literal enclosed in double quotes ("")  is also a
   valid string argument.

   The assembler also interprets any character
   (except A, B, C, D, O, or X) after an initial circumflex (^)
   as a delimiter. Note that ^B, ^D, ^O, and ^X are used as radix
   control operators rather than argument delimiters. ^A is used
   as the ASCII operator and ^C is used as the complement operator.
   To pass an angle bracket as part of a string, you can use the
   circumflex form of the delimiter.

   The following are examples of delimited macro arguments:

   <HAVE THE SUPPLIES RUN OUT?>
   <LAB:    CLR     R4>

   "A quoted literal is taken as a single parameter value."

   ^%ARGUMENT IS <LAST,FIRST> FOR CALL%
   ^?EXPRESSION IS <5+3>*<4+2>?

   In the last two examples, the initial circumflex indicates
   that the percent sign (%)  and question mark (?) are the
   delimiters. Note that only the left-hand delimiter is preceded
   by a circumflex.

   The assembler interprets a string argument enclosed by delimiters
   as one actual argument and associates it with one formal
   argument. If a string argument that contains separator characters
   is not enclosed by delimiters, the assembler interprets it as
   successive actual arguments and associates it with successive
   formal arguments.

   For example, the following macro definition has one formal
   argument:

   .MACRO DOUBLE_ASCII STRNG
   .ASCII  "STRNG"
   .ASCII  "STRNG"
   .ENDM   DOUBLE_ASCII

   The following two macro calls demonstrate actual arguments with
   and without delimiters:

   DOUBLE_ASCII <A B C D E>
   .ASCII  "A B C D E"
   .ASCII  "A B C D E"

   DOUBLE_ASCII  A B C D E
   %MACRO64-E-TOOMNYARGS, Too many arguments in macro call

   Note that the assembler interprets the second macro call as
   having five actual arguments instead of one actual argument with
   spaces.

   When a macro is called, the assembler removes normal delimiters
   around a string before associating it with the formal arguments.
   However, a quoted literal within double quotes is treated as a
   single token and retains its double quote delimiters.

   If a string contains a semicolon (;),  the string must be
   enclosed by delimiters; otherwise, the semicolon will mark the
   start of the comment field. Further, if the string contains a
   semicolon, you cannot continue the line unless the string is a
   quoted literal.

   You can nest macro invocations, that is, a macro definition can
   contain a call to another macro. If, within a macro definition,
   another macro is called and is passed a string argument, you must
   delimit the argument so that the entire string is passed to the
   second macro as one argument.

   The following macro definition contains a call to the DOUBLE_
   ASCII macro defined earlier:

           .MACRO     CNTDA LAB1,LAB2,STR_ARG
   LAB1:   .BYTE      LAB2-LAB1-1            ; Length of 2*string
             DOUBLE_ASCII   <STR_ARG>
      ; Call DOUBLE_ASCII macro
   LAB2:
           .ENDM    CNTDA

   Note that the argument in the call to DOUBLE_ASCII is enclosed in
   angle brackets even though it does not contain any separator
   characters. The argument is thus delimited because it is a
   formal argument in the definition of the macro CNTDA and will
   be replaced with an actual argument that may contain separator
   characters.

   The following example calls the macro CNTDA, which in turn calls
   the macro DOUBLE_ASCII:

   CNTDA  ST,FIN,<LEARN YOUR ABC'S>
   ST:     .BYTE   FIN-ST-1
           DOUBLE_ASCII <LEARN YOUR ABC'S>
           .ASCII  "LEARN YOUR ABC'S"
           .ASCII  "LEARN YOUR ABC'S"
   FIN:

   In addition to nested macro invocations, you can
   also nest macro definitions. That is, you can define
   one macro within another. In this example, the
   INNER_MACRO_DEF macro is not defined until the OUTER_MACRO_DEF
   macro is invoked and expanded:

           .macro OUTER_MACRO_DEF
               .macro INNER_MACRO_DEF
                   ...
               .endm INNER_MACRO_DEF
           .endm OUTER_MACRO_DEF

   You can use this capability to define a macro that redefines
   itself:

           .macro SETUP
               A = 75
               B = 92
               C = 87
               D = 0
               E = -12
               F = 42
               .macro SETUP
                   ; Setup is done - do nothing
               .endm SETUP
           .endm SETUP

   In this example, the SETUP macro defines a number of assembly
   constants. After the SETUP macro has been expanded once, its
   work is done. Subsequent expansions of the setup macro need not
   take any action. Therefore, the SETUP macro redefines itself
   to a macro whose expansion includes only a comment statement.
   As described elsewhere, when you redefine a macro, the original
   version of the macro is automatically deleted. If that macro is
   currently expanding (as would be the case with the previous SETUP
   macro), the new definition is immediately associated with the
   macro name. However, the old definition is retained until all
   pending expansions complete normally. When all pending expansions
   complete, the old version of the macro is deleted. Thus, the
   SETUP macro may be invoked any number of times in the assembly
   unit. Since the first expansion redefines itself, the expansion
   of the SETUP macro has no effect other than the first time it is
   invoked.

   Another way to pass string arguments in nested macros is to
   enclose the macro argument in nested delimiters.

                                  NOTE

      Each time you use the delimited argument in a macro call,
      the assembler removes the outermost pair of delimiters
      before associating it with the formal argument. This method
      is not recommended because it requires that you know how
      deeply a macro is nested.

   The following macro definition also contains a call to the
   DOUBLE_ASCII macro:

          .MACRO  CNTDA2 LAB1,LAB2,STR_ARG
   LAB1:  .BYTE   LAB2-LAB1-1             ; Length of 2*string
          DOUBLE_ASCII  STR_ARG           ; Call DOUBLE_ASCII macro
   LAB2:
          .ENDM   CNTDA2

   Note that the argument in the call to DOUBLE_ASCII is not
   enclosed in angle brackets.

   The following example calls the macro CNTDA2:

          CNTDA2 BEG,TERM,<<MIND YOUR P'S AND Q'S>>
   BEG:   .BYTE   TERM-BEG-1              ; Length of 2*string
          DOUBLE_ASCII  <MIND YOUR P'S AND Q'S>
          ; Call DOUBLE_ASCII macro
          .ASCII  "MIND YOUR P'S AND Q'S"
          .ASCII  "MIND YOUR P'S AND Q'S"
   TERM:

   Note that even though the call to DOUBLE_ASCII in the macro
   definition is not enclosed in delimiters, the call in the
   expansion is enclosed because the call to CNTDA2 contains nested
   delimiters around the string argument.
 

4  Argument_Concatentation
   The argument concatenation operator, the apostrophe ('),
   concatenates a macro argument with constant text or another
   argument. Apostrophes can either precede or follow a formal
   argument name in the macro source.

   If an apostrophe precedes the argument name, the text before
   the apostrophe is concatenated with the actual argument when
   the macro is expanded. For example, if ARG1 is a formal argument
   associated with the actual argument TEST, then ABCDE'ARG1 is
   expanded to ABCDETEST.

   If an apostrophe follows the formal argument name, the actual
   argument is concatenated with the text that follows the
   apostrophe when the macro is expanded. The apostrophe itself
   does not appear in the macro expansion.

   To concatenate two arguments, separate the two formal arguments
   with two successive apostrophes. Two apostrophes are needed
   because each concatenation operation discards an apostrophe from
   the expansion.

   An example of a macro definition that uses concatenation follows:

           .MACRO CONCAT   A,B
   A''B:   .WORD 0
           .ENDM CONCAT

   Note that two successive apostrophes are used when concatenating
   the two formal arguments A and B.

   An example of a macro call and expansion follows:

           CONCAT  X,Y
   XY:     .WORD 0
 

4  Passing_Numeric_Values_of_Symbols
   When a symbol is specified as an actual argument, the name of
   the symbol, not the numeric value of the symbol, is passed to
   the macro. You can pass the value of the symbol by inserting a
   backslash (\) before the symbol in the macro call. The assembler
   passes the characters representing the decimal value of the
   symbol to the macro. For example, if the symbol COUNT has a value
   of 2 and the actual argument specified is \COUNT, the assembler
   passes the string 2 to the macro; it does not pass the name of
   the symbol, COUNT.

   Passing numeric values of symbols is especially useful with the
   apostrophe (')  concatenation operator for creating new symbols.

   An example of a macro definition for passing numeric values of
   symbols follows:

           .MACRO WORD n
   WORD'n: .WORD n
           .ENDM WORD

   The following example shows a possible call and expansion of the
   macro previously defined:

          X = 1       ; Start counting at 1
          WORD \X
   WORD1: .WORD 1
 

4  Created_Temporary_Labels
   Temporary labels are often very useful in macros. You can create
   a macro definition that specifies temporary labels within it,
   but these temporary labels might be duplicated elsewhere in the
   temporary label block, possibly causing errors. However, the
   assembler can create temporary labels in the macro expansion that
   will not conflict with other temporary labels. These labels are
   called created temporary labels.

   Created temporary labels range from 30000$ to 65535$. Each time
   the assembler creates a new temporary label, it increments the
   numeric part of the label name by 1. Consequently, no user-
   defined temporary labels should be in the range of 30000$ to
   65535$.

   A created temporary label is specified by a question mark (?)  in
   front of the formal argument name. When the macro is expanded,
   the assembler creates a new temporary label if the corresponding
   actual argument is blank. If the corresponding actual argument is
   specified, the assembler substitutes the actual argument for the
   formal argument.

   The following example is a macro definition specifying a created
   temporary label:

           .MACRO  POSITIVE        ARG1,?L1
           BGE     ARG1,L1
           NEGQ    ARG1,ARG1
   L1:    .ENDM    POSITIVE

   The following three calls and expansions of the macro defined
   previously show both created temporary labels and a user-defined
   temporary label:

           POSITIVE  R0
           BGE     R0,30000$
           NEGQ    R0,R0
   30000$:

           POSITIVE  R5
           BGE     R5,30001$
           NEGQ    R5,R5
   30001$:

           POSITIVE  R7,10$
           BGE     R7,10$
           NEGQ    R7,R7
   10$:
 

3  Program_Sections
   MACRO-64 allows you to divide your program into sections called
   psects using the .PSECT directive. Psects are useful for
   organizing your program, and for low-level control over the
   linking process. More importantly, each psect falls into one
   of the following three categories:

   o  CODE psects can contain only instructions. They contain no
      data. Psects in this category have the EXE and NOMIX psect
      attributes.

   o  DATA psects can contain only data. They contain no
      instructions. Psects in this category have the NOEXE and NOMIX
      attributes.

   o  MIXED psects can contain instructions, data, or both. Psects
      in this category have the MIX attribute. In addition, they may
      have either the EXE or NOEXE attribute.

   MACRO-64 categorizes psects because:

   o  There is a significant performance compromise associated
      with mixing instructions and data in the same program section
      within the Alpha architecture. This is because the Alpha
      architecture typically maintains separate memory caches
      for instructions and data.

   o  If you mix instructions and data, it is likely that
      instructions will migrate into the data cache and that
      data will migrate into the instruction cache. While this
      situation still yields correct results, the benefits of the
      instruction and data caches are diminished. Placing data in
      the instruction stream can also have detrimental effects on
      the instruction pipeline and the multiple instruction-issue
      capabilities that most Alpha systems employ.

   Since a code psect can contain only instructions and cannot
   contain arbitrary data, instructions you place in a CODE psect
   can be analyzed by the assembler optimizer and by the symbolic
   debugger. Since a mixed psect can contain arbitrary data as well
   as instructions, instructions you place in a mixed psect are not
   analyzed by the assembler optimizer or by the symbolic debugger.
   Instead, the assembler internally converts instructions in a
   mixed psect to an equivalent data representation.

   Because of the compromises associated with mixed psects, by
   default the assembler creates psects with the NOMIX psect
   attribute. If you need to place data in a psect that has the
   EXE attribute, or if you need to place instructions in a psect
   that has the NOEXE attribute, you must also specify the MIX
   attribute in the psect's definition. Note that unlike the other
   psect attributes, the MIX psect attribute is an assembly-time
   attribute. The MIX psect attribute does not appear in the psect
   definitions in your object module and it does not affect the
   linking process.

   You can use all assembler directives and instructions within
   mixed psects. While many assembler directives can be used
   within both code and data psects, data-storage directives
   cannot be used in code psects and instructions and instruction-
   storage directives cannot be used in data psects. If you place
   instructions or instruction-storage directives in a data psect,
   or if you place data-storage directives in a code psect, the
   assembler issues a diagnostic message.

   In summary, code psects may contain only storage for instructions
   and storage created by instruction directives. Data psects may
   contain only storage created by data directives. Mixed psects may
   contain either storage for instructions or data or both. There
   are no restrictions on the use of data directives in a mixed
   psect. However, the assembler converts instructions you place in
   a mixed psect to a data representation. Therefore, instructions
   in a mixed psect are not analyzed as instructions by either the
   assembler optimizer or the symbolic debugger.
 

3  Automatic_Data_Alignment
   The assembler can optionally align your data on natural
   boundaries. While disabled by default, this feature is
   enabled with the /ALIGNMENT=DATA command-line qualifier or the
   .ENABLE ALIGN_DATA directive. A natural boundary is an address
   that is evenly divisibly by the size of the scalar data type
   being accessed. The MACRO-64 automatic data alignment feature can
   automatically align word, longword, quadword, and octaword data
   to a natural boundary. Accessing data on a natural boundary can
   be significantly faster than an unaligned access.

   When the MACRO-64 automatic data alignment feature is enabled,
   the assembler automatically aligns all data-storage directives to
   a natural boundary. To achieve alignment, the assembler pads
   with 0 bytes as necessary before allocating the storage for
   the data directive. Labels that occur before the data-storage
   directive are defined to be the address of the data storage after
   alignment.
 

3  Directives
   The general assembler directives provide facilities for
   performing eleven types of functions. Some directives are only
   applicable within data psects (psects with the NOEXE and NOMIX
   attributes). Other directives are only applicable within code
   psects (psects with the EXE and NOMIX attributes). All directives
   are applicable within psects that contain either data and code,
   or both (psects with the MIX attribute). For information on the
   MIX assembly-time psect and any associated restrictions, see the
   description of the .PSECT directive in this chapter.

   The following table discusses these types of functions and their
   directives.
 

4  .ADDRESS
   Address storage directive

   Format

     .ADDRESS  address-list
 

5  Parameter
 

address-list

   A list of symbols or expressions, separated by commas (,),  which
   MACRO-64 interprets as addresses.
 

5  Description
   .ADDRESS stores successive quadwords (8 bytes) containing
   addresses in the object module. Digital recommends that you use
   .ADDRESS rather than .QUAD for storing address data to provide
   additional information to the linker.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current (64-bit) boundary before allocating storage.

   o  You can define a 32-bit address item using macros and the
      .LONG directive. For example:

      .macro address_32 item
          .long item
      .endm address_32
 

5  Example

       .ADDRESS A,B,C
 

4  .ALIGN
   Location counter alignment directive

   Format

     .ALIGN  integer [,fill-specifier]

     .ALIGN  keyword [,fill-specifier]
 

5  Parameters
 

integer

   An integer in the range 0 to 9. The location counter is aligned
   at an address that is the value of 2 raised to the power of the
   integer.
 

keyword

   One of five keywords that specify the alignment boundary. The
   location counter is aligned to an address that is the next
   multiple of the following values:

   Keyword  Size (in Bytes)

   BYTE     20= 1
   WORD     21= 2
   LONG     22= 4
   QUAD     23= 8
   OCTA     24= 16
 

[,fill-specifier]

   Any expression that resolves to an assembly-time integer value
   containing no forward references. The filling is done per byte,
   regardless of the alignment. If the value you specify is not in
   the range of 0 to 255, the assembler issues a diagnostic message
   and truncates the value.
 

5  Description
   .ALIGN aligns the location counter to the boundary specified by
   either an integer or a keyword.
 

5  Notes

   o  If .ALIGN is specified in a psect with the EXE and NOMIX
      attributes, the fill-specifier is ignored. The assembler
      aligns the psect to the requested boundary padding with NOP
      or FNOP instructions.

   o  If .ALIGN is specified in a psect that does not have the EXE
      attribute and a fill-specifier is specified, the assembler
      aligns the psect to the requested boundary padding, with byte
      locations using the fill-specifier as the initial value for
      the generated byte padding.

   o  If the fill-specifier expression encounters a value that is
      too large to fit in a boundary specified by the keyword, the
      data is truncated and an informational message is displayed.

   o  The alignment that you specify in .ALIGN cannot exceed the
      alignment of the psect in which the alignment is attempted
      (see the description of .PSECT). For example, if you are using
      the BYTE psect alignment and you specify .ALIGN with a word or
      larger alignment, the assembler displays an error message.
 

5  Examples
     Example 1

          .PSECT A,QUAD  ; Begin at quadword
       B::.BYTE 4        ; Data is byte
          .ALIGN QUAD    ; Next data is
       C::.WORD 6        ; also quadword aligned
     Example 2

          .PSECT A,EXE,NOMIX,OCTA
       L1::TRAPB:        ; offset 0
          .ALIGN OCTA    ; NOP padding bytes 4..15
           TRAPB:         ; offset 16
     Example 3

          .PSECT A,NOEXE,NOMIX,OCTA
       L1:.WORD 5        ; byte offset 0..1
          .ALIGN QUAD,2  ; fill specifier initial value
                         ; of 2 for bytes 2..7
          .WORD 6        ; byte offsets 8..9
 

4  .ASCIC
   Counted ASCII string storage directive

   Format

     .ASCIC  quoted-literal
 

5  Parameter
 

quoted-literal

   An ASCII string delimited with double quotes.
 

5  Description
   .ASCIC performs the same function as .ASCII, except that .ASCIC
   inserts a count byte before the string data. The count byte
   contains the length of the string in bytes. The length given
   includes any bytes of nonprintable characters specified using the
   backslash (\) operator, but excludes the count byte.

   .ASCIC is useful in copying text because the count indicates the
   length of the text to be copied.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  This directive also accepts VAX MACRO syntax.
 

5  Example

       .ASCIC "MY STRING"  ; In the listing, this becomes:
                           ; .BYTE 9
                           ; .ASCII \MY STRING\
 

4  .ASCID
   String-descriptor ASCII string storage directive

   Format

     .ASCID  quoted-literal
 

5  Parameter
 

quoted-literal

   An ASCII string delimited with double quotes.
 

5  Description
   .ASCID performs the same function as the .ASCII directive, except
   that .ASCID inserts a string descriptor before the string data.
   The descriptor format is identical to that defined for OpenVMS
   Alpha and OpenVMS VAX. The string descriptor has the following
   format:
 

5  Notes

   o  String descriptors are used in calling certain system
      routines.

   o  The string-length field is two bytes in size.

   o  Descriptor information (2 bytes) is always set to ^X010E.

   o  The pointer field is a 32-bit pointer to the string (4 bytes).

   o  If natural alignment is enabled (using .ENABLE ALIGN_DATA),
      the descriptor is quadword aligned. This allows you to access
      the entire descriptor (2 data words and a longword address) on
      a quadword boundary.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Examples
     Example 1
       .DESCR1:   .ASCID "ARGUMENT FOR CALL"     ; String descriptor
     Example 2
       .DESCR2:   .ASCID "SECOND ARGUMENT"  ; Another string descriptor
 

4  .ASCII
   ASCII string storage directive

   Format

     .ASCII  quoted-literal
 

5  Parameters
 

quoted-literal

   An ASCII string delimited with double quotes.
 

5  Description
   .ASCII stores the ASCII value of each character in the ASCII
   string or the value of each byte expression in the next available
   byte.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Examples

       .ASCII "MY STRING"
 

4  .ASCIZ
   Zero-terminated ASCII string storage directive

   Format

     .ASCIZ  quoted-literal
 

5  Parameter
 

quoted-literal

   An ASCII string delimited with double quotes.
 

5  Description
   .ASCIZ performs the same function as .ASCII, except that .ASCIZ
   appends a null byte as the final character of the string. When a
   list or text string is created with an .ASCIZ directive, you need
   only perform a search for the null character in the last byte to
   determine the end of the string.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .ASCIZ "MY STRING"    ; Equivalent to
                             ; .ASCII "MY STRING \x00"
 

4  .BASE
   Base register directive

   Format

     .BASE  Rn [,base_expression]
 

5  Parameters
 

Rn

   One of the base registers, R0 through R30, FP, and SP.
 

base_expression

   The base address, which is optional, and can be one of the
   following:

   o  An absolute expression

   o  A relocatable expression

   o  An external expression

   An expression must not contain forward references or implicit
   external symbols. An implicitly defined external symbol is a
   symbol that the assembler defaults to an external symbol. This
   occurs when the assembler encounters references to a symbol, but
   does not encounter a definition for the symbol or an .EXTERNAL
   directive that declares the symbol.
 

5  Description
   The .BASE directive is used to inform the assembler that a
   specified base register contains a specified base address. Later
   in your program, the assembler allows you to implicitly reference
   the specified base register. When the assembler knows which
   base addresses are stored in one or more base registers, it can
   convert an expression to an offset from one of the base registers
   previously specified in a .BASE directive. .BASE provides a
   convenient and more readable shorthand for accessing memory and
   constant values using base registers. .BASE also makes it easier
   for you to change your register assignments if you later modify
   your code.

   The base expression is optional. If the base expression is
   specified, this base address value is assumed by the assembler
   to be in the specified register, Rn. If the base expression is
   omitted, the contents of the specified base register, Rn, is
   considered undefined until a new base expression is associated
   with the base register.

   R31 is defined to always contain 0, according to the architecture
   definition. Therefore, R31 is known to be a predefined base
   register containing 0. For every assembly, the assembler assumes
   the following statement:

       .BASE R31, 0

   Because the contents of R31 cannot change, you cannot specify a
   base address for R31.

   You can use the .BASE directive to implicitly reference base
   registers. You can also automatically compute offsets from a base
   address known to be in a register to a base address you use in an
   instruction argument.

   Most of the memory format Alpha instructions are defined
   such that one of their arguments must have a base register and
   an offset. If the assembler encounters only an expression with
   no base register, the assembler attempts to find a base register
   that contains a base address or constant within a 16-bit signed
   offset of the value of the expression. If it finds such a base
   register, the assembler computes an offset that, when added to
   the value of the base register, results in a value equal to the
   expression specified in the instruction argument.
 

5  Examples
     Example 1
       .EXTERNAL COMM_AREA       1
       .BASE R1, COMM_AREA       2
       CURR_LINE       = COMM_AREA + 0
       CURR_COLUMN     = COMM_AREA + 4
       CURR_MODE       = COMM_AREA + 8
       LDA     R4, 17                  ; LDA R4, 17(R31)  3
       LDL     R2, CURR_LINE           ; LDL R2, 0(R1)    4
       LDL     R3, CURR_COLUMN         ; LDL R3, 4(R1)
       STL     R4, CURR_MODE           ; STL R4, 8(R1)

     1  This statement declares an external symbol, COMM_AREA.
        COMM_AREA is a global symbol that represents the base
        address of a three-longword communication area that is used
        by different routines in the program.

     2  This statement informs the assembler that base register R1
        contains the base address, COMM_AREA, of this communication
        area. The next three statements define variables within the
        communication area.

     3  The first instruction shows how you can load registers
        with constant values in the range -32,768 to +32,767 by
        implicitly using R31 as the base register.

     4  The last three statements show how the .BASE directive
        allows you to implicitly reference base registers
        and automatically compute offsets. In each of these
        instructions, the second argument is defined to require
        an offset and a base register.

        Since no base register is specified, the assembler attempts
        to imply the base register and compute the offset based upon
        information given in previous .BASE directives.

        In the last three instructions, the address argument is
        within -32,768 to +32,767 of the base address known to
        be in R1 (that is, COMM_AREA). Therefore, R1 is selected
        as the base register. The assembler also computes the
        correct offset from the base address known to be in R1 to
        the address specified in the instruction argument.

     Example 2
     The assembler performs a sequential search through the list
     of possible base registers, R0 through R31. It uses the first
     definition possible if multiple base registers are valid. For
     example:

            .BASE R5, 300
            :
            LDQ  R10, 100

     The assembler outputs the LDQ instruction as follows:

            LDQ  R10, -200(R5)

     Both R31 and R5 are defined as base registers that can be used
     in constructing the instruction argument. R31 always contains
     0. In this example, R5 is also known to contain the constant
     300. The assembler uses the first base register, starting at
     R0 and progressing to R31, which provides a known value within
     -32,768 to +32,767 of the specified argument value. Since the
     assembler considers R5 before it considers R31, R5 is used
     rather than R31.
 

4  .BEGIN_EXACT
   Exact instruction block directive

   Format

     .BEGIN_EXACT
 

5  Description
   An exact instruction block suppresses code optimizations
   (SCHEDULE and PEEPHOLE) regardless if these optimizations are
   enabled for the assembly unit. Unlike .ENABLE and .DISABLE, which
   can be used to enable or disable specific optimizations for the
   entire assembly unit, .BEGIN_EXACT and .END_EXACT allow you to
   suppress optimization for a specified range of instructions.
   Instructions outside the specified range remain subject to any
   optimizations you have enabled.
 

5  Notes

   o  This directive cannot appear in a psect with the NOEXE and
      NOMIX attributes.

   o  Although this directive is accepted by the assembler in a
      psect with the MIX attribute, it has no effect in these psects
      since no code optimizations are in affect for MIX psects.

   o  .BEGIN_EXACT must be paired with a matching .END_EXACT to
      close the exact instruction block.

   o  .BEGIN_EXACT and .END_EXACT instruction blocks can be
      nested. The outermost level of the .BEGIN_EXACT and matching
      .END_EXACT directives delimit the actual exact instruction
      block from which code optimizations are suppressed. Nesting
      .BEGIN_EXACT and .END_EXACT instruction blocks can be useful
      in macro definitions where the macro expansion requires an
      exact instruction sequence. Nested .BEGIN_EXACT and .END_EXACT
      instruction blocks allow a macro to be invoked both from
      within and without the exact instruction block.

   o  .BEGIN_EXACT does not affect automatic alignment. Automatic
      alignment is enabled with the .ENABLE ALIGN_CODE and .ENABLE
      ALIGN_DATA directives or with the /ALIGN=(CODE,DATA) command-
      line qualifier.
 

5  Examples

     The following example shows an instruction sequence prior to
     optimization:

            addf f7, f8, f9     ; 1
            addf f2, f3, f4     ; 2
            addl r5, r6, r7     ; 3
            addl r8, r9, r10    ; 4

     The assembler optimizes the previous example to a sequence
     similar to the following instruction sequence:

                    :
            addf f7, f8, f9     ; 1
            addl r5, r6, r7     ; 3
            addf f2, f3, f4     ; 2
            addl r8, r9, r10    ; 4
                    :

     If you choose to suppress optimization in the previous example,
     enclose the four instructions with the .BEGIN_EXACT and
     .END_EXACT directives, as shown in the following example:

            .BEGIN_EXACT
            addf f7, f8, f9     ; 1
            addf f2, f3, f4     ; 2
            addl r5, r6, r7     ; 3
            addl r8, r9, r10    ; 4
            .END_EXACT
 

4  .BLKx
   Block storage allocation directives

   Format

     .BLKA  [expression]

     .BLKB  [expression]

     .BLKD  [expression]

     .BLKF  [expression]

     .BLKG  [expression]

     .BLKL  [expression]

     .BLKO  [expression]

     .BLKQ  [expression]

     .BLKS  [expression]

     .BLKT  [expression]

     .BLKW  [expression]
 

5  Parameter
 

expression

   An integer expression specifying the amount of storage to be
   allocated. All the symbols in the expression must be defined
   at the current point in the assembly and the expression must be
   an absolute expression. If the expression is omitted, a default
   value of 1 is assumed.
 

5  Description
   MACRO-64 has the following 11 block storage directives:

   DirectivReserves Storage for:  Bytes Allocated

   .BLKA   Addresses (quadwords)  8 * value of expression
   .BLKB   Byte data              Value of expression
   .BLKD   Double-precision       8 * value of expression
           floating-point data
           (quadwords)
   .BLKF   Single-precision       4 * value of expression
           floating-point data
           (longwords)
   .BLKG   G_floating data        8 * value of expression
           (quadwords)
   .BLKL   Longword data          4 * value of expression
   .BLKO   Octaword data          16 * value of expression
   .BLKQ   Quadword data          8 * value of expression
   .BLKS   S_floating data        4 * value of expression
           (longwords)
   .BLKT   T_floating data        8 * value of expression
           (quadwords)
   .BLKW   Word data              2 * value of expression

   Each directive reserves storage for a different data type. The
   value of the expression determines the number of data items for
   which MACRO-64 reserves storage. For example, .BLKL 4 reserves
   storage for 4 longwords of data and .BLKB 2 reserves storage for
   2 bytes of data. The total number of bytes reserved is equal to
   the length of the data type times the value of the expression.
 

5  Notes

   o  If automatic data alignment is enabled, the .BLKx directives
      align the current location counter to one of the alignments
      listed in the following table:

      DirectiAlignment

      .BLKA  Quadword (64-bit) boundary
      .BLKB  None
      .BLKD  Quadword (64-bit) boundary
      .BLKF  Longword (32-bit) boundary
      .BLKG  Quadword (64-bit) boundary
      .BLKL  Longword (32-bit) boundary
      .BLKO  Octaword (128-bit) boundary
      .BLKQ  Quadword (64-bit) boundary
      .BLKS  Longword (32-bit) boundary
      .BLKT  Quadword (64-bit) boundary
      .BLKW  Word (16-bit) boundary

   o  You can only use these directives within psects having either
      the NOEXE or MIX attributes.
 

5  Example

           .PSECT A,NOEXE
       B:: .BLKW  10             ; 10 words (20 bytes) of storage
           .BLKQ   5             ; 5 quadwords (40 bytes) of storage

           .BLKW                 ; 1 word (2 bytes) of storage
 

4  .BYTE
   Byte storage directive

   Format

     .BYTE  expression-list
 

5  Parameter
 

expression-list

   One or more expressions separated by commas. Each expression
   is first evaluated as a quadword expression; then the value of
   the expression is truncated to fit in a byte. The value of each
   expression should be in the range 0 to 255 for unsigned data or
   in the range -128 to +127 for signed data.
 

5  Description
   .BYTE generates successive bytes of binary data in the object
   module.
 

5  Notes

   o  The assembler displays a warning message if the expression is
      outside the range -128 to -255.

   o  The assembler will truncate the most significant bits of an
      integer or external value that is too large to store in eight
      bits.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).
 

5  Example

       A:      .BYTE   5       ; Stores 5 in a byte
 

4  .CODE_ADDRESS
   Code address storage directive

   Format

     .CODE_ADDRESS  name-list
 

5  Parameter
 

name-list

   A list of symbols separated by commas. These symbols should
   reference either a procedure descriptor name, such as a routine
   name, or an externally defined procedure descriptor.
 

5  Description
   .CODE_ADDRESS causes the code addresses of the specified
   identifiers to be placed at the current psect and current
   location counter. The specified identifier should reference a
   procedure descriptor defined in the image.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.
 

5  Example

       .CODE_ADDRESS A
 

4  .D_FLOATING
   Floating-point storage directive

   Format

     .D_FLOATING  floating-point-number-list

     .DOUBLE  floating-point-number-list
 

5  Parameter
 

floating-point-number-list

   A comma-separated list of floating-point constants. The constants
   cannot contain any operators except unary plus or unary minus.
 

5  Description
   .D_FLOATING evaluates the specified floating-point constants and
   stores the results in the object module. .D_FLOATING generates
   64-bit, double-precision floating-point data (1 bit of sign, 8
   bits of exponent, and 55 bits of fraction). See the description
   of .F_FLOATING for information on storing single-precision
   floating-point numbers and the descriptions of .G_FLOATING, .S_
   FLOATING, and .T_FLOATING for descriptions of other floating-
   point constants.
 

5  Notes

   o  Double-precision floating-point numbers are always rounded.

   o  The alternate form of .D_FLOATING is .DOUBLE.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.

   o  The Alpha architecture supports only conversion operations
      for the
      D floating-point data type.
 

5  Example

       .D_FLOATING  3.1E+02
 

4  .DEFINE_FREG
   Define floating-point register symbol directive

   Format

     .DEFINE_FREG  regsym regnum
 

5  Parameters
 

regsym

   A MACRO-64 identifier.
 

regnum

   An assembly-time expression or a currently defined register
   symbol.
 

5  Description
   The identifier you specify as the first argument to .DEFINE_FREG
   becomes a floating-point register symbol. Thereafter, it cannot
   be used as a MACRO-64 identifier. Specifically, the user-defined
   register symbol is only allowed where a register is allowed. In
   this sense, the user-defined register symbol is reserved until
   the end of the assembly unit or until you delete its definition
   (see .UNDEFINE_REG), whichever occurs first.

   The second argument to .DEFINE_FREG can be either an integer
   expression or a currently defined floating-point register symbol.
   An integer expression indicates the register number to assign
   to the register symbol. The expression can contain no forward
   or external references and must be in the range of 0 to 31.
   Alternatively, you can define a register symbol in terms of
   another currently defined register symbol. A currently defined
   register symbol is a predefined register symbol or a register
   symbol that you have previously defined. In this case, the new
   register symbol you specify with the first argument receives the
   current value of the register symbol you specify with the second
   argument.
 

5  Notes

   o  You cannot define a floating-point register in terms of an
      integer register and vice versa.

   o  You cannot redefine a currently defined register symbol with a
      different register number. To redefine a register symbol, you
      must first delete the old definition with the .UNDEFINE_REG
      directive.
 

5  Example

           .DEFINE_IREG A0     16      ; A0 is integer register 16
           .DEFINE_IREG A1     R17     ; A1 is integer register 17,
                                       ;  defined in terms of the
                                       ;  predefined R17 register symbol
           .DEFINE_IREG PTR    A0      ; PTR is integer register 16,
                                       ;  defined in terms of the
                                       ;  previously-defined A0 register
                                       ;  symbol
           .DEFINE_FREG $F0    0       ; $F0 is floating register 0
           .DEFINE_FREG $F1    F1      ; $F1 is floating register 1,
                                       ;  defined in terms of the
                                       ;  predefined F1 register symbol
           .DEFINE_FREG RADIUS $F1     ; RADIUS is floating register 1,
                                       ;  defined in terms of the
                                       ;  previously defined $F1
                                       ;  register symbol
           .DEFINE_IREG X1     R5      ; X1 is integer register 5,
                                       ;  defined in terms of the
                                       ;  predefined R5 register symbol
           .DEFINE_IREG X1     5       ; 2nd definition is the same
                                       ;  value, so no diagnostic
                                       ;  results
           .DEFINE_IREG X1     7       ; Warning: redefinition with a
                                       ;  different value
           .DEFINE_IREG X2     F5      ; Error: cannot define an integer
                                       ;  register in terms of a
                                       ;  floating register

           LDQ         R1, (PTR)       ; LDQ R1, (R16)
           LDG         RADIUS, (A1)    ; LDG F1, (R17)
 

4  .DEFINE_IREG
   Define integer register symbol directive

   Format

     .DEFINE_IREG  regsym regnum
 

5  Parameters
 

regsym

   A MACRO-64 identifier.
 

regnum

   An assembly-time expression or a currently defined register
   symbol.
 

5  Description
   The identifier you specify as the first argument to .DEFINE_IREG
   becomes an integer register symbol. Thereafter, it cannot be
   used as a MACRO-64 identifier. Specifically, the user-defined
   register symbol is only allowed where a register is allowed. In
   this sense, the user-defined register symbol is reserved until
   the end of the assembly unit or until you delete its definition
   (see .UNDEFINE_REG), whichever occurs first.

   The second argument to .DEFINE_IREG can be either an integer
   expression or a currently defined integer register symbol.
   An integer expression indicates the register number to assign
   to the register symbol. The expression can contain no forward
   or external references and must be in the range of 0 to 31.
   Alternatively, you can define a register symbol in terms of
   another, currently defined register symbol. A currently defined
   register symbol is a predefined register symbol or a register
   symbol that you have previously defined. In this case, the new
   register symbol you specify with the first argument receives the
   current value of the register symbol you specify with the second
   argument.
 

5  Notes

   o  You cannot define an integer register in terms of a floating-
      point register and vice versa.

   o  You cannot redefine a currently defined register symbol with a
      different register number. To redefine a register symbol, you
      must first delete the old definition with the .UNDEFINE_REG
      directive.
 

5  Example

     Refer to the example in .DEFINE_FREG.
 

4  .DISABLE
   Disable assembler functions directive

   Format

     .DISABLE  argument-list

     .DSABL  argument-list
 

5  Parameter
 

argument-list

   One or more of the symbolic arguments listed in the description
   of .ENABLE. You can use either the long or the short form of the
   symbolic arguments. If you specify multiple arguments, separate
   them by commas, spaces, or tabs.
 

5  Description
   .DISABLE disables the specified assembler function. See the
   description of .ENABLE for more information.

   The alternate form of .DISABLE is .DSABL.
 

4  .ELSE
   Conditional assembly block directive

   Format

     .ELSE
 

5  Description
   A conditional assembly block is a series of source statements
   that is assembled only if a certain condition is met. .IF starts
   the conditional block and .ENDC ends the conditional block; each
   .IF must have a corresponding .ENDC. The .IF directive contains
   a condition test and one or two arguments. The condition test
   specified is applied to the arguments. If the test is met, all
   MACRO-64 statements between .IF and .ELSE are assembled. If
   the test is not met, the statements between .ELSE and .ENDC are
   assembled.

   Conditional blocks can be nested; that is, a conditional block
   can be inside another conditional block. In this case, the
   statements in the inner conditional block are assembled only
   if the condition is met for both the outer and inner block. For
   more information, see the description of the .IF directive.
 

5  Notes

   o  You cannot use the .ELSE directive in the same conditional
      block as the .IF_x directive.

   o  The .ELSE directive is similar to the .IF_FALSE directive.
      However, you can only use .ELSE once within a conditional
      block. .IF_FALSE can be used any number of times in a
      conditional block.
 

5  Example

     Here is an example of a conditional assembly directive:

       .IF EQUAL  ALPHA+1        ; Assemble block if ALPHA+1=0.
         .
         .
       .ELSE                     ; Assemble when .IF=false.
         .
         .
       .ENDC
 

4  .ENABLE
   Enable assembler functions directive

   Format

     .ENABLE  argument-list

     .ENABL  argument-list
 

5  Parameter
 

argument-list

   One or more of the symbolic arguments You can use either the long
   form or the short form of the symbolic arguments.

   If you specify multiple arguments, separate them with commas,
   spaces, or tabs.

   Table 6 .ENABLE and .DISABLE Symbolic Arguments

               Short  Default
   Long Form   Form   Condition  Function

   ALIGN_CODE         Disabled The code alignment option aligns
                             certain branch target labels. The
                             ALIGN_CODE option is disabled for
                             the assembly unit if any one of the
                             following is true:

                             o  /NOALIGNMENT=CODE is specified on
                                the command line.

                             o  .DISABLE ALIGN_CODE is specified in
                                the source program.

                             o  The /ALIGNMENT=CODE option is
                                defaulted.

   ALIGN_DATA         Disabled When ALIGN_DATA is disabled, the data-
                             storage directives put each succeeding
                             item on the next byte boundary.

                             When ALIGN_DATA is enabled, the data-
                             storage directives put each succeeding
                             item on natural boundaries (such as
                             words on word boundaries, longwords on
                             longword boundaries) and add pad bytes
                             as necessary.

                             Accessing data on anything other than
                             natural boundaries usually incurs a
                             significant performance penalty.

                             You can enable or disable the
                             ALIGN_DATA option for specific ranges
                             within your program.

   FLOAT              Enabled Controls whether the assembler
                             generates floating-point instructions
                             when optimizing code and performing
                             code-label alignment.

                             Currently, the only floating-point
                             instruction generated by the assembler
                             during optimization and alignment
                             processing is FNOP, the floating-
                             point no-operation instruction. If you
                             specify .DISABLE FLOAT, the assembler
                             does not generate any floating-point
                             instructions as part of optimization
                             and alignment processing.

                             The initial value of this option is
                             specified by the /ENVIRONMENT=[NO]FLOAT
                             command-line option. The last value of
                             the FLOAT option at the end of assembly
                             determines whether FLOAT is enabled or
                             DISABLED.

   GLOBAL      GBL    Enabled When GLOBAL is enabled, the assembler
                             implicitly treats any undefined symbol
                             as an external reference defined in
                             another module. If the GLOBAL option
                             is disabled, the assembler issues
                             a warning and implicitly treats
                             the undefined symbol as an external
                             reference assumed to be defined in
                             another module. The last value of the
                             GLOBAL option at the end of assembly
                             determines whether the GLOBAL option is
                             enabled or disabled.

   LOCAL_BLOCK LSB    Disabled Used to override the default assembler
                             behavior to define a temporary label
                             block. (A temporary label is of the
                             form n$ where n represents a number.)
                             A temporary label block is usually
                             delimited by two user-defined local
                             or global labels. However, the .ENABLE
                             LOCAL_BLOCK directive defines the start
                             of a block that is terminated by one of
                             the following:

                             o  A second .ENABLE LOCAL_BLOCK
                                directive.

                             o  A .DISABLE LOCAL_BLOCK directive
                                followed by a user-defined local or
                                global label, or a .PSECT directive.

   PEEPHOLE           Disabled Peephole optimization reduces the
                             strength of certain instructions and
                             eliminates instructions where possible.
                             The PEEPHOLE option is disabled for
                             the assembly unit if any one of the
                             following is true:

                             o  /NOOPTIMIZE=PEEPHOLE is specified on
                                the command line.

                             o  .DISABLE PEEPHOLE is specified in
                                the source program.

                             o  The PEEPHOLE option is defaulted.

   PREPROCESSOR_      Enabled When PREPROCESSOR_OUTPUT is enabled,
   OUTPUT                    the MACRO-64 preprocessor processes
                             your source statements and outputs to
                             the preprocessor-output file. If the
                             PREPROCESSOR_OUTPUT option is disabled,
                             your source statements are processed
                             as before. However, output of these
                             statements to the preprocessor-output
                             file is suppressed.

                             Neither .ENABLE PREPROCESSOR_OUTPUT
                             nor .DISABLE PREPROCESSOR_OUTPUT is
                             passed through to the preprocessor-
                             output file. These two directives
                             have no effect unless you specify
                             /PREPROCESSOR_ONLY on the command line.

   SCHEDULE           Disabled Instruction scheduling optimization
                             reorders instructions to more optimally
                             utilize the instruction pipeline.
                             The SCHEDULE option is disabled for
                             the assembly unit if any one of the
                             following is true:

                             o  /NOOPTIMIZE=SCHEDULE is specified on
                                the command line.

                             o  .DISABLE SCHEDULE is specified in
                                the source program.

                             o  The SCHEDULE option is defaulted.
 

5  Description
   .ENABLE enables the specified assembly function. .ENABLE and
   its negative form, .DISABLE, control the following assembler
   functions:

   o  Creating local label blocks

   o  Specifying that undefined symbol references are external
      references

   o  Enabling or disabling specific optimizations for the assembly
      unit

   You can enable one or more specific optimization options with
   either the .ENABLE directive or the /OPTIMIZE command-line
   qualifier, or both. If you explicitly disable one or more
   specific optimization options with the .DISABLE directive, those
   optimization options are disabled regardless of the command-line
   options you specify.
 

5  Notes

   o  The alternate form of .ENABLE is .ENABL.
 

5  Examples
     Example 1
     The following example shows the ALIGN_DATA option:

       .PSECT A, NOEXE
       .ENABLE ALIGN_DATA  ; Align on natural
                           ; natural boundaries
       A: .BYTE 1          ;
       B: .QUAD 1000       ; B is allocated at
                           ; a natural boundary -
                           ; specifically at A + 7
       .DISABLE ALIGN_DATA ;
       C: .BYTE 2          ;
       D: .QUAD 1001       ; D is allocated at
                           ; an unaligned boundary -
                           ; specifically C + 1
     Example 2
     The following example shows the GLOBAL option disabled:

       .DISABLE GLOBAL
       .ADDRESS X         ; Assembler issues a warning
       .END
     Example 3
     The following example shows the LOCAL_BLOCK option enabled:

             .ENABLE LOCAL_BLOCK

             .PSECT A,NOEXE
       A1::
       5$:   .PROCEDURE_DESCRIPTOR PROC_1   ; Temporary label 5$
             .blkb 32
       A2::
             .address 5$         ; By default the declaration
                                 ; of A2 would have ended the
                                 ; temporary label block and
                                 ; made this reference to 5$
                                 ; illegal.  However, this default
                                 ; behavior has been overridden
                                 ; by the use of .ENABLE LOCAL_BLOCK.

             .DISABLE LOCAL_BLOCK
             .END
     Example 4
     The following example shows an unoptimized and optimized list
     of instructions with the SCHEDULE and PEEPHOLE options enabled:

       .ENABLE PEEPHOLE,SCHEDULE
       .psect A,EXE,QUAD     ; unoptimized
       TRAPB
       A::ADDF F1,F2,F3
          ADDF F4,F5,F6
          ADDL R1,R2,R3
          ADDL R4,R5,R6

     This example shows the optimized list of instructions:

       .ENABLE PEEPHOLE,SCHEDULE
       .psect A,EXE,QUAD     ; optimized
       A::ADDF F1,F2,F3
          ADDL R1,R2,R3
          ADDF F4,F5,F6
          ADDL R4,R5,R6

     The following example shows a repeat block that initializes
     a block of 1000 longwords to the values of 0 through 999. The
     .DISABLE PREPROCESSOR_OUTPUT directive suppresses from the
     preprocessor output file those statements that are incompatible
     with the OSF/1 Assembler.

       .DISABLE PREPROCESSOR_OUTPUT
        I=0
       .REPEAT 1000
          .ENABLE PREPROCESSOR_OUTPUT
          .LONG %INTEGER(I)
          .DISABLE PREPROCESSOR_OUTPUT
          I = I + 1
       .ENDR
 

4  .END
   Assembly termination directive

   Format

     .END  [label]
 

5  Parameter
 

label

   The procedure descriptor name that specifies the routine (called
   the transfer address) where program execution begins. This
   argument is optional.
 

5  Description
   .END terminates the source program. No additional text should
   occur beyond this point in the current source file, or in any
   additional source files specified in the command line for this
   assembly. If any additional text does occur, the assembler
   ignores it. The additional text does not appear in the listing
   file nor does it affect the object file.
 

5  Notes

   o  When an executable image consisting of several object modules
      is linked, only one object module should be terminated by an
      .END directive that specifies a transfer address. All other
      object modules should be terminated by .END directives that
      do not specify a transfer address. If an executable image
      contains either no transfer address or more than one transfer
      address, the linker displays an error message.

   o  For more information, see the .PROCEDURE_DESCRIPTOR directive.
 

5  Example

         .
         .
         .
       .PROCEDURE_DESCRIPTOR TRANSFER1,code_address_T1
         .
         .
         .
       .END TRANSFER1        ; TRANSFER1 is module transfer address
 

4  .ENDC
   End conditional directive

   Format

     .ENDC
 

5  Description
   .ENDC terminates the conditional range started by the .IF
   directive. See the description of .IF for more information and
   examples.
 

4  .ENDM
   End macro definition directive

   Format

     .ENDM  [macro-name]
 

5  Parameter
 

macro-name

   The name of the macro whose definition is to be terminated. The
   macro name is optional; if specified, it must match the name
   defined in the matching .MACRO directive. The macro name should
   be specified so that the assembler can detect any improperly
   nested macro definitions.
 

5  Description
   .ENDM terminates the macro definition. See the description of
   .MACRO for an example that uses an .ENDM directive.
 

5  Notes

   o  If .ENDM is encountered outside a macro definition, the
      assembler displays an error message.
 

4  .ENDR
   End repeat range directive

   Format

     .ENDR
 

5  Description
   .ENDR indicates the end of a repeat range. It must be the final
   statement of every repeat block. A repeat block consists of
   any range of text beginning with the .IRP, .IRPC, or .REPEAT
   directive. For more information, see the description for the
   .IRP, .IRPC, or .REPEAT directives for examples of how to use the
   .ENDR directive.
 

5  Notes

   o  If .ENDR is encountered outside a repeat block, the assembler
      displays an error message.
 

4  .END_EXACT
   End exact instruction block directive

   Format

     .END_EXACT
 

5  Description
   .END_EXACT delimits the end of an exact instruction block. An
   exact instruction block suppresses the SCHEDULE and PEEPHOLE
   optimizations for the specified range of instructions regardless
   if code optimizations are enabled for the assembly unit.

   For more information on the .END_EXACT directive, see the
   description of the .BEGIN_EXACT directive in this chapter.
 

4  .ERROR
   Error directive

   Format

     .ERROR  quoted-literal
 

5  Parameter
 

quoted-literal

   A string of characters, between a pair of double quotes,
   displayed during assembly.
 

5  Description
   .ERROR causes the assembler to display an error message on the
   terminal or batch log file and in the listing file (if there is
   one).

   Using .ERROR prevents an output object file from being produced.
 

5  Notes

   o  .PRINT, .WARN, and .ERROR are directives used to display
      messages. You can use them to display information indicating
      unexpected or important conditions within the assembly.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .ERROR "Illegal Arguments"
       ^
       %MACRO64-E-GENERROR, Generated ERROR: Illegal Arguments
       at line number 3 in file DISK$:[TEST]ERROR.M64;2
 

4  .EVEN
   Even location counter alignment directive

   Format

     .EVEN
 

5  Description
   .EVEN ensures that the current value of the location counter
   is even by adding 1 if the current value is odd. If the current
   value is already even, no action is taken.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).
 

4  .EXTERNAL
   External symbol attribute directive

   Format

     .EXTERNAL  symbol-list

     .EXTRN  symbol-list
 

5  Parameter
 

symbol-list

   A list of symbol names separated by commas.
 

5  Description
   .EXTERNAL indicates that the specified symbols are external; that
   is, the symbols are defined in another object module.
 

5  Notes

   o  The alternate form of .EXTERNAL is .EXTRN.
 

5  Example

            .EXTERNAL B    ; B is defined in another module
               .
               .
               .
       A::  .ADDRESS B    ; Its address is stored here
 

4  .F_FLOATING
   Floating-point storage directive

   Format

     .F_FLOATING  floating-point-number-list

     .FLOAT  floating-point-number-list
 

5  Parameter
 

floating-point-number-list

   A list of one or more floating-point constants separated by
   commas. The constants cannot contain any operators except unary
   plus or unary minus.
 

5  Description
   .F_FLOATING evaluates the specified floating-point constant(s)
   and stores the results in the object module. .F_FLOATING
   generates 32-bit, single-precision, floating-point data (1
   bit of sign, 8 bits of exponent, and 23 bits of fractional
   significance). See the description of .D_FLOATING for information
   on storing double-precision floating-point constants and the
   descriptions of .G_FLOATING, S_FLOATING, and T_FLOATING for
   descriptions of other floating-point constants.
 

5  Notes

   o  The alternate form of .F_FLOATING is .FLOAT.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a longword (32-bit) boundary
      before allocating storage.
 

5  Example

       .F_FLOATING 1.0,3.0E+2
 

4  .G_FLOATING
   G_floating-point storage directive

   Format

     .G_FLOATING  floating-point-number-list
 

5  Parameter
 

floating-point-number-list

   A comma-separated list of one or more floating-point constants.
   The constants cannot contain any operators except unary plus or
   unary minus.
 

5  Description
   .G_FLOATING evaluates the specified floating-point constants and
   stores the results in the object module. .G_FLOATING generates
   64-bit data (1 bit of sign, 11 bits of exponent, and 52 bits of
   fraction). See the description of .D_FLOATING for information
   on storing double-precision floating-point constants and the
   descriptions of .F_FLOATING, S_FLOATING, and T_FLOATING for
   descriptions of other floating-point constants.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.
 

5  Example

       .G_FLOATING  2.0E-3
 

4  .IDENT
   Identification directive

   Format

     .IDENT  quoted-literal
 

5  Parameter
 

quoted-literal

   A 1- to 31-character string, within double quotes, that
   identifies the module, such as a string that specifies a version
   number.
 

5  Description
   .IDENT provides a means of identifying the object module. This
   identification is in addition to the name assigned to the object
   module with .TITLE. You can specify a character string in .IDENT
   to label the object module. This string is printed in the header
   of the listing file and also appears in the object module.
 

5  Notes

   o  If a source module contains more than one .IDENT, the last
      directive given establishes the character string that forms
      part of the object module identification.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .IDENT "Module Name"
 

4  .IF
   Conditional assembly block directive

   Format

     .IF  condition argument(s)
        .

        .

        .

     range
        .

        .

        .

     .ENDC
 

5  Parameters
 

condition

   A specified condition that must be met if the block is to be
   included in the assembly. The condition must be separated from
   the argument by a comma, space, or tab.
 

argument(s)

   One or more symbolic arguments or expressions of the specified
   conditional test. If the argument is an expression, it cannot
   contain any undefined symbols. The assembler converts relocatable
   arguments to absolute arguments by discarding the relocatable
   portion of the expression and using only the offset from the
   beginning of the psect. Arguments must be separated by a comma.
 

range

   The block of source code that is conditionally included in the
   assembly.
 

   Table 7 Condition Tests for Conditional Assembly Directives

                                                            Condition
   Condition       Complement                     Number    That
   Test            Condition           Argument   of        Assembles
                   Test                Type       Arguments Block

   Long      Short               Short
   Form      Form  Long Form     Form

   EQUAL     EQ    NOT_EQUAL     NE    Expression 1 or 2    Expression-
                                                            1 is
                                                            equal to
                                                            expression-
                                                            2 or not
                                                            equal to
                                                            expression-
                                                            2.
   GREATER   GT    LESS_EQUAL    LE    Expression 1 or 2    Expression-
                                                            1 is
                                                            greater
                                                            than
                                                            expression-
                                                            2 or
                                                            less
                                                            than or
                                                            equal to
                                                            expression-
                                                            2.
   LESS_     LT    GREATER_      GE    Expression 1 or 2    Expression-
   THAN            EQUAL                                    1 is
                                                            less
                                                            than
                                                            expression-
                                                            2 or
                                                            greater
                                                            than or
                                                            equal to
                                                            expression-
                                                            2.
   DEFINED   DF    NOT_DEFINED   NDF   Symbolic   1         Symbol
                                                            is
                                                            defined
                                                            or not
                                                            defined.
   BLANK     B     NOT_BLANK     NB    Macro      1         Argument
                                                            is blank
                                                            or not
                                                            blank.
   IDENTICAL IDN   DIFFERENT     DIF   Macro      2         Arguments
                                                            are
                                                            identi-
                                                            cal or
                                                            differ-
                                                            ent.
 

5  Description
   A conditional assembly block is a series of source statements
   that are assembled only if a certain condition is met. A .IF
   starts the conditional block and a .ENDC ends the conditional
   block; each .IF must have a corresponding .ENDC. The .IF
   directive contains a condition test and one or two arguments.
   The condition test specified is applied to the arguments. If
   the test is met, all MACRO-64 statements between .IF and .ENDC
   are assembled. If the test is not met, the statements are not
   assembled. Optionally, you can use the .ELSE directive (or a
   combination of the .IFF, .IFT, and .IFTF directives) to specify
   an alternate series of statements to assemble if the test is not
   met.

   You can nest conditional blocks; that is, a conditional block
   can be inside another conditional block. In this case, the
   statements in the inner conditional block are assembled only
   if the condition is met for both the outer and inner block.
 

5  Notes

   o  The assembler displays an error message if the following
      directives occur outside a conditional assembly block: .ENDC,
      .ELSE, .IF_FALSE, .IF_TRUE, .IF_TRUE_FALSE.

   o  MACRO-64 permits a nesting depth of 100 conditional assembly
      levels. If a statement attempts to exceed this nesting level
      depth, the assembler displays an error message.

   o  The effect of logical expressions can only be achieved by
      using several levels of .IF directives. See Example 5.

   o  Lowercase string arguments are converted to uppercase before
      being compared, unless the string is surrounded by double
      quotes or /NAMES=AS_IS is specified on the command line.

   o  The assembler displays an error message if .IF specifies any
      of the following: a condition test other than those which are
      valid, an illegal argument, or a null argument specified in an
      .IF directive.
 

5  Examples
     Example 1
     Here is an example of a conditional assembly directive:

       .IF EQUAL  ALPHA+1        ; Assemble block if ALPHA+1=0. Do
         .                       ;   not assemble if ALPHA+1 not=0
         .
         .
       .ENDC
     Example 2
     Nested conditional directives take the following form:

       .IF   condition argument(s)
       .IF   condition argument(s)
         .
         .
         .
       .ENDC
       .ENDC
     Example 3
     The following conditional directives can govern whether
     assembly of the specified range is to occur:

       .IF DEFINED  SYM1
       .IF DEFINED  SYM2
         .
         .
         .
       .ENDC
       .ENDC

     In this example, if the outermost condition is not satisfied,
     no deeper level of evaluation of nested conditional statements
     within the program occurs. Therefore, both SYM1 and SYM2 must
     be defined for the specified range to be assembled.
     Example 4
     An alternate series of statements can be specified using .ELSE.

       .IF EQUAL A,B        ; Assemble if A is equal to B
       .ELSE                ; Assemble if A is not equal to B
       .ENDC
 

     Example 5
     The following example demonstrates the use of .ELSE and
     nesting:

       .IF LESS_THAN X,Y  ; Assemble if X is less than Y
          .IF DEFINED Z   ; Assemble if Z is defined and
                          ;  X is less than Y
          .ELSE           ; Assemble if Z is not defined and
                          ;  X is less than Y
          .ENDC
       .ELSE              ; Assemble if X is greater than or equal to Y
          .IF DEFINED Z   ; Assemble if Z is defined and X is
                          ;  greater than or equal to Y
          .ENDC
       .ENDC
 

4  .IF_x
   Subconditional assembly block directives

   Format

     .IF_FALSE

     .IF_TRUE

     .IF_TRUE_FALSE
 

5  Description
   For compatibility with VAX MACRO, MACRO-64 provides three
   directives for use within .IF blocks:

   Directive     Function

   .IF_FALSE     If the condition of the assembly block tests false,
                 the program includes the source code following
                 the .IF_FALSE directive and continuing up to the
                 next subconditional directive or to the end of the
                 conditional assembly block.
   .IF_TRUE      If the condition of the assembly block tests true,
                 the program includes the source code following
                 the .IF_TRUE directive and continuing up to the
                 next subconditional directive or to the end of the
                 conditional assembly block.
   .IF_TRUE_     Regardless of whether the condition of the
   FALSE         assembly block tests true or false, the source
                 code following the .IF TRUE_FALSE directive (and
                 continuing up to the next subconditional directive
                 or to the end of the assembly block) is always
                 included.

   The implied argument of a subconditional directive is the
   condition test specified when the conditional assembly block was
   entered. A conditional or subconditional directive in a nested
   conditional assembly block is not evaluated if the preceding (or
   outer) condition in the block is not satisfied (see Example 3 and
   Example 4).

   A conditional block with a subconditional directive is different
   from a nested conditional block. If the condition in the .IF is
   not met, the inner conditional blocks are not assembled, but a
   subconditional directive can cause a block to be assembled.
 

5  Notes

   o  If a subconditional directive appears outside a conditional
      assembly block, the assembler displays an error message.

   o  The alternate forms of .IF_FALSE, .IF_TRUE, and .IF_TRUE_FALSE
      are .IFF, .IFT, and .IFTF.

   o  You cannot use .ELSE in the same conditional block as .IF_x.
 

5  Examples
     Example 1
     Assume that symbol SYM is defined:

          .IF DEFINED   SYM     ; Tests TRUE since SYM is defined.
            .                   ;   Assembles the following code.
            .
            .
          .IF_FALSE             ; Tests FALSE since previous
            .                   ;   .IF was TRUE.  Does not
            .                   ;   assemble the following code.
            .
          .IF_TRUE              ; Tests TRUE since SYM is defined.
            .                   ;   Assembles the following code.
            .
            .
          .IF_TRUE_FALSE        ; Assembles following code
            .                   ;   unconditionally.
            .
            .
          .IF_TRUE              ; Tests TRUE since SYM is defined.
            .                   ;   Assembles remainder of
            .                   ;   conditional assembly block.
            .
          .ENDC
     Example 2
     Assume that symbol X is defined and that symbol Y is not
     defined:

          .IF DEFINED  X        ; Tests TRUE since X is defined.
          .IF DEFINED  Y        ; Tests FALSE since Y is not defined.
          .IF_FALSE             ; Tests TRUE since Y is not defined.
            .                   ;   Assembles the following code.
            .
            .
          .IF_TRUE              ; Tests FALSE since Y is not defined.
            .                   ;   Does not assemble the following
            .                   ;   code.
            .
          .ENDC
          .ENDC
     Example 3
     Assume that symbol A is defined and that symbol B is not
     defined:

          .IF DEFINED  A       ; Tests TRUE since A is defined.
            .                  ;   Assembles the following code.
            .
            .
          .IF_FALSE            ; Tests FALSE since A is defined.
            .                  ;   Does not assemble the following
            .                  ;   code.
            .
          .IF NOT_DEFINED B    ; Nested conditional directive
            .                  ;   is not evaluated.
            .
            .
          .ENDC
          .ENDC
     Example 4
     Assume that symbol X is not defined but symbol Y is defined:

          .IF DEFINED  X       ; Tests FALSE since X is not defined.
            .                  ;   Does not assemble the following
            .                  ;   code.
            .
          .IF DEFINED  Y       ; Nested conditional directive
            .                  ;   is not evaluated.
            .
            .
          .IF_FALSE            ; Nested subconditional
            .                  ;   directive is not evaluated.
            .
            .
          .IF_TRUE             ; Nested subconditional
            .                  ;   directive is not evaluated.
            .
            .
          .ENDC
          .ENDC
 

4  .IIF
   Immediate conditional assembly block directive

   Format

     .IIF  condition [,]argument(s), statement
 

5  Parameters
 

condition

   One of the legal condition tests defined for conditional assembly
   blocks (see the description of .IF). The condition must be
   separated from the arguments by a comma, space, or tab. If the
   first argument can be a blank, the condition must be separated
   from the arguments with a comma.
 

argument(s)

   An expression or symbolic argument associated with the immediate
   conditional assembly block directive. If the argument is an
   expression, it cannot contain any undefined symbols. The
   assembler converts relocatable arguments to absolute arguments
   by discarding the relocatable portion of the expression and using
   only the offset from the beginning of the psect. The arguments
   must be separated from the statement by a comma.
 

statement

   The statement to be assembled if the condition is satisfied.
 

5  Description
   .IIF provides a means of writing a one-line conditional assembly
   block. The condition to be tested and the conditional assembly
   block are expressed completely within the line containing the
   .IIF directive. No terminating .ENDC statement is required or
   allowed.
 

5  Notes

   o  The assembler displays an error message if .IIF specifies a
      condition test other than those which the assembler considers
      valid, an illegal argument, or a null argument.
 

5  Example

     In the following example, the symbol EXAM is defined within the
     source program:

       .IIF DEFINED EXAM, BR ALPHA

     This directive generates the following code:

       BR    ALPHA
 

4  .INCLUDE
   Include source file directive

   Format

     .INCLUDE  quoted-literal
 

5  Parameter
 

quoted-literal

   The name of the source file to be included within double quotes.
   If a logical name exists that is the same as the source file
   name, specify the .M64 file extension to override the logical
   name.
 

5  Description
   .INCLUDE indicates that the current input source file should be
   suspended and that the specified file should be used. When that
   file ends, the original source stream resumes, starting at the
   line after .INCLUDE.
 

5  Notes

   o  The assembler issues an error message if the file nesting
      level exceeds 50.
 

5  Example

       .INCLUDE "file1.m64"
 

4  .INSTRUCTION
   Instruction directive

   Format

     .INSTRUCTION  expression
 

5  Parameter
 

expression

   An absolute expression in the range of -2147483648 to 2147483647.
   The expression cannot be relocatable, external, or complex.
 

5  Description
   The specified value is stored at the current location as an
   instruction. You can use .INSTRUCTION to specify arbitrary
   instructions. Similar to .LONG, .INSTRUCTION stores a longword
   (32 bits) of data. Unlike .LONG, the assembler considers
   .INSTRUCTION an instruction and allows its use in code psects.
 

5  Notes

   o  You can only use this directive within code or mixed psects
      (psects that have either the EXE or MIX attributes).

   o  If automatic data alignment is enabled within a mixed psect,
      this directive aligns the current location counter to a
      longword (32-bit) boundary before allocating storage.

   o  You can use this directive to store arbitrary, longword,
      assembly-time constant data in a code section.
 

5  Example

       .INSTRUCTION 7
 

4  .IRP
   Indefinite repeat argument directive

   Format

     .IRP  symbol,<argument list>

        .

        .

        .

     range

        .

        .

        .

     .ENDR
 

5  Parameters
 

symbol

   A formal argument that is successively replaced with the
   specified actual arguments enclosed in angle brackets (<>).  If
   no formal argument is specified, the assembler displays an error
   message.
 

<argument list>

   A list of actual arguments enclosed in angle brackets and used
   in expanding the indefinite repeat range. An actual argument
   can consist of one or more characters. Multiple arguments must
   be separated by a legal separator (comma, space, or tab). If no
   actual arguments are specified, no action is taken.
 

range

   The block of source text to be repeated once for each occurrence
   of an actual argument in the list. The range can contain macro
   definitions and repeat ranges. .MEXIT is legal within the range
   and causes the current and remaining repetitions to be aborted.
 

5  Description
   .IRP replaces a formal argument with successive actual arguments
   specified in an argument list. This replacement process occurs
   during the expansion of the indefinite repeat block range. The
   .ENDR directive specifies the end of the range.

   .IRP is similar to a macro definition with only one formal
   argument. At each successive expansion of the repeat block, this
   formal argument is replaced with successive elements from the
   argument list. The directive and its range are coded in line
   within the source program. This type of macro definition and
   its range do not require calling the macro by name, as do other
   macros described in this section.

   .IRP can appear either inside or outside another macro
   definition, indefinite repeat block, or repeat block (see the
   description of .REPEAT). The rules for specifying .IRP arguments
   are the same as those for specifying macro arguments.
 

5  Example

     The macro definition is as follows:

       .macro CHECK_PROCEDURE_KIND PROCEDURE_KIND
           OK = 0      ; Assume procedure_kind is unknown
           .irp REFERENCE_KIND,BOUND,NULL, REGISTER,STACK
               .if identical, <PROCEDURE_KIND>, <REFERENCE_KIND>
                   OK = 1 ; Procedure_kind is known
                   .mexit ; No need to look further
               .endc
           .endr
           .if eq, OK  ; If unknown procedure kind
               .error "Unknown procedure kind: PROCEDURE_KIND"
           .endc
       .endm CHECK_PROCEDURE_KIND

       CHECK_PROCEDURE_KIND REGISTER
       CHECK_PROCEDURE_KIND FOOZLE

     The macro call and expansion of the previously defined macro is
     as follows:

       CHECK_PROCEDURE_KIND REGISTER
           OK = 0      ; Assume procedure kind is unknown
           .if identical,<REGISTER>,<BOUND>
           .endc
           .if identical,<REGISTER>,<NULL>
           .endc
           .if identical,<REGISTER>,<REGISTER>
               OK = 1 ; Procedure kind is known
               .mexit ; No need to look further
           .if eq, OK  ; If unknown procedure kind
           .endc

       CHECK_PROCEDURE_KIND FOOZLE
           OK = 0      ; Assume procedure kind is unknown
           .if identical,<FOOZLE>,<BOUND>
           .endc
           .if identical,<FOOZLE>,<NULL>
           .endc
           .if identical,<FOOZLE>,<REGISTER>
           .endc
           .if identical,<FOOZLE>,<STACK>
           .endc
           .if eq, OK  ; If unknown procedure kind
               .error "Unknown procedure kind: FOOZLE"
           .endc

     In this example the CHECK_PROCEDURE_KIND macro uses the
     .IRP directive to iterate over a list of reference keywords
     to determine if its argument matches one of the reference
     keywords. If a match is not found, the macro displays an error
     message.
 

4  .IRPC
   Indefinite repeat character directive

   Format

     .IRPC  symbol,<STRING>

        .

        .

        .

     range

        .

        .

        .

     .ENDR
 

5  Parameters
 

symbol

   A formal argument that is successively replaced with the
   specified characters enclosed in angle brackets (<>).  If no
   formal argument is specified, the assembler displays an error
   message.
 

<STRING>

   A sequence of characters enclosed in angle brackets and used in
   the expansion of the indefinite repeat range. Although the angle
   brackets are required only when the string contains separating
   characters, their use is recommended for legibility.
 

range

   The block of source text to be repeated once for each occurrence
   of a character in the list. The range can contain macro
   definitions and repeat ranges. .MEXIT is legal within the range.
 

5  Description
   .IRPC is similar to .IRP except that .IRPC permits single-
   character substitution rather than argument substitution. On each
   iteration of the indefinite repeat range, the formal argument is
   replaced with each successive character in the specified string.
   The .ENDR directive specifies the end of the range.

   .IRPC is similar to a macro definition with only one formal
   argument. At each expansion of the repeat block, this formal
   argument is replaced with successive characters from the actual
   argument string. The directive and its range are coded in line
   within the source program and do not require calling the macro by
   name.

   .IRPC can appear either inside or outside another macro
   definition, indefinite repeat block, or repeat block (see
   description of .REPEAT).
 

5  Example

     The macro definition is as follows:

           .macro X_COUNT ARG
               COUNT = 0
               .irpc CH,<ARG>
                   .iif identical,<CH>,<X>, COUNT = COUNT + 1
               .endr
           .endm X_COUNT

     The macro call and expansion of the macro defined previously is
     as follows:

           X_COUNT XXFOOXBARXX
               COUNT = 0
               .irpc CH,<XXFOOXBARXX>
                   .iif identical,<CH>,<X>, COUNT = COUNT + 1
               .endr
                   .iif identical,<X>,<X>, COUNT = COUNT + 1
                   .iif identical,<X>,<X>, COUNT = COUNT + 1
                   .iif identical,<F>,<X>, COUNT = COUNT + 1
                   .iif identical,<O>,<X>, COUNT = COUNT + 1
                   .iif identical,<O>,<X>, COUNT = COUNT + 1
                   .iif identical,<X>,<X>, COUNT = COUNT + 1
                   .iif identical,<B>,<X>, COUNT = COUNT + 1
                   .iif identical,<A>,<X>, COUNT = COUNT + 1
                   .iif identical,<R>,<X>, COUNT = COUNT + 1
                   .iif identical,<X>,<X>, COUNT = COUNT + 1
                   .iif identical,<X>,<X>, COUNT = COUNT + 1

               .print "%integer(COUNT)"
       %MACRO64-I-GENPRINT, Generated PRINT: 5

     This example uses the .IRPC directive to iterate over the
     characters in the argument to the X_COUNT macro. Each time
     an argument character is X, the variable COUNT is incremented.
     After the X_COUNT macro has expanded, the example uses the
     %INTEGER() lexical operator to display the value of COUNT.
 

4  .LIBRARY
   Macro library directive

   Format

     .LIBRARY  quoted-literal1 [quoted-literal2]
 

5  Parameters
 

quoted-literal1

   A string enclosed within double quotes that is the file
   specification of a macro library. If a logical name exists and
   it is the same as the macro library name, specify the .MLB file
   extension to override the logical name.
 

quoted-literal2

   An optional string enclosed within double quotes that specifies
   a search list of file specifications where the assembler should
   look for the specified macro library. The assembler successively
   processes the search list in left-to-right order and attempts to
   locate the specified macro library in each location specified in
   the search list until the macro library is found. If the macro
   library is not found, the assembler issues a diagnostic message.
   If you omit the second argument to the .LIBRARY directive, the
   assembler uses the following search list by default:

   o  The current device and directory

   o  The device and directory specified by the logical name
      MACRO64$LIBRARY (if defined)

   o  The device and directory specified by the logical name
      ALPHA$LIBRARY (if defined)

   o  The device and directory specified by the logical name
      SYS$LIBRARY

   Logical names may be defined as OpenVMS search lists.
 

5  Description
   .LIBRARY adds a name to the macro library list that is searched
   whenever a .MCALL or an undefined opcode is encountered. The
   libraries are searched in the reverse order in which they were
   specified to the assembler.

   If you omit any information from the macro-library-name file
   description, default values are assumed. The device defaults to
   your current default disk; the directory defaults to your current
   default directory; the file type defaults to MLB.
 

5  Example

       .LIBRARY "MY_MACROS" 1
       .LIBRARY "PROJ_MACROS" "PROJ:[MACRO],PROJ:[DEVELOPMENT]" 2

     1  The first statement adds the macro library MY_MACROS.MLB
        to the macro library list. The assembler first looks for
        MY_MACROS.MLB in the current directory. If not found there,
        the assembler next looks in the directory or directories
        indicated by the MACRO64$LIBRARY logical name if it is
        defined. If not found there or if MACRO64$LIBRARY is not
        defined, the assembler next looks in the directory or
        directories indicated by the ALPHA$LIBRARY logical name
        if it is defined. If not found there or if ALPHA$LIBRARY is
        not defined, the assembler next looks in the directory or
        directories indicated by the SYS$LIBRARY logical name. If
        not found there, the assembler issues a diagnostic message.

     2  The second statement adds the macro library PROJ_MACROS.MLB
        to the macro library list. The assembler first looks for
        PROJ_MACROS.MLB in the PROJ:[MACRO] directory. If not found
        there, the assembler next looks in the PROJ:[DEVELOPMENT]
        directory. If not found there, the assembler issues a
        diagnostic message.
 

4  .LINKAGE_PAIR
   Linkage directive

   Format

     .LINKAGE_PAIR  name
 

5  Parameter
 

name

   The name of the procedure descriptor, possibly defined in a
   different module of the routine to which linkage is required.
 

5  Description
   .LINKAGE_PAIR causes a linkage pair to be stored at the current
   location counter. A linkage pair consists of two quadwords. The
   first quadword is the code entry point of the routine indicated
   by the specified identifier. The second quadword is the address
   of the procedure descriptor of the routine indicated by the
   specified identifier. The second quadword is also called the
   procedure value. The specified name should reference a procedure
   descriptor that is either defined within the assembly unit or
   that becomes defined at the time the program is linked.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to an octaword (128-bit) boundary
      before allocating storage.
 

5  Example

       .LINKAGE_PAIR A     ; Code address A followed by address of
                           ; procedure descriptor A
 

4  .LIST
   Listing directive

   Format

     .LIST  [argument-list]
 

5  Parameter
 

argument-list

   One or more of the symbolic arguments You can use either the long
   form or the short form of the arguments. If multiple arguments
   are specified, separate them with commas, spaces, or tabs.
 

5  Description
   .LIST is equivalent to .SHOW. See the description of .SHOW for
   more information.
 

4  .LOCAL_CODE_ADDRESS
   Local code address storage directive

   Format

     .LOCAL_CODE_ADDRESS  name-list
 

5  Parameter
 

name-list

   A list of symbols separated by commas. Each symbol references a
   procedure descriptor defined in the current module.
 

5  Description
   .LOCAL_CODE_ADDRESS causes the code addresses of the specified
   identifiers to be placed at the current psect and current
   location counter. The specified identifier must reference a
   procedure descriptor defined within the module. The .LOCAL_
   CODE_ADDRESS directive, rather than the .CODE_ADDRESS directive,
   must be used with procedure descriptor names that are local (as
   opposed to global) to the assembly unit.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.
 

5  Example

       .PROCEDURE_DESCRIPTOR P1,C1
       .BLKQ 1
       .LOCAL_CODE_ADDRESS P1       ; Code address
                                    ; of P1...address of C1...
                                    ; is stored here.
 

4  .LOCAL_LINKAGE_PAIR
   Local linkage directive

   Format

     .LOCAL_LINKAGE_PAIR  name
 

5  Parameter
 

name

   The name of a procedure descriptor of the routine to which
   linkage is required. The specified procedure descriptor must
   be defined in the current module.
 

5  Description
   .LOCAL_LINKAGE_PAIR causes a linkage pair to be stored at
   the current location counter. A linkage pair consists of a
   code address and the address of the specified identifier. The
   specified name must reference a procedure descriptor that is
   defined within the assembly unit.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to an octaword (128-bit) boundary
      before allocating storage.
 

5  Example

       .PROCEDURE_DESCRIPTOR P1,CA1
        .
        .
        .
       .LOCAL_LINKAGE_PAIR P1        ; Code address CA1 followed by
                                     ; procedure descriptor address P1.
 

4  .LOCAL_PROCEDURE_DESCRIPTOR
   Procedure descriptor labeling directive

   Format

     .LOCAL_PROCEDURE_DESCRIPTOR  pd-name, ca-name
 

5  Parameters
 

pd-name

   The name of the procedure descriptor. This name can be up to 31
   characters long. It cannot be a temporary label.
 

ca-name

   The name of the code address that corresponds to the procedure
   descriptor. This name must be defined later in the program as
   a label in a psect that has either the EXE or MIX attribute, or
   both. This name can be up to 31 characters long. It cannot be a
   temporary label.
 

5  Description
   .LOCAL_PROCEDURE_DESCRIPTOR defines a bivalued local identifier
   that is used to represent a local routine. The first value
   is the procedure value, which is the address of the procedure
   descriptor. This value is defined as the current location counter
   at the point where you use the .LOCAL_PROCEDURE_DESCRIPTOR
   directive. The second value is the code address, which is
   the code entry-point address of the procedure. This value is
   defined by the second argument to the .LOCAL_PROCEDURE_DESCRIPTOR
   directive. No storage is allocated.
 

5  Notes

   o  See the OpenVMS Calling Standard for a full description of
      procedure descriptors.

   o  You must specify .LOCAL_PROCEDURE_DESCRIPTOR before the code
      of the routine it describes.

   o  See the description for the $PROCEDURE_DESCRIPTOR and $ROUTINE
      library macros. These macros define the procedure identifier
      and define the storage for the procedure descriptor.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before defining the procedure identifier.
 

5  Example

       .LOCAL_PROCEDURE_DESCRIPTOR LP1,C1
 

4  .LONG
   Longword storage directive

   Format

     .LONG  expression-list
 

5  Parameter
 

expression-list

   One or more expressions separated by commas.
 

5  Description
   .LONG generates successive longwords (4 bytes) of data in the
   object module. The assembler truncates on the left of an integer
   or external value.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a longword (32-bit) boundary
      before allocating storage.

   o  You can define a 32-bit address item using macros and the
      .LONG directive. For example:

      .macro address_32 item
      .long item
      .endm address_32
 

5  Example

       .LONG 4     ; Places 4 in 4 bytes of storage.
 

4  .MACRO
   Macro definition directive

   Format

     .MACRO  macro-name [formal-argument-list]
        .

        .

        .

     range
        .

        .

        .

     .ENDM  [macro-name]
 

5  Parameters
 

macro-name

   The name of the macro to be defined; this name can be any legal
   symbol up to 31 characters long.
 

formal-argument-list

   The symbols, separated by commas, to be replaced by the actual
   arguments in the macro call.
 

range

   The source text to be included in the macro expansion.
 

5  Description
   .MACRO begins the definition of a macro. It gives the macro name
   and a list of formal arguments. The .MACRO directive is followed
   by the source text to be included in the macro expansion. The
   .ENDM directive specifies the end of the range.

   Macro names do not conflict with user-defined symbols. Both a
   macro and a user-defined symbol can have the same name.

   When the assembler encounters a .MACRO directive, it adds the
   macro name to its macro name table and stores the source text
   of the macro (up to the matching .ENDM directive). No other
   processing occurs until the macro is expanded.

   The symbols in the formal argument list are associated with the
   macro name and are limited to the scope of the definition of that
   macro. For this reason, the symbols that appear in the formal
   argument list can also appear elsewhere in the program.
 

5  Notes

   o  If a macro has the same name as an Alpha opcode, the macro
      is used instead of the instruction. This feature allows you to
      temporarily redefine an opcode.

   o  You can redefine a macro by using a .MACRO directive with the
      same name as in a previous macro definition. Therefore, the
      previous macro definition is implicitly deleted and the new
      macro definition supersedes the previous definition. See the
      .MDELETE directive for more information on macro deletion.

   o  You can nest a macro definition within another macro
      definition. The inner macro is not defined until the outer
      macro is invoked.

   o  You can nest a macro invocation so that one macro can invoke
      another. The assembler supports nested macro invocations to a
      depth of 1000. If a macro invokes itself, either directly or
      indirectly, it is recursive. Recursive macros must specify a
      basis-step in order to avoid infinite recursion. A basis-step
      is a macro exit condition that will eventually cause the macro
      to exit, which ends the recursion (see Example 3).
 

5  Examples
     Example 1
     This example shows how macro definitions and invocations may
     be nested. It also shows examples of the various forms of
     parameter passing.


       .MACRO OP1 A,B=R4,?C
       C:      ADDL R2, B, R3
       .MACRO OP'B
               TRAPB
       .ENDM OP'B
               ADDL A, R2, R3
               OP'B
               .MDELETE OP'B
       .ENDM OP1

     When OP1 is invoked "OP1 R0", the text expands to:

       33000$: ADDL R2, R4, R3
       .MACRO OPR4
               TRAPB
       .ENDM
               ADDL R0, R2, R3
               OPR4
               .MDELETE OPR4

     Processing this text will cause OPR4 to be expanded to TRAPB;
     the final text will be:

       33000$: ADDL R2, R4 R3
               ADDL R0, R2, R3
               TRAPB

     Example 2
     The following example shows macro redefinition:

       .MACRO INITIALIZE
          .MACRO INITIALIZE   ;Redefine to nothing
          .ENDM INITIALIZE
          X=0
          Y=1
          Z=-1
       .ENDM INITIALIZE

     Note that while the redefined version of the macro immediately
     supersedes the previous definition in any subsequent
     invocation, the invocation of the original definition expands
     to completion.
     Example 3
     This example shows a recursive macro:

       .MACRO FACTORIAL N
          .IF EQUAL <N>,0      ;Basis step; stop at zero
             F=1
          .ELSE
             FACTORIAL <N-1>
             F = F * <N>
          .ENDC
       .ENDM FACTORIAL
 

4  .MCALL
   Macro call directive

   Format

     .MCALL  macro-name-list
 

5  Parameter
 

macro-name-list

   A list of macros to be defined for this assembly. Separate the
   macro names with commas.
 

5  Description
   .MCALL specifies the names of the system and user-defined macros
   that are required to assemble the source program but are not
   defined in the source file.

   If any named macro is not found upon completion of the search
   (that is, if the macro is not defined in any of the macro
   libraries), the assembler displays an error message.
 

5  Notes

   o  Using the .MCALL directive is optional unless the macro name
      is the same as an opcode or assembler directive. The assembler
      automatically searches for a library macro when it encounters
      an identifier that is not an opcode or directive in the
      opcode field. If your macro name is the same as an opcode or
      directive, you must use the .MCALL directive. You can also use
      the .MCALL directive in your program to document which macros
      are used by your program.
 

5  Example

       .MCALL TRAPB       ; Substitute macro in library for
                          ; TRAPB instruction
 

4  .MDELETE
   Macro deletion directive

   Format

     .MDELETE  macro-name-list
 

5  Parameter
 

macro-name-list

   A list of macros whose definitions are to be deleted. You can
   separate the macros with commas or spaces.
 

5  Description
   .MDELETE deletes the definitions of specified macros.

   .MDELETE completely deletes the macro. If you delete a macro that
   is currently expanding (such as a macro that deletes itself),
   the macro name is immediately removed from the macro name table
   and the macro is marked for deletion. When the macro finishes
   expanding, it is deleted.
 

5  Example

       .MACRO FOO
       .PRINT "In macro FOO"
       .ENDM FOO
       FOO
       .MDELETE FOO
 

4  .MEXIT
   Macro exit directive

   Format

     .MEXIT
 

5  Description
   .MEXIT terminates a macro expansion before the end of the macro.
   Termination is the same as if .ENDM were encountered. You can
   also use the directive within repeat blocks. .MEXIT is useful
   in conditional expansion of macros and repeat blocks because it
   bypasses the complexities of nested conditional directives and
   alternate assembly paths.
 

5  Notes

   o  When .MEXIT occurs in a repeat block, the assembler terminates
      the current repetition of the range and suppresses further
      expansion of the repeat range.

   o  When macros or repeat blocks are nested, .MEXIT exits to the
      next higher level of expansion.

   o  If .MEXIT occurs outside a macro definition or a repeat block,
      the assembler displays an error message.
 

5  Examples
     Example 1
     The following macro definition uses the .MEXIT directive
     to exit the current macro when it has finished processing a
     particular kind of argument:

               .macro STORE REG, LOCATION
                   .if identical,<REG>,<FP>
                       STQ REG, LOCATION
                       .mexit
                   .endc
                   .if identical,<REG>,<SP>
                       STQ REG, LOCATION
                       .mexit
                   .endc
                   .if identical,<%extract(0,1,<REG>)>,<R>
                       STQ REG, LOCATION
                       .mexit
                   .endc
                   .if identical,<%extract(0,1,<REG>)>,<F>
                       STT REG, LOCATION
                       .mexit
                   .endc
                   .error "Register argument is not a register"
               .endm STORE

     Example 2
     In this example, the STORE macro (as defined in Example 1)
     attempts to recognize its REG argument as either FP, SP, an
     integer register (a register with R as its first letter),
     or a floating-point register (a register with F as its first
     letter). The following example show two expansions of the STORE
     macro:

               STORE R1, 0(SP)
                   .if identical,<R1>,<FP>
                   .endc
                   .if identical,<R1>,<SP>
                   .endc
                   .if identical,<%extract(0,1,<R1>)>, <R>
                   .if identical,<R>,<R>
                       STQ R1, 0(SP)
                       .mexit

               STORE 24(SP), 16(SP)
                   .if identical,<24(SP)>,<FP>
                   .endc
                   .if identical,<24(SP)>,<SP>
                   .endc
                   .if identical,<%extract(0,1,<24(SP)>)>,<R>
                   .if identical,<2>,<R>
                   .endc
                   .if identical, <%extract(0,1<24(SP)>)>,<F>
                   .if identical,<2>,<F>
                   .endc
                   .error "Register argument is not a register"

     The first call of the STORE macro stores R1 at 0(SP). The
     STORE macro determines to do an integer store by recognizing
     the letter R as the first letter of the register name. After
     it has done so, it abandons further expansion of the macro
     using the .MEXIT directive. The second invocation attempts to
     store 24(SP) at 16(SP). Since the STORE macro cannot identify
     24(SP) as a legitimate register in any of the four forms it
     recognizes, the STORE macro does not attempt to store the
     REG argument, and does not abandon expansion with the .MEXIT
     directive. Instead, the STORE macro expands and issues a
     diagnostic message.
 

4  .NARG
   Number of arguments directive

   Format

     .NARG  symbol
 

5  Parameter
 

symbol

   A symbol that is assigned a value equal to the number of
   positional arguments in the macro call.
 

5  Description
   .NARG determines the number of arguments in the current macro
   call.

   .NARG counts all the positional arguments specified in the macro
   call, including null arguments (specified by adjacent commas).
   The value assigned to the specified symbol does not include
   any keyword arguments or any formal arguments that have default
   values.
 

5  Notes

   o  If .NARG appears outside a macro, the assembler displays an
      error message.
 

5  Examples
     Example 1
     The macro definition is as follows:

       .MACRO  CNT_ARG A1,A2,A3,A4,A5,A6,A7,A8,A9=DEF9,A10=DEF10
       .NARG   COUNTER         ; COUNTER is set to no. of ARGS
       .WORD   COUNTER         ; Store value of COUNTER
       .ENDM   CNT_ARG
     Example 2
     The macro calls and expansions of the macro previously defined
     are as follows:

       CNT_ARG TEST,FIND,ANS   ; COUNTER will = 3
       .NARG   COUNTER         ; COUNTER is set to no. of ARGS
       .WORD   COUNTER         ; Store value of COUNTER

       CNT_ARG                 ; COUNTER will = 0
       .NARG   COUNTER         ; COUNTER is set to no. of ARGS
       .WORD   COUNTER         ; Store value of COUNTER

       CNT_ARG TEST,A2=SYMB2,A3=SY3      ; COUNTER will = 1
       .NARG   COUNTER         ; COUNTER is set to no. of ARGS
       .WORD   COUNTER         ; Store value of COUNTER
                               ; Keyword arguments are not counted

       CNT_ARG ,SYMBL,,        ; COUNTER will = 4
       .NARG   COUNTER         ; COUNTER is set to no. of ARGS
       .WORD   COUNTER         ; Store value of COUNTER
                               ; Null arguments are counted
 

4  .NCHR
   Number of characters directive

   Format

     .NCHR  symbol,<string>
 

5  Parameters
 

symbol

   A symbol that is assigned a value equal to the number of
   characters in the specified character string.
 

<string>

   A sequence of printable characters. Delimit the character
   string with angle brackets (<>)  (or a character preceded by a
   circumflex (^))  only if the specified character string contains
   a legal separator (comma, space, or tab) or a
   semicolon (;).
 

5  Description
   .NCHR determines the number of characters in a specified
   character string. It can appear anywhere in an MACRO-64 program
   and is useful in calculating the length of macro arguments.
 

5  Notes

   o  You can use the %LENGTH lexical operator instead of the .NCHR
      directive.
 

5  Examples
     Example 1
     The macro definition is as follows:

       .MACRO   CHAR    MESS                  ; Define MACRO
       .NCHR    CHRCNT,<MESS>      ; Assign value to CHRCNT
       .WORD    CHRCNT                        ; Store value
       .ASCII   "MESS"                        ; Store characters
       .ENDM    CHAR                          ; Finish
     Example 2
     The macro calls and expansions of the macro previously defined
     are as follows:

       CHAR     <HELLO>                        ; CHRCNT will = 5
       .NCHR    CHRCNT,<HELLO>                 ; Assign value to CHRCNT
       .WORD    CHRCNT                          ; Store value
       .ASCII   "HELLO"                         ; Store characters

       CHAR     <14, 75.39  4>                 ; CHRCNT will = 12(dec)
       .NCHR    CHRCNT,<14, 75.39  4>          ; Assign value to CHRCNT
       .WORD    CHRCNT                          ; Store value
       .ASCII   "14, 75.39  4"                  ; Store characters
 

4  .NLIST
   Listing exclusion directive

   Format

     .NLIST  [argument-list]
 

5  Parameter
 

argument-list

   One or more of the symbolic arguments Use either the long form
   or the short form of the arguments. If you specify multiple
   arguments, separate them with commas, spaces, or tabs.
 

5  Description
   .NLIST is equivalent to .NOSHOW. See the description of .SHOW for
   more information.
 

4  .NOSHOW
   Listing exclusion directive

   Format

     .NOSHOW  [argument-list]
 

5  Parameter
 

argument-list

   One or more of the symbolic arguments listed in the description
   of .SHOW. Use either the long form or the short form of the
   arguments. If you specify multiple arguments, separate them with
   commas, spaces, or tabs.
 

5  Description
   .NOSHOW specifies listing control options. See the description of
   .SHOW for more information.
 

4  .OCTA
   Octaword storage directive

   Format

     .OCTA  expression-list
 

5  Parameter
 

expression-list

   A list of constant values separated by commas. Each value results
   in a 64-bit value being sign-extended to 128 bits and stored in
   an octaword.
 

5  Description
   .OCTA generates 128 bits (16 bytes) of binary data.
 

5  Notes

   o  The low quadword contains the specified constant value.

   o  The high quadword contains the sign extension of the specified
      constant value. That is, the high quadword contains 0 if the
      specified value is positive, and it contains all bits set to 1
      if the specified value is negative.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to an octaword (128-bit) boundary
      before allocating storage.
 

5  Example

       .OCTA  0                         ; OCTA 0
       .OCTA  ^X01234ABCD5678F9         ; OCTA hex value specified

       .OCTA  VINTERVAL                 ; VINTERVAL has 64-
bit value,

                                        ;   sign-extended
 

4  .ODD
   Odd location counter alignment directive

   Format

     .ODD
 

5  Description
   .ODD ensures that the current value of the location counter is
   odd by adding 1 if the current value is even. If the current
   value is already odd, no action is taken.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).
 

4  .PACKED
   Packed decimal string storage directive

   Format

     .PACKED  decimal-string[,symbol]
 

5  Description
   .PACKED is supplied as a library macro with MACRO-64.
 

4  .PAGE
   Page ejection directive

   Format

     .PAGE
 

5  Description
   .PAGE forces a new page in the listing. The directive itself is
   also printed in the listing and begins the new page.

   .PAGE in a macro definition is ignored. The paging operation is
   performed only during macro expansion. If the .PAGE directive
   occurs during macro expansion, text beginning with the original
   macro invocation line appears at the top of a new page.
 

5  Example

       .MACRO SKIP    ; macro definition with .PAGE
       .PAGE          ;
       .ENDM SKIP     ;
       .PSECT A,NOEXE ;
       .BLKW 10       ;
       SKIP           ; In the listing file, a form feed
                      ;  will be inserted here
 

4  .PRINT
   Assembly message directive

   Format

     .PRINT  quoted-literal
 

5  Parameter
 

quoted-literal

   The string of characters enclosed in quotes are displayed when
   encountered during assembly.
 

5  Description
   .PRINT causes the assembler to display an informational message.
   The message consists of the string.
 

5  Notes

   o  .PRINT, .WARN, and .ERROR are directives that display
      messages. You can use these to display information indicating
      unexpected or important conditions within the assembly.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .PRINT "Questionable usage"
       ^
       %MACRO64-I-GENPRINT, Generated PRINT: Questionable usage
       at line number 3 in file DISK$:[TEST]PRINT.M64;2
 

4  .PROCEDURE_DESCRIPTOR
   Procedure descriptor labeling directive

   Format

     .PROCEDURE_DESCRIPTOR  pd-name, ca-name
 

5  Parameters
 

pd-name

   The name of the procedure descriptor. This name can be up to 31
   characters long. It cannot be a temporary label.
 

ca-name

   The name of the code address that corresponds to the procedure
   descriptor. This name must be defined later in the program as
   a label in a psect that has either the EXE or MIX attribute, or
   both. This name can be up to 31 characters long. It cannot be a
   temporary label.
 

5  Description
   .PROCEDURE_DESCRIPTOR defines a bivalued global identifier
   that is used to represent a global routine. The first value
   is the procedure value, which is the address of the procedure
   descriptor. This value is defined as the current location counter
   at the point where you use the .PROCEDURE_DESCRIPTOR directive.
   The second value is the code address, which is the code entry-
   point address of the procedure. This value is defined by the
   second argument to the .PROCEDURE_DESCRIPTOR directive. No
   storage is allocated.
 

5  Notes

   o  See the OpenVMS Calling Standard for a full description of
      procedure descriptors.

   o  You must specify .PROCEDURE_DESCRIPTOR before the code of the
      routine it describes.

   o  See the descriptions for the $PROCEDURE_DESCRIPTOR and
      $ROUTINE library macros. These macros define the procedure
      identifier and define the storage for the procedure
      descriptor.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before defining the procedure identifier.
 

4  .PSECT
   Program sectioning directive

   Format

     .PSECT  program-section-name[,argument-list]
 

5  Parameters
 

program-section-name

   The name of the program section (psect).
 

argument-list

   A list containing the program section attributes and the program
   section alignment. Program sections are aligned when you specify
   an integer in the range of 0 to 16 or one of the five keywords
   listed in the following table. If you specify an integer, the
   program section is linked to begin at the next virtual address
   that is a multiple of two raised to the power of the integer. If
   you specify a keyword, the program section is linked to begin at
   the next virtual address that is a multiple of the corresponding
   value listed in the following table:

   KeywordSize (in Bytes)

   BYTE   20 = 1
   WORD   21 = 2
   LONG   22 = 4
   QUAD   23 = 8
   OCTA   24 = 16

   QUAD is the default.

   Table 8 Program Section Attributes

   AttribuFunction

   ABS    Absolute-The program section has an absolute address. An
          absolute program section contributes no binary code to
          the image, so its byte allocation request to the linker
          is 0. You cannot store initial values in an absolute
          program section with directives such as .BYTE, .WORD,
          .LONG, .QUAD. Usually the .BLKx directives are used in
          conjunction with label definitions within an absolute
          program section to define symbolic offsets within a
          structure. Compare this attribute with its opposite, REL.

   CON    Concatenate-Program sections with the same name and
          attributes (including CON) from other modules are
          concatenated into one program section at link time. Their
          contents are concatenated in the order in which the linker
          acquires them. The allocated virtual address space is the
          sum of the individual requested allocations. Compare this
          attribute with its opposite, OVL.

   EXE    Executable-The program section contains instructions.
          This attribute provides the capability of separating
          instructions from read-only and read/write data. The
          linker uses this attribute in gathering program sections
          and in verifying that the transfer address is in an
          executable program section. The assembler only allows
          you to place instructions in a program section that has
          either or both the EXE or MIX attributes. Compare this
          attribute with its opposite, NOEXE.

   GBL    Global-Program sections that have the same name and
          attributes will be combined at link time into a single
          program section even when the individual program sections
          are in different clusters. This attribute is specified
          for Fortran COMMON block program sections. Compare this
          attribute with its opposite, LCL.

   LCL    Local-The program section is restricted to its cluster.
          Compare this attribute with its opposite, GBL.

   MIX    Mix-The program section can contain both data and
          instructions. The MIX and NOMIX attributes are assembly-
          time attributes that only affect assembler processing.
          The MIX and NOMIX attributes do not appear in the object
          module and do not affect linker processing. To mix
          instructions and data in the same psect, you must specify
          the MIX attribute. The NOMIX attribute is the default. If
          you choose to use instructions in a NOEXE psect, or use
          data directives in an EXE psect, you must specify the MIX
          attribute. The following limitations apply when using the
          MIX attribute:

          o  Optimizations and alignment of code labels are not
             performed. Optimizations and code-label alignment are
             not performed on instructions placed in a MIX psect,
             regardless of whether the .ENABLE/.DISABLE options have
             been set, or if the command-line /OPTIMIZATION and
             /ALIGNMENT=CODE options have been specified.

          o  Limited debugging information is provided. No PC-line
             (program counter) correlation information is generated
             for the instructions placed in a MIX psect.

          o  The listing file includes only binary encoded
             instructions. All instructions that are placed in a
             MIX psect appear in the machine-code portion of the
             listing file, in their binary encoded instruction form
             as a data initializer to the .LONG data directive.

          There are no restrictions on data directives. Compare this
          attribute with its opposite, NOMIX.

   NOEXE  Not Executable-The program section contains data only; it
          does not contain instructions. The assembler only allows
          you to place data allocations in a program section that
          has either or both the NOEXE and MIX attributes. Compare
          this attribute with its opposite, EXE.

   NOMIX  The default attribute when you use the .PSECT directive.
          Compare this attribute with its opposite, MIX.

   NOPIC  Non-Position-Independent Content-The program section is
          assigned to a fixed location in virtual memory (when it
          is in a shareable image). Compare this attribute with its
          opposite, PIC.

   NORD   Nonreadable-Reserved for future use. Compare this
          attribute with its opposite, RD.

   NOSHR  No Share-The program section is reserved for private use
          at execution time by the initiating process. Compare this
          attribute with its opposite, SHR.

   NOWRT  Nonwritable-The contents of the program section cannot
          be altered (written into) at execution time. Compare this
          attribute with its opposite, WRT.

   OVR    Overlay-Program sections with the same name and attributes
          (including OVR) from other modules receive the same
          relocatable base address in memory at link time. The
          allocated virtual address space is the requested
          allocation of the largest overlaying program section.
          Compare this attribute with its opposite, CON.

   PIC    Position-Independent Content-The program section can be
          relocated; that is, it can be assigned to any memory area
          (when it is in a shareable image). Compare this attribute
          with its opposite, NOPIC.

   RD     Readable-Reserved for future use. Compare this attribute
          with its opposite, NORD.

   REL    Relocatable-The linker assigns the program section a
          relocatable base address. The contents of the program
          section can be code or data. Compare this attribute with
          its opposite, ABS.

   SHR    Share-The program section can be shared at execution time
          by multiple processes. This attribute is assigned to a
          program section that can be linked into a shareable image.
          Compare this attribute with its opposite, NOSHR.

   WRT    Write-The contents of the program section can be altered
          (written into) at execution time. Compare this attribute
          with its opposite, NOWRT.

   Table 9 Default Program Section Attributes

   Default
   Attribute   Opposite Attribute

   CON         OVR
   EXE         NOEXE
   LCL         GBL
   NOMIX       MIX
   NOPIC       PIC
   NOSHR       SHR
   RD          NORD
   REL         ABS
   WRT         NOWRT
 

5  Description
   .PSECT defines a program section and its attributes and refers to
   a program section after it is defined. Use program sections to do
   the following:

   o  Develop modular programs.

   o  Separate instructions from data.

   o  Allow different modules to access the same data.

   o  Protect read-only data and instructions from being modified.

   o  Identify sections of the object module to the linker and the
      debugger.

   o  Control the order in which program sections are stored in
      virtual memory.

   When the assembler encounters a .PSECT directive that specifies
   a new program section name, it creates a new program section
   and stores the name, attributes, and alignment of the program
   section. The assembler includes all data or instructions that
   follow the .PSECT directive in that program section until it
   encounters another .PSECT directive. The assembler starts all
   program sections at a relative location counter of 0.

   The assembler does not automatically define program sections.
   Any code or data placed before the first .PSECT directive in the
   source code produces an assembly error.

   If the assembler encounters a .PSECT directive that specifies
   the name of a previously defined program section, it stores the
   new data or instructions after the last entry in the previously
   defined program section, even with program sections that have
   the OVR attribute. (OVR program sections from separate modules
   are overlaid by the linker. The OVR attribute does not affect
   how multiple contributions to a psect are processed within a
   single assembly unit.) You need not relist the attributes when
   continuing a program section, but any attributes that are listed
   must be the same as those previously in effect for the program
   section. A continuation of a program section cannot contain
   attributes conflicting with those specified, or defaulted, in
   the original .PSECT directive.

   The attributes listed in the .PSECT directive describe the
   contents of the program section. Except for the EXE and NOEXE
   attributes, the assembler does not check to ensure that the
   contents of the program section actually adhere to the attributes
   listed. However, the assembler and the linker do check that
   all program sections with the same name have exactly the same
   attributes. The assembler and linker display an error message if
   the program section attributes are not consistent.

   Program section names are independent of local symbol, global
   symbol, and macro names. You can use the same symbolic name
   for a program section and for a local symbol, global symbol,
   or macro name. You may want to use unique names for clarity and
   maintainability.
 

5  Notes

   o  The .ALIGN directive cannot specify an alignment greater than
      that of the current program section; consequently, .PSECT
      should specify the largest alignment needed in the program
      section.

   o  For efficiency of execution and ease of programming, an
      alignment of quadword or larger is recommended for all program
      sections that have quadword data.
 

5  Example

       .PSECT A,QUAD,EXE     ; Code psect
 

4  .QUAD
   Quadword storage directive

   Format

     .QUAD  expression-list
 

5  Parameter
 

expression-list

   One or more expressions separated by commas.
 

5  Description
   .QUAD generates 64 bits (8 bytes) of binary data.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.
 

5  Example

       A:: .QUAD 4
 

4  .REPEAT
   Repeat block directive

   Format

     .REPEAT expression
        .

        .

        .

     range
        .

        .

        .

     .ENDR
 

5  Parameters
 

expression

   An expression whose value controls the number of times the range
   is to be assembled within the program. When the expression is
   less than or equal to 0, the repeat block is not assembled. The
   expression must be absolute or relocatable and must not contain
   any undefined symbols. The assembler converts a relocatable value
   to the relative offset within the psect.
 

range

   The source text to be repeated the number of times specified by
   the value of the expression. The repeat block can contain macro
   definitions or other repeat blocks. .MEXIT is legal within the
   range and causes the current and all succeeding repetitions to be
   aborted.
 

5  Description
   .REPEAT repeats a block of code a specified number of times in
   line with other source code. The .ENDR directive specifies the
   end of the range.
 

5  Notes
   The alternate form of .REPEAT is .REPT.
 

5  Examples
     Example 1
     The following macro definition uses the .REPEAT directive to
     store an ASCII string a specified number of times, followed by
     a 0 byte:

       .MACRO  COPIES  STRING,NUM
       .REPEAT NUM
       .ASCII  "STRING"
       .ENDR
       .BYTE   0
       .ENDM   COPIES
     Example 2
     The following macro call stores five copies of the string
     ABCDEF. This example is divided into four parts:

     Macro invocation:

       COPIES  <ABCDEF>,5

     Macro expansion of .REPEAT invocation:

         .REPEAT 5
         .ASCII  "ABCDEF"
         .ENDR

     .REPEAT expansion:

         .ASCII  "ABCDEF"
         .ASCII  "ABCDEF"
         .ASCII  "ABCDEF"
         .ASCII  "ABCDEF"
         .ASCII  "ABCDEF"

     End of macro expansion:

         .BYTE   0
     Example 3
     The following macro call stores three copies of the string How
     Many Times. This example is divided into four parts:

     Macro invocation:

         VARB = 3
         COPIES  <How Many Times>,VARB

     Macro expansion of .REPEAT invocation:

         .REPEAT VARB
         .ASCII  "How Many Times"
         .ENDR

     .REPEAT expansion:

         .ASCII  "How Many Times"
         .ASCII  "How Many Times"
         .ASCII  "How Many Times"

     End of macro expansion:

         .BYTE   0
 

4  .RESTORE_PSECT
   Restore previous program section context directive

   Format

     .RESTORE_PSECT

     .RESTORE
 

5  Description
   .RESTORE_PSECT retrieves the program section from the top of
   the program section context stack, an internal stack in the
   assembler. If the stack is empty when .RESTORE_PSECT is issued,
   the assembler displays an error message. When .RESTORE_PSECT
   retrieves a program section, it restores the current location
   counter to the value it had when the program section was saved.
   The maximum stack level is 50. See the description of .SAVE_PSECT
   for more information.
 

5  Notes

   o  The alternate form of .RESTORE_PSECT is .RESTORE.

   o  You cannot use .RESTORE_PSECT to overwrite previous data-
      storage initializations. In the following example, MACRO-
      64 attempts to store 42 over 43 and fails, resulting in a
      diagnostic:

      .PSECT A
      .SAVE PSECT
      .PSECT A
      .QUAD 43
      .RESTORE PSECT
      .QUAD 42
 

5  Example

           .PSECT A,QUAD,NOEXE
       A1: .WORD 5
       A2: .QUAD 6
           .SAVE_PSECT        ; Saves psect A context
           .PSECT B,QUAD,NOEXE
       B1: .WORD 6
           .RESTORE_PSECT     ; Return A location counter
       A3: .WORD 5

           .PSECT B,QUAD,NOEXE
       1$: .WORD 5
           .SAVE LOCAL_BLOCK  ; Saves psect B context and temporary
                              ; label context

           .PSECT C,NOEXE
       1$: .WORD 6
           .RESTORE_PSECT     ; Restores psect B and saves
                              ; label context
           .ADDRESS 1$        ; References the address of
                              ; psect B temporary label 1$
 

4  .SAVE_PSECT
   Save current program section context directive

   Format

     .SAVE_PSECT  [LOCAL_BLOCK]

     .SAVE  [LOCAL_BLOCK]
 

5  Description
   .SAVE_PSECT stores the current program section context on the
   top of the program section context stack, an internal assembler
   stack. It leaves the current program section context in effect.
   The program section context stack can hold up to 50 entries.
   Each entry includes the value of the current location counter
   and the maximum value assigned to the location counter in the
   current program section. If the stack is full when .SAVE_PSECT is
   encountered, an error occurs.

   If the LOCAL_BLOCK option is specified, the current temporary
   label block is saved with the current program section context.

   .SAVE_PSECT and .RESTORE_PSECT are especially useful in macros
   that define program sections. See the description of .RESTORE_
   PSECT for an example using .SAVE_PSECT.
 

5  Notes

   o  The alternate form of .SAVE_PSECT is .SAVE.
 

4  .S_FLOATING
   Single-precision IEEE floating-point arithmetic directive

   Format

     .S_FLOATING  floating-point-number-list
 

5  Parameter
 

floating-point-number-list

   A list of IEEE single-precision floating-point constants
   separated by commas.
 

5  Description
   .S_FLOATING evaluates the specified floating-point constants and
   stores the results in the object module. .S_FLOATING generates
   32-bit, single-precision, floating-point data (1 bit of sign, 8
   bits of exponent, and 23 bits of fractional significance). See
   the description of .T_FLOATING for information on storing double-
   precision floating-point IEEE numbers and the descriptions of
   .D_FLOATING, .F_FLOATING, and .G_FLOATING for descriptions of
   other floating-point numbers.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a longword (32-bit) boundary
      before allocating storage.
 

5  Example

       .S_FLOATING 2.0,3.0,4.405
 

4  .SHOW
   Listing inclusion and exclusion directives

   Format

     .SHOW  [argument-list]

     .NOSHOW  [argument-list]
 

5  Parameter
 

[argument-list]

   You can use either the long form or the short form of the
   arguments. If you specify multiple arguments, you must separate
   them by commas. If any argument is not specifically included in
   a listing control statement, the assembler assumes its default
   value (show or noshow) throughout the source program.

   Table 10 .SHOW and .NOSHOW Symbolic Arguments

                 Short
   Long Form     Form     Default  Function

   BINARY        MEB      Noshow   Lists macro and repeat block
                                   expansions that generate binary
                                   code. BINARY is a subset of
                                   EXPANSIONS.
   CONDITIONALS  CND      Noshow   Lists unsatisfied conditional
                                   code associated with the
                                   conditional assembly directives.
   EXPANSIONS    ME       Noshow   Lists macro and repeat range
                                   expansions.
   LIBRARY       None     Noshow   Includes the macro definitions in
                                   a library in the listing.
   INCLUDE       None     Noshow   Lists include file text in the
                                   listing file.
 

5  Description
   .SHOW and .NOSHOW specify listing control options in the source
   text of a program. You can use .SHOW and .NOSHOW with or without
   an argument list.

   .SHOW and .NOSHOW control the listing of the source lines that
   are in conditional assembly blocks (see the description of .IF),
   macros, and repeat blocks. When you use them without arguments,
   these directives alter the listing level count. The listing level
   count is initialized to 0. Each time .SHOW appears in a program,
   the listing level count is incremented; Each time .NOSHOW appears
   in a program, the listing level count is decremented.

   When the listing level count is negative, the listing is
   suppressed unless the line contains an error. Conversely, when
   the listing level count is positive, the listing is generated.
   When the count is 0, the line is either listed or suppressed,
   depending on the value of the listing control symbolic arguments.
 

5  Notes

   o  The listing level count allows macros to be listed
      selectively; a macro definition can specify .NOSHOW at the
      beginning to decrement the listing count and can specify .SHOW
      at the end to restore the listing count to its original value.

   o  The alternate forms of .SHOW and .NOSHOW are .LIST and .NLIST.

   o  The initial setting for each .LIST/.SHOW option (except
      BINARY) is obtained from the command-line setting using the
      /SHOW qualifier.

   o  The /[NO]SHOW=BINARY option overrides the .[NO]SHOW BINARY
      directive.
 

5  Example

       .NOSHOW   ; Turn off listing file display.  Counter < 0.
          .
          .
          .
       .SHOW     ; Turn on listing file display.  Counter = 0.
                 ; Value of .SHOW options are used.
          .
          .
          .
       .SHOW     ; Counter > 0.  Listing file display is
                 ; on for all options regardless of setting.
          .
          .
          .
 

4  .SIGNED_BYTE
   Signed byte storage directive

   Format

     .SIGNED_BYTE  expression-list
 

5  Parameters
 

expression-list

   An expression or list of expressions separated by commas. Each
   expression specifies a value to be stored. The value must be in
   the range of -128 through +127.
 

5  Description
   .SIGNED_BYTE generates successive bytes of binary data in the
   object module and performs signed range checking. Apart from
   the range check, .SIGNED_BYTE is equivalent to .BYTE for storage
   allocation.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).
 

5  Example

       .PSECTA,NOEXE
       .SIGNED_BYTE   LABEL1-LABEL2  ;  Data must fit
       .SIGNED_BYTE   -126           ;     in a byte
 

4  .SIGNED_WORD
   Signed word storage directive

   Format

     .SIGNED_WORD  expression-list
 

5  Parameter
 

expression-list

   An expression or list of expressions separated by commas. Each
   expression specifies a value to be stored. The value must be in
   the range of -32,768 through +32,767.
 

5  Description
   .SIGNED_WORD generates successive words of binary data in the
   object module and performs signed range checking. Apart from
   the range check, .SIGNED_WORD is equivalent to .WORD in terms of
   storage allocation.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a word (16-bit) boundary
      before allocating storage.
 

5  Example

       .PSECT $DATA,NOEXE
       .SIGNED_WORD -32766;
       .SIGNED_WORD 32769 ;causes assembly error
 

4  .SUBTITLE
   Listing subtitle directive

   Format

     .SUBTITLE  quoted-literal

     .SBTTL  quoted-literal
 

5  Parameter
 

quoted-literal

   An ASCII string enclosed in quotes from 1 to 31 characters long;
   excess characters are truncated.
 

5  Description
   .SUBTITLE causes the assembler to print the line of text as
   the subtitle on the second line of each assembly listing page.
   This subtitle text is printed on each page until altered by a
   subsequent .SUBTITLE directive in the program.
 

5  Notes

   o  The alternate form of .SUBTITLE is .SBTTL.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .SUBTITLE "Terminal Display Routines"
 

4  .T_FLOATING
   Double-precision IEEE floating-point arithmetic directive

   Format

     .T_FLOATING  floating-point-number-list
 

5  Parameter
 

floating-point-number-list

   A list of IEEE double-precision floating-point constants
   separated by commas.
 

5  Description
   .T_FLOATING evaluates the specified floating-point constants and
   stores the results in the object module. .T_FLOATING generates
   64-bit, double-precision, floating-point data (1 bit of sign, 11
   bits of exponent, and 52 bits of fractional significance). See
   the description of .S_FLOATING for information on storing single-
   precision floating-point IEEE numbers and the descriptions of .D_
   FLOATING, .F_FLOATING, and .G_FLOATING for descriptions of other
   floating-point numbers.
 

5  Notes

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a quadword (64-bit) boundary
      before allocating storage.
 

5  Example

       .T_FLOATING 4.5036,6.034
 

4  .TITLE
   Listing title directive

   Format

     .TITLE  module-name ["listing-title"]
 

5  Parameters
 

module-name

   Either a quoted literal or an identifier that specifies the
   module's title.
 

"listing-title"

   Optional quoted literal that specifies a title to appear within
   the first line of each listing output file.
 

5  Description
   .TITLE assigns a name to the object module.
 

5  Notes

   o  The module name specified with .TITLE bears no relationship
      to the file specification of the object module, as specified
      in the MACRO-64 command line. The object module name appears
      in the linker load map and is also the module name that the
      debugger and librarian recognize.

   o  If .TITLE is not specified, MACRO-64 assigns the default
      name (.MAIN.) to the object module. If more than one .TITLE
      directive is specified in the source program, the last .TITLE
      directive encountered establishes the name for the entire
      object module.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .TITLE "MAIN" "Main Entry Point"
 

4  .UNDEFINE_REG
   Undefine register symbol directive

   Format

     .UNDEFINE_REG  regsym
 

5  Parameter
 

regsym

   A currently defined floating-point or integer register symbol.
 

5  Description
   The register symbol that you specify as the argument to the
   .UNDEFINED_REG directive is no longer a register symbol. Starting
   with the statement that follows the .UNDEFINE_REG directive, you
   can use the symbol as a MACRO-64 identifier.
 

5  Notes

   o  If you specify a MACRO-64 identifier that is not currently
      defined as a register symbol, the .UNDEFINE_REG directive has
      no effect.
 

5  Example

          .DEFINE_IREG  X1    R5      ; X1 is integer register 5
          .UNDEFINE_REG X1            ; X1 is an identifier again
          .DEFINE_IREG  X1    7       ; X1 is integer register 7 -
no
                                       ;  redefinition and no warning

           $ROUTINE F0                 ; Error: F0 is a register and
                                       ;  cannot be used as an
                                       ;  identifier
           .UNDEFINE_REG F0            ; F0 is no longer a register
           $ROUTINE F0                 ; Ok now
 

4  .WARN
   Warning directive

   Format

     .WARN  quoted-literal
 

5  Parameter
 

quoted-literal

   The string of characters enclosed in quotes are displayed during
   assembly.
 

5  Description
   .WARN causes the assembler to display a warning message on the
   terminal or in the batch log file, and in the listing file (if
   there is one).
 

5  Notes

   o  .PRINT, .WARN, and .ERROR are directives that display
      messages. You can use them to display information indicating
      an unexpected or important assembly condition.

   o  This directive also accepts VAX MACRO syntax. See the
      VAX MACRO and Instruction Set Reference Manual for details.
 

5  Example

       .WARN "Illegal parameter value; 0 assumed"
       ^
       %MACRO64-W-
GENWARN, Generated WARNING: Illegal parameter value; 0 assumed
       at line number 3 in file DISK$:[TEST]WARN.M64;2
 

4  .WEAK
   Weak symbol attribute directive

   Format

     .WEAK  symbol-list
 

5  Parameter
 

symbol-list

   A list of identifiers separated by commas.
 

5  Description
   .WEAK specifies symbols that are either defined externally in
   another module or defined globally in the current module. .WEAK
   suppresses any object library search for the symbol.

   When .WEAK specifies a symbol that is not defined in the current
   module, the symbol is externally defined. If the linker finds the
   symbol's definition in another module, it uses that definition.
   If the linker does not find an external definition, the symbol
   has a value of 0 and the linker does not report an error. The
   linker does not search a library for the symbol, but if a module
   brought in from a library for another reason contains the symbol
   definition, the linker uses it.

   When .WEAK specifies a symbol that is defined in the current
   module, the symbol is considered to be globally defined. However,
   if this module is inserted in an object library, this symbol
   is not inserted in the library's symbol table. Consequently,
   searching the library at link time to resolve this symbol does
   not cause the module to be included.
 

5  Example

           .WEAK A,B,C
       A:: .WORD 5     ; A and B are weak global definitions
       B:: .QUAD 6
           .ADDRESS C  ; C is a weak external reference
 

4  .WORD
   Word storage directive

   Format

     .WORD  expression-list
 

5  Parameter
 

expression-list

   One or more expressions separated by commas.
 

5  Description
   .WORD generates successive words (2 bytes) of data in the object
   module.
 

5  Notes

   o  The expression is first evaluated as a quadword and then
      truncated to a word. The value of the expression should be
      in the range of -32,768 to +32,767 for signed data or 0 to
      65,535 for unsigned data. The assembler displays an error if
      the high-order 6 bytes of the quadword expression have a value
      other than zero or ^XFFFFFFFFFFFF.

   o  The assembler truncates on the left of an integer or external
      value.

   o  Addresses are not allowed with .WORD.

   o  You can only use this directive within data or mixed psects
      (psects that have either the NOEXE or MIX attributes).

   o  If automatic data alignment is enabled, this directive aligns
      the current location counter to a word (16-bit) boundary
      before allocating storage.
 

5  Example

       .WORD 5,6,7
 

3  Supplied_Library_Macros
   The MACRO-64 assembler provides a library of macros that help you
   to program in conformance with the OpenVMS Calling Standard. This
   library also allows you to define your own opcodes and packed
   decimal data. The library, called MACRO64.MLB, is installed on
   your system with the MACRO-64 assembler.

   The MACRO-64 assembler automatically adds the MACRO64.MLB library
   to the library list before it begins processing your source
   program. Consequently, you do not need to add it manually using
   the .LIBRARY directive.

   The following macros are supplied by the MACRO-64 Assembler:

      $BEGIN_EPILOGUE
      $CALL
      $CODE_SECTION
      $DATA_SECTION
      $END_EPILOGUE
      $END_PROLOGUE
      $END_ROUTINE
      $LINKAGE_PAIR
      $LINKAGE_SECTION
      $OPDEF
      .PACKED
      $PROCEDURE_DESCRIPTOR
      $RESET_LP_LIST
      $RETURN
      $ROUTINE
 

4  Routines_and_Lexical_Scope
   The calling-standard macros use the concept of a single, current,
   active routine. A routine is a programming entity that is
   associated with a procedure descriptor that may be called, or
   is a main routine specified as the transfer address of a linked
   image.

   Only one routine can be active or current at any given time
   during assembly. If more than one routine is defined in a single
   assembler source file, all items associated with the current
   routine, that is, within the lexical scope of the routine, must
   be completed before making a different routine current. The
   lexical scope of one routine cannot overlap the lexical scope
   of another routine.

   A routine becomes current or comes into scope by invoking the
   $ROUTINE macro with the appropriate arguments. $ROUTINE marks the
   beginning of the lexical scope of a routine. The complementary
   macro, $END_ROUTINE, marks the end of the current routine's
   lexical scope.
 

5  Routines_and_Program_Sections
   Routines have three types of associated program sections:

   o  Code section-Contains the executable instructions of the
      routine. This section is typically read-only and executable.

   o  Data section-Contains data accessed by a routine. Typically,
      this is where variable data is stored. This section is
      typically nonexecutable, readable, and writeable.

   o  Linkage section-Contains a routine's procedure descriptor and
      the necessary linkage information for calling other routines,
      and for linkage to data not in the linkage section, if any.
      Also, constant data may be placed here. Typically, this
      section is read-only and not executable.

      The linkage section is considered a type of data section with
      the following function:

      -  Provides linkage information for calls made from a routine
         associated with the linkage section.

      -  Provides linkage information for data outside of the
         linkage section.

      -  Defines the associated routine's procedure descriptor so
         that calls can be made to the routine.

      -  Defines constant or static data.
 

4  Using_Macros_to_Control_Program_Sections
   The following section explains how to use the MACRO-64 supplied
   macros to define and control the various program sections during
   assembly.
 

5  Defining_Program_Sections
   Each of the three program section types can be referenced by a
   corresponding macro. The following three macros are used to refer
   to and define these three psects associated within a routine:

   o  $CODE_SECTION-makes the routine's code psect current.

   o  $DATA_SECTION-makes the routine's data psect current.

   o  $LINKAGE_SECTION-makes the routine's linkage psect current.

   To switch to one of the current routine's sections, you invoke
   the corresponding macro. For example, after invoking $ROUTINE,
   to place instructions into the current routine's code psect,
   you invoke the $CODE_SECTION macro. This makes the code psect
   associated with the current routine the current psect. Similarly,
   invoking $LINKAGE_SECTION makes the linkage psect associated with
   the current routine the current psect.

   You can also control the psect name and attributes for each of
   the program sections by defining arguments to the $ROUTINE macro.
 

5  Using_Macro_Defined_Symbols
   When you use any of the supplied macros described in this
   chapter, with the exception of $OPDEF, the following register
   symbols are defined for you:

      .DEFINE_IREG $IA0 R16 ; Integer argument 0
      .DEFINE_IREG $IA1 R17 ; Integer argument 1
      .DEFINE_IREG $IA2 R18 ; Integer argument 2
      .DEFINE_IREG $IA3 R19 ; Integer argument 3
      .DEFINE_IREG $IA4 R20 ; Integer argument 4
      .DEFINE_IREG $IA5 R21 ; Integer argument 5
      .DEFINE_FREG $FA0 F16 ; Floating-point argument 0
      .DEFINE_FREG $FA1 F17 ; Floating-point argument 1
      .DEFINE_FREG $FA2 F18 ; Floating-point argument 2
      .DEFINE_FREG $FA3 F19 ; Floating-point argument 3
      .DEFINE_FREG $FA4 F20 ; Floating-point argument 4
      .DEFINE_FREG $FA5 F21 ; Floating-point argument 5
      .DEFINE_IREG $AI R25 ; Argument-information register
      .DEFINE_IREG $RA R26 ; Return-address register
      .DEFINE_IREG $PV R27 ; Procedure-value register
      .DEFINE_IREG $FP R29 ; Frame pointer
      .DEFINE_IREG $SP R30 ; Stack pointer

                                  NOTE

      SP and FP remain predefined by MACRO-64 whether or not
      you use the OpenVMS Calling Standard macros. $SP and
      $FP are defined by the OpenVMS Calling Standard macros
      for consistency with the other register definitions that
      correspond to OpenVMS Calling Standard register conventions.

   The following symbols are defined by the $ROUTINE macro. These
   symbols are useful while programming with the calling-standard
   macros to refer to particular data and linkage section items.

   o  $CS-The address of the beginning of the current routine's code
      section.

   o  $LS-The address of the beginning of the current routine's
      linkage section.

   o  $DS-The address of the beginning of the current routine's data
      section.

   o  $DP-The linkage section address where the $ROUTINE macro
      places the .ADDRESS $DS to enable access to the data section
      from the linkage section (this variable is optional).

   o  $SIZE-The size of the fixed-stack area in bytes. $SIZE is
      defined using the value specified with the SIZE argument.

   o  $RSA_OFFSET-The offset within the fixed-stack area to the
      register save area. $RSA_OFFSET is defined using the value
      specified with the RSA_OFFSET argument.

   o  $RSA_END-The offset within the fixed-stack area to the first
      byte beyond the end of the register save area.

   For more information, see the description for the $ROUTINE macro
   in this chapter.

   The $CALL macro also defines the $STACK_ARG_SIZE symbol. This
   symbol specifies the number of bytes used to store arguments
   on the stack. This value is useful after calling a routine that
   returns a value on the stack. In this case, $CALL cannot remove
   the arguments from the stack because you must first retrieve the
   returned value from the stack. Subsequently, you can remove the
   arguments from the stack using the $STACK_ARG_SIZE symbol. For
   more information, see the description of $CALL in this chapter.
 

5  Defining_Procedure_Type
   The OpenVMS Calling Standard defines four types of routines;
   stack, register, null, and bound.

   You can define the routine type by using the KIND keyword
   argument with $ROUTINE or $PROCEDURE_DESCRIPTOR macros. The
   validity and values of other $ROUTINE and $PROCEDURE_DESCRIPTOR
   macro parameters are determined by the type of routine being
   declared. For example, a null procedure type has no stack size;
   therefore, the SIZE parameter is invalid and cannot be specified
   for a null procedure type. When using the KIND keyword with the
   $ROUTINE or $PROCEDURE_DESCRIPTOR macros, note the following
   exceptions:

   o  The $SIZE symbol defined by $ROUTINE is only valid for stack
      and register routines.

   o  The $RSA_OFFSET symbol defined by $ROUTINE is only valid for a
      stack routine.
 

5  Using_Macros_in_Prologue_Sections
   With stack and register routines, $ROUTINE generates a standard
   prologue sequence if you specify the STANDARD_PROLOGUE=TRUE
   keyword argument. STANDARD_PROLOGUE=TRUE is the default for
   register and stack routines.

   Alternatively, you can code your own prologue sequence by
   specifying the STANDARD_PROLOGUE argument as FALSE and using the
   $END_PROLOGUE macro to mark the end of your prologue sequence. In
   this case, you may wish to use the $SIZE and $RSA_OFFSET symbols
   to symbolically specify the fixed-stack size and register save
   area offset, respectively.

   For more information on the prologue sequence of instructions
   that must occur at the beginning of all stack and register
   routines, see the OpenVMS Calling Standard.
 

5  Using_Macros_in_Epilogue_Sections
   With stack and register routines, you can use the $RETURN
   macro to generate an epilogue sequence. Alternatively, you
   can code your own epilogue sequence using the $BEGIN_EPILOGUE
   and $END_EPILOGUE macros to mark the beginning and end of your
   epilogue sequences.

   The OpenVMS Calling Standard also describes the epilogue sequence
   of instructions that must be executed every time a stack or
   register routine returns to its caller.
 

4  Programming_Examples_Using_Supplied_Macros
   Examples Program Using Supplied Macros and Program Using $CALL
   show how to use the calling-standard macros to define a routine,
   switch control between psects, generate an epilogue sequence, and
   end the routine.

   Example 3  Program Using Supplied Macros

           $ROUTINE MAIN, KIND=STACK, - ; Stack routine kind 1
               SAVED_REGS=<FP>, - ; Saves FP           2
               SIZE=48               ; Stack size is 48   3

           $LINKAGE_SECTION          ; Switch to the linkage psect. 4

   X:      .long 6                   ; X is a constant
   FP1_ADDR:                         ; FP1_ADDR -> FP1
           .address FP1

           $DATA_SECTION             ; Switch to the data section 5

   A::     .blkw 5                   ; $DS points here
   B::     .blkw

           $CODE_SECTION             ; Switch to the code section 6
                                     ; ($CS points here)
                  .
                  .
                  .
           $RETURN                   ; Perform epilogue and return 7

           $END_ROUTINE MAIN         ; Mark the end of the routine 8

   1  $ROUTINE defines the routine MAIN. The routine type is defined
      as a stack routine using the KIND=STACK keyword argument.

   2  The keyword argument SAVED_REGS=<FP> adds the frame pointer
      register to the list of registers saved on the stack by the
      prologue code. The SAVED_REGS keyword is valid only for stack
      procedures. If you do not specify the FP register (R29) with
      this argument, it is assumed.

   3  The keyword argument SIZE=48 defines the stack area in bytes.
      This argument is valid only for register and stack routines.
      If you do not specify a stack size for a stack or register
      routine, $ROUTINE computes the minimum stack size required to
      accommodate the other arguments you specify or leave as the
      default.

   4  The $LINKAGE_SECTION macro switches to the linkage section.
      You can use the $LS symbol created by the $ROUTINE macro
      to point to the address of the current routine's linkage
      section. $ROUTINE creates the procedure descriptor and leaves
      the current location counter within the linkage section just
      beyond the procedure descriptor.

   5  The $DATA_SECTION macro switches to the data section. You can
      use the $DS symbol created by the $ROUTINE macro to point to
      the address of the current routine's data section.

   6  The $CODE_SECTION macro switches to the code section. The $CS
      symbol created by the $ROUTINE macro is used to point to the
      address of the current routine's code section.

   7  The $RETURN macro generates a standard epilogue instruction
      sequence. You can use this macro only with stack or register
      routine defined with the $ROUTINE macro.

   8  The $END_ROUTINE macro marks the end of the routine.
 

4  Using_the_$CALL_Macro
   $CALL calls local or external routines previously defined by the
   $ROUTINE macro or defined in another language.

   To call a routine using standard linkage, use the $CALL macro.
   You invoke this macro from within the routine's code section.
   $CALL performs the following actions:

   o  Searches a list of linkage pairs referenced in previous
      invocations of the $CALL and $LINKAGE_PAIR macros within
      the calling routine. If a linkage pair is already found to
      exist on the list, $CALL uses the linkage pair stored from the
      previous invocation. Otherwise, $CALL stores the linkage pair
      of the called routine in the caller's linkage section and adds
      the linkage pair to the caller's list.

   o  Allocates stack space for arguments, if necessary.

   o  Loads arguments specified with the ARGS argument into argument
      registers and onto the stack, as appropriate.

   o  Sets the arguments information register, R25, according to the
      arguments specified with ARGS argument.

   o  Generates the following instruction sequence to perform
      the actual call based on the location of the linkage pair
      generated from above, and the value of Rls, linkage register,
      which is assumed to point to the base of the linkage section:

            LDQ R26, code_addr_offset(Rls)      ; load code address
            LDQ R27, proc_desc_addr_offset(Rls) ; load procedure
                                                ; descriptor address
                                                ;
            JSR R26, R26                        ; Jump to the routine
                                                ;  saving the return
                                                ;  address in R26

   o  Frees argument stack space, if any, and if the called routine
      does not return a value on the stack.

      Like $ROUTINE, the $CALL macro invokes other macros to perform
      the previous tasks.

      If you do not specify the Rls argument in your invocation of
      $CALL, $CALL assumes that you have used the .BASE directive
      to define a register that points to the base address of your
      linkage section. That is, it assumes that you have included a
      statement similar to the following:

      .BASE R27, $LS

      This source statement defines the base address of the linkage
      section to be R27, and to be associated with the macro symbol
      $LS. This source statement should be placed in your source
      code before the $CALL macro call.
 

5  Using_$CALL_in_Source_Code
   This example uses the same source code from the previous example,
   except it uses the $CALL macro to show how to call a local and
   external routine.

   Example 4  Program Using $CALL

               .
               .
               .
           $CODE_SECTION             ; Switch to the code section
                                     ; ($CS points here)
               .
               .
               .
           MOV     R27,R2    1
           .base   R2, $LS   2
               .
               .
               .
           $CALL SUB1                ; Call external routine SUB1  3
           $CALL SUB2, LOCAL=TRUE    ; Call local routine SUB2     4
               .
               .
               .
           $RETURN                   ; Perform epilogue and return
           $END_ROUTINE MAIN         ; Mark the end of the routine

   1  The $LS symbol is defined to be the address of the procedure
      that is defined within the linkage section. The calling
      routine places the address of the procedure descriptor in
      R27 before making the call. This guarantees that the address
      associated with the symbol $LS is stored in R27 upon routine
      entry. Since the information in R27 is erased during a
      standard call, a copy is preserved in register R2.

   2  Register R2 now contains the address of our procedure
      descriptor, which is the base address of our linkage section.
      Since $LS is defined to point to the base address of the
      linkage section, the assembler computes the offsets within
      the linkage section using the .BASE directive.

   3  The $CALL macro calls the external routine SUB1.

   4  The $CALL macro calls the local routine SUB2. This call uses
      the LOCAL=TRUE keyword argument to indicate that routine SUB2
      is defined within the module.
 

4  Programming_Considerations
   This section discusses some programming considerations you need
   to be aware of when using the calling-standard macros.
 

5  Making_Multiple_Calls_From_the_Same_Routine
   The $CALL macro generates the following instruction sequence:

    LDQ R26, code_address_offset(Rls)              ; load code address
    LDQ R27, procedure_descriptor_address_offset(Rls) ; load procedure
                                                      ;    descriptor
                                                      ;    address
    JSR R26, R26                                      ;

   The contents of R26 and R27 are erased as a result of using the
   $CALL macro. This is important since Rls in the previous sequence
   is typically R27. Thus, if you require subsequent access to your
   linkage section, such as when making subsequent calls, you need
   to make a working copy of R27 to use after the first call.

   Note that $CALL also overwrites the values in the argument
   registers, and the scratch registers specified or the default
   set by the SCRATCH_REGS argument, when you pass arguments to the
   called routine.
 

5  Nonstandard_Linkage
   Under certain circumstances, there may be advantages in using a
   nonstandard routine linkage.
 

5  Routine_Restrictions
   Different routine types have different capabilities and
   restrictions. For example, only a stack routine that specifies
   BASE_REG_IS_FP=TRUE can make standard calls.
 

5  Syntax_Rules

   You can use either positional or keyword argument association
   or a combination of the two with these macros. For positional
   association, the order of formal arguments is shown with
   the format of each macro. The following syntax rules apply
   when invoking the assembler using the command-line qualifier
   /NAMES=AS_IS:

   o  When specifying macro names, you must use all uppercase or all
      lowercase characters. You cannot mix uppercase and lowercase
      characters.

   o  When specifying keyword arguments, you must use the same
      alphabetic case as the macro name it is associated with. If
      you use lowercase characters with the macro name, you must
      use lowercase characters with the keyword argument. If you
      use uppercase characters with the macro name, you must use
      uppercase characters with the keyword argument.
 

4  $BEGIN_EPILOGUE
   Marks the beginning of an epilogue instruction sequence.

   Format

     $BEGIN_EPILOGUE
 

5  Description
   $BEGIN_EPILOGUE marks the beginning of an epilogue instruction
   sequence that you code within a stack or register routine defined
   with the $ROUTINE macro.

   At each point where a stack or register routine returns to
   its caller, the routine must perform a sequence of operations
   to restore any saved registers and to perform stack frame
   management. This sequence is called the epilogue and is described
   in detail in the OpenVMS Calling Standard.

   You can use the $RETURN macro to generate a standard epilogue
   instruction sequence for you, or you can code your own sequence.
   If you code your own epilogue sequence, you must mark the
   beginning and end of the epilogue sequence with the $BEGIN_
   EPILOGUE and $END_EPILOGUE macros.
 

5  Notes

   o  You must not use $BEGIN_EPILOGUE for an epilogue instruction
      sequence generated by $RETURN. $RETURN automatically invokes
      $BEGIN_EPILOGUE and $END_EPILOGUE.
 

5  Example

               $ROUTINE MUMBLE, KIND=REGISTER, SAVE_FP=R1
                   :
                   :
                   :
               $BEGIN_EPILOGUE
               MOV     R1,FP               ; Restore caller's frame
               RET     (R26)               ; Return to caller
               $END_EPILOGUE
                   :
                   :
                   :
               $END_ROUTINE MUMBLE
 

4  $CALL
   Issues a call to another routine.

   Format

     $CALL  NAME=routine-being-called -

            [Rls=linkage-section-register] -

            [LS=linkage-section-address] -

            [LOCAL=boolean] -

            [ARGS=argument-list] -

            [SET_ARG_INFO=boolean-value] -

            [STACK_RETURN_VALUE=boolean-value] -

            [SCRATCH_REGS=scratch_reg-list] -

            [TIE=boolean-value] -

            [FUNC_RETURN=

            {I64,D64,I32,U32,FF,FD,FG,FS,FT,FDC,FGC,FSC,FTC}]

            -

            [USES_VAX_ARGLIST=boolean-value] -

            [SIGNATURE_BLOCK=signature_address] -

            [NONSTANDARD=boolean-value] -
 

5  Parameters
 

NAME

   The name of the routine to call. This argument is required.
 

Rls

   Linkage section register to use when generating the LDQ, LDQ, JSR
   instruction sequence. This argument is optional.

   If Rls is omitted, $CALL assumes that you entered a .BASE
   directive before invoking $CALL that establishes the value of a
   base register pointing into the linkage section. If you omit the
   Rls argument and you do not enter such a .BASE directive before
   invoking $CALL, the assembler issues the following error message
   during the $CALL macro expansion:

       "Argument 2 invalid"  The assembler failed to find a
        base register specified with a previous .BASE directive
        to form a register expression of the form offset(Rn)"
 

LS

   LS is the address of the linkage section. If you use $CALL within
   a routine defined by the $ROUTINE macro, the LS argument defaults
   to the $LS symbol defined by $ROUTINE. If you use $CALL outside
   of a routine defined by the $ROUTINE macro, there are two ways
   that you can indicate the location of the linkage section to
   $CALL. First, you can specify the LS argument to $CALL as a
   relocatable address expression that indicates the base of the
   linkage section. In this case you must also specify the Rls
   argument. Second, you can specify both the linkage-section base
   register and the linkage-section address in a .BASE directive
   before invoking $CALL. In this case, you must omit both the Rls
   and LS arguments to $CALL.

   Digital recommends that you omit this argument if you use $CALL
   within a routine defined by the $ROUTINE macro.
 

LOCAL

   A Boolean value (TRUE or FALSE) that specifies whether the
   routine to be called is local to the module or globally visible.
   By default, $CALL generates a call to a globally visible routine.
   To generate a call to a routine that is not globally visible, you
   must specify LOCAL=TRUE.
 

ARGS

   An optional list of arguments to pass to the called routine.
   Enclose the argument list within angle brackets (<>)  and
   separate the arguments with commas (,).  You can use the
   following qualifiers with each argument you specify with the
   ARGS argument. These qualifiers are described in the following
   table.

   Each argument is an address expression (which may include a
   register) followed by a qualifier. The table also contains
   the argument type, the instruction used to load the argument
   into a register, the instruction used to store the argument on
   the stack, and the encodings used in the Argument Information
   Register (R25) in the call signature block when you specify
   TIE=TRUE. See the OpenVMS Calling Standard for more information
   on these encodings. Note that arguments are only stored on
   the stack if there are more than six arguments provided to the
   routine.

                                   ARGS Arguments
_________________________________________________________________________
Argument
          Argument   LOAD        STORE       AI       Reg Arg   Mem Arg
Qualifier Type       Instruction Instruction Encoding Signature Signature
_________________________________________________________________________
/A        Address    LDA         STQ         I64      I32       I32
/D        D-floating LDG         STG         FD       FD        Q
/F        F-floating LDF         STF         FF       FF        I32
/G        G-floating LDG         STG         FG       FG        Q
/L        Longword   LDL         STQ         I64      I32       I32
/Q        Quadword   LDQ         STQ         I64      Q         Q
/S        S-floating LDS         STS         FS       FS        I32
/T        T-floating LDT         STT         FT       FT        Q
/UL(1)    Unsigned   LDL         STQ         I64      U32       I32
          Longword   /ZAP
                     #^xF0
_______________________________________________________________________
(1)--Unsigned 32-bit integers are normally passed using the /L argument
qualifier. Therefore, Digital does not recommend that you use the /UL
argument qualifier.
_______________________________________________________________________
 

SET_ARG_INFO

   An optional argument to indicate whether $CALL should
   set the Argument Information (AI) register (R25) with
   the appropriate argument information or not. By default,
   or if you specify SET_ARG_INFO=TRUE, $CALL stores the
   appropriate argument information in R25. If you specify
   SET_ARG_INFO=FALSE, $CALL does not affect R25.

   If you want to conform to the OpenVMS Calling Standard, you
   must store the appropriate information in R25 yourself before
   invoking $CALL. If you do not need to conform to the OpenVMS
   Calling Standard, and if the called routine does not need
   argument information in R25, you can specify SET_ARG_INFO=FALSE
   and make no change in R25. By making no change in R25, you
   avoid the overhead involved when either you or $CALL load
   argument information into R25 at the expense of calling standard
   conformance.
 

STACK_RETURN_VALUE

   An optional argument to indicate that the called routine returns
   a value on the stack. By default, $CALL assumes that the called
   routine does not return a value on the stack. In this case, $CALL
   removes any arguments passed to the called routine from the stack
   when the called routine returns.

   If the called routine returns a value on the stack, the returned
   value is placed at a lower address than the arguments on the
   stack. In this case, you must specify STACK_RETURN_VALUE=TRUE
   to prevent $CALL from removing the arguments to the called
   routine from the stack and erasing the value returned by the
   called routine. You must retrieve the return value and remove it
   from the stack. Then you can remove the arguments to the called
   routine using the $STACK_ARG_SIZE symbol defined by $CALL.
 

SCRATCH_REGS

   An optional list of scratch registers for $CALL to use when
   processing arguments passed to the called routine with the ARGS
   argument. If you pass more than six arguments to the called
   routine, $CALL may need to use scratch registers to process the
   call.

   By default, $CALL uses R0, R1, F0, and F1. You can cause $CALL to
   use different scratch registers with the SCRATCH_REGS argument.

   If you are passing integer arguments, you should specify at
   least one integer register. If you are passing floating-point
   arguments, you should specify at least one floating-point
   register.

   $CALL can process arguments to the called routine more
   efficiently if you specify two or more scratch registers of the
   type or types appropriate to the arguments you are passsing.
 

TIE

   A Boolean value (TRUE or FALSE) that specifies whether $CALL
   should generate a call sequence that is compatible with both
   native routines and the Translated Image Environment (TIE). By
   default, $CALL generates a faster call sequence that is only
   compatible with native routines. If you specify TIE=TRUE, $CALL
   generates a call sequence that works with both native routines
   and translated routines. If you are calling a VAX routine in a
   shareable image that has been translated with the DECmigrate
   image translator, specify TIE=TRUE. If you are calling a native
   routine, Digital recommends you default the TIE argument or
   specify TIE=FALSE. While $CALL generates a call sequence that
   is compatible with native routines when you specify TIE=TRUE,
   that call sequence is slower than when you specify or default
   TIE=FALSE.
 

FUNC_RETURN

   An optional argument used to indicate the type of function return
   when you also specify TIE=TRUE. This argument is ignored unless
   you also specify TIE=TRUE. Specify one of I64, D64, I32, U32,
   FF, FD, FG, FS, FT, FFC, FDC, FGC, FSC, or FTC. These values
   correspond to the RASE$K_FR_* signature encodings described
   in Table 3-7 in the OpenVMS Calling Standard. If you specify
   TIE=TRUE and do not specify a function return type with FUNC_
   RETURN, the default function return type is I64.
 

                                  NOTE

      Specification of the FUNC_RETURN argument does not in itself
      cause $ROUTINE to generate a procedure signature block.
      However, if you specify either or both the ARGLIST or USES_
      VAX_ARGLIST arguments, any value you specify with the FUNC_
      RETURN argument is recorded in both the procedure descriptor
      and the procedure signature block.
 

USES_VAX_ARGLIST

   An optional argument to indicate whether the called routine uses
   a VAX argument list. This argument is ignored unless you also
   specify TIE=TRUE. By default, $CALL assumes the called routine
   does not use a VAX argument list. Specify USES_VAX_ARGLIST=TRUE
   to indicate that the called routine uses a VAX argument list.
 

SIGNATURE_BLOCK

   An optional argument that you can use to supply the address of
   the call signature block. This argument is ignored unless you
   also specify TIE=TRUE. Note that you cannot specify a SIGNATURE_
   BLOCK argument in combination with either of the FUNC_RETURN
   or USES_VAX_ARGLIST arguments. By default, $CALL generates a
   call signature block for you when you specify TIE=TRUE, and you
   can in part control the contents of that signature block with
   the FUNC_RETURN and USES_VAX_ARGLIST arguments. If you wish to
   define your own call signature block, do not specify either of
   the FUNC_RETURN or USES_VAX_ARGLIST arguments and supply the
   address of your call signature block with the SIGNATURE_BLOCK
   argument.
 

NONSTANDARD

   A Boolean value (TRUE or FALSE) that specifies whether $CALL
   should suppress warning and informational messages concerning
   nonstandard usage. By default, $CALL issues warning and
   informational messages to indicate you are using $CALL in a
   way that violates the OpenVMS Calling Standard or in a way
   that requires special programming considerations. Specify
   NONSTANDARD=TRUE if you wish to suppress these messages.
 

5  Description
   $CALL issues a call to another routine and performs the following
   actions:

   1. Searches a list of linkage pairs referenced in previous
      invocations of the $CALL and $LINKAGE_PAIR macros. If a
      linkage pair is already in the list, $CALL uses the linkage
      pair from the previous invocation. Otherwise, $CALL stores
      the linkage pair of the called routine in the caller's linkage
      section and adds the linkage pair to the caller's list. If you
      use $CALL within a routine defined with the $ROUTINE macro,
      $CALL and $LINKAGE_PAIR reset the list of linkage pairs for
      each routine.

   2. Allocates stack space for arguments if necessary.

   3. Generates instructions to load the arguments to the called
      routine.

   4. Sets the value in the argument information register, R25.

   5. Generates the following instruction sequence to perform
      the actual call based on the location of the linkage pair
      generated from step 1 and the address specified or defaulted
      with the LS argument. The register specified with the Rls
      argument is assumed to point to the base of the linkage
      section as shown in the following example:

      LDQ R26, code_address_offset(Rls)         ; load code address
      LDQ R27, procedure_descriptor_address_offset(Rls) ; load
                                                        ;  procedure
                                                        ;  descriptor
                                                        ;  address
          JSR R26, R26

   6. Frees argument stack space, if any, and if the called routine
      does not return a value on the stack.
 

5  Examples
     Example 1
           $CALL SUB1, Rls=R13, LS=MY_LINKAGE_SECTION
           .BASE R13, MY_LINKAGE_SECTION
           $CALL SUB2

           $ROUTINE SUB3, KIND=STACK, SAVED_REGS=<R2,FP>
           $LINKAGE_SECTION
           .QUAD 1
       XX:
           $CODE_SECTION
           MOV R27, R2
           $CALL SUB4, R2
           .BASE R2, $LS
           $CALL SUB5
           $CALL SUB6, -
              ARGS=<XX/A, R0/Q>, -
              SCRATCH_REGS=<R22,R23>
           $CALL SUB7, -
              ARGS=<1/A,2/A,3/A>
           $RETURN
           $END_ROUTINE SUB3
     Example 2
       $CALL FOO, ARGS=<A,B,C,D,E,F,G,H>, STACK_RETURN_VALUE=TRUE
                               ; Fetch octaword return value from stack
       LDQ R4, 0(SP)           ; low quadword
       LDQ R5, 8(SP)           ; high quadword
       LDA SP, $STACK_ARG_SIZE+16(SP)  ; RESET STACK
 

4  $CODE_SECTION
   Switches control to the current routine's code section psect.

   Format

     $CODE_SECTION
 

5  Description
   $CODE_SECTION switches control to the current routine's code
   section psect.
 

5  Example

         $CODE_SECTION
 

4  $DATA_SECTION
   Switches control to the current routine's data section psect.

   Format

     $DATA_SECTION
 

5  Description
   $DATA_SECTION switches control to the current routine's data
   section psect.
 

5  Example

       $DATA_SECTION
 

4  $END_EPILOGUE
   Marks the end of an epilogue instruction sequence.

   Format

     $END_EPILOGUE
 

5  Description
   You can use the $END_EPILOGUE macro to mark the end of an
   epilogue instruction sequence that you code yourself within
   a stack or register routine defined with the $ROUTINE macro.
   At each point where a STACK or REGISTER routine returns to
   its caller, the routine must perform a sequence of operations
   to restore any saved registers and to perform stack-frame
   management. This sequence is called the epilogue and is described
   in detail in the OpenVMS Calling Standard.

   You can use the $RETURN macro to generate a standard epilogue
   instruction sequence for you. Alternatively, you can code your
   own sequence. If you code your own epilogue sequence, you must
   mark the beginning and end of the epilogue sequence with the
   $BEGIN_EPILOGUE and $END_EPILOGUE macros, respectively.

   Note that you must not use $END_EPILOGUE for an epilogue
   instruction sequence generated by $RETURN. $RETURN invokes
   $BEGIN_EPILOGUE and $END_EPILOGUE for you.

   You may omit the invocation of $END_EPILOGUE if your epilogue
   sequence occurs at the end of the routine. The $END_ROUTINE macro
   invokes $END_EPILOGUE for you if you invoke the $BEGIN_EPILOGUE
   macro without a matching invocation of the $END_EPILOGUE macro.
   You must invoke $END_EPILOGUE with epilogue sequences that occur
   in the middle of your routine.
 

5  Example

               $ROUTINE MUMBLE, KIND=REGISTER, SAVE_FP=R1
                   :
                   :
                   :
               $BEGIN_EPILOGUE
               MOV     R1,FP               ; Restore caller's frame
               RET     (R26)               ; Return to caller
               $END_EPILOGUE
                   :
                   :
                   :
               $END_ROUTINE MUMBLE
 

4  $END_PROLOGUE
   Marks the end of a prologue instruction sequence.

   Format

     $END_PROLOGUE
 

5  Description
   $END_PROLOGUE marks the end of a routine prologue instruction
   sequence that you code yourself. The prologue instruction
   sequence begins with the first instruction of the routine. There
   can only be one prologue instruction sequence in a routine. The
   prologue is described in detail in the OpenVMS Calling Standard.

   You invoke $END_PROLOGUE after the last instruction in the
   routine prologue code. The last instruction in the routine
   prologue is the one that updates FP (R29, the frame pointer)
   and makes the frame become current. You must use this macro
   when the routine type is stack or register and you specify
   STANDARD_PROLOGUE=FALSE to the $ROUTINE macro.
 

5  Notes

   o  Do not use this macro when the $ROUTINE macro generates a
      standard prologue or when the routine type is null or bound.
      For example, a standard prologue is generated for you when you
      specify or leave the default of $ROUTINE's STANDARD_PROLOGUE
      argument to TRUE.
 

5  Example

               MOV     SP, FP
               $END_PROLOGUE
 

4  $END_ROUTINE
   Marks the end of a routine.

   Format

     $END_ROUTINE  [name=routine-name]
 

5  Parameter
 

name

   The name of the routine that is ended. This argument is optional.
   If you specify a name, $END_ROUTINE verifies that the name
   matches that which was specified with $ROUTINE to begin the
   routine. If the name does not match, $END_ROUTINE issues a
   diagnostic message. There is no default. If you omit the name,
   $END_ROUTINE does not verify a matching name.
 

5  Description
   You must use this macro at the end of a routine that is defined
   with the $ROUTINE macro to delimit the end the current routine
   and to perform final macro processing of the routine.
 

5  Example

           $END_ROUTINE NAME=FOOZLE
 

4  $LINKAGE_PAIR
   Locates or defines a linkage pair in the linkage psect.

   Format

     $LINKAGE_PAIR  name=routine-name, local=boolean
 

5  Parameters
 

name

   Name of the linkage pair to define. This argument is required.
 

local

   A Boolean value (TRUE or FALSE) that specifies whether the
   routine is defined within the module for not. The default is
   to store a linkage pair for a global routine. You must specify
   LOCAL=TRUE to store a linkage pair for a routine that is not
   globally visible.
 

5  Description
   You can invoke this macro to locate or define a linkage pair
   in the linkage psect. The linkage pair is added to a list for
   later use and retrieval by the $CALL and $LINKAGE_PAIR macros.
   Thus, only the first invocation of $LINKAGE_PAIR (or $CALL) for
   a given routine to be called results in a linkage pair being
   stored. $LINKAGE_PAIR and $CALL use the same list of linkage
   pairs. $LINKAGE_PAIR restores the current psect when it is done.

   $LINKAGE_PAIR defines the symbol $LP. This symbol value is the
   address within the linkage section of the linkage pair for the
   specified routine to call.
 

5  Notes

   o  Because the $CALL macro invokes the $LINKAGE_PAIR macro
      for you, you do not need to use $LINKAGE_PAIR when you are
      using $CALL. You may wish to use $LINKAGE_PAIR when you are
      not using $CALL or when you require a specific ordering or
      placement of linkage pairs within the linkage section.
 

5  Example

   $LINKAGE_PAIR SUB1  ; define linkage pair in linkage section
   LDQ R26, $LP
   LDQ R27, $LP+8
   JSR R26, R26
 

4  $LINKAGE_SECTION
   $LINKAGE_SECTION switches control to the current routine's
   linkage section psect.

   Format

     $LINKAGE_SECTION
 

5  Description
   $LINKAGE_SECTION switches control to the current routine's
   linkage section psect.
 

5  Example

       $LINKAGE_SECTION
 

4  $OPDEF
   Used to define opcodes.

   Format

     $OPDEF  MNEMONIC, FORMAT, ENCODING [,DEFAULTS]
 

5  Parameters
 

MNEMONIC

   MNEMONIC is the mnemonic name by which the instruction is called.
   You may optionally specify a qualifier list separated from the
   name by a slash (/).  A qualifier list is a sequence of one or
   more letters or digits with no intervening spaces or separators.
 

FORMAT

   FORMAT is one of the following arguments:

   Format                      Description

   MEMORY                      Standard memory format instructions.
   MEMORY_FUNCTION             Memory format instructions with a
                               function code.
   JUMP                        Memory format instructions formatted
                               like jump instructions.
   BRANCH                      Standard branch format instructions.
   OPERATE                     Standard operate instructions.
   FLOATING_OPERATE            Standard floating-point operate
                               instructions.
   PAL                         Standard PALcode instructions.
   <CUSTOM=operand_type_list>  Custom format.

   With the CUSTOM format, you may optionally specify a list of the
   types of operands the instruction is to accept. If you specify
   a list of operand types, you must enclose the entire FORMAT
   argument within angle brackets, and you must specify the operand
   types in the order they are to be used with the instruction.
   $OPDEF supports the following operand types:

   IREGISTER      Integer register, such as R5 or SP.
   FREGISTER      Floating-point register, such as F7.
   LITERAL        Integer literal, such as #123 or 32767.
   LIT_IREG       Integer literal, such as #123 or 32767, or integer
                  register, such as R5 or SP.
   INDIRECT       Indirect integer register notation such as (R7).
   DISPLACEMENT   Indirect integer register notation with an integer
                  literal displacement, such as FOO(R12).
   BRANCH_OFFSET  Label or address expression, such as L1.

   For example:

   FORMAT=<CUSTOM=IREGISTER,DISPLACEMENT>

   The following example shows the definition of the ADDQ
   instruction, which takes either an integer register or literal
   as its second argument:

       $OPDEF ADDQ,                                      -
           FORMAT=<CUSTOM=IREGISTER,LIT_IREG,IREGISTER>, -
           ENCODING=<26:31=^x10,                         -
               21:25=%OP1,                               -
               12:20=%OP2,                               -
               5:11=^x20,                                -
               0:4=%OP3>

   For a detailed description of instruction formats, see the Alpha
   Architecture Reference Manual.
 

ENCODING

   ENCODING is the numeric encoding for the instruction opcode.
   The default radix is decimal, as is the case for all assembler
   constants. Prefix the value with ^X for hexadecimal. Certain
   instruction formats allow multipart encoding:

   Format             Encoding Description

   MEMORY_FUNCTION    Specify the base opcode, followed by a dot,
                      followed by the function code. For example:

                      ENCODING=^X10.F000
   JUMP               Specify the base opcode, optionally followed
                      by a dot, and the hardware-hint bits
                      optionally followed by a dot and the software-
                      hint bits. For example:

                      ENCODING=^X1A.2.1
   OPERATE            Specify the base opcode, followed by a dot,
                      followed by the function code. For example:

                      ENCODING=^X12.3C
   FLOATING_OPERATE   Specify the base opcode, followed by a dot and
                      the function code. For example:

                      ENCODING=^X17.02B
   PAL                Specify the base opcode, optionally followed
                      by a dot and the function code. Omit the
                      function code for a generic PAL instruction
                      that accepts an integer-expression argument.
                      For example:

                      ENCODING=^X0.0080
                      ENCODING=^X19
   CUSTOM             Specify a comma-separated list of bit ranges
                      and values to place in those bit ranges. For
                      example:

                      ENCODING = < 26:31=^X14, 21:25=%OP1, -
                                   16:20=%OP2.REG, 0:15=%OP2.DISP >

   For CUSTOM format instructions, specify the ENCODING argument as
   a comma-separated list of bit ranges and values to place in those
   bit ranges. Enclose the list within angle brackets.

   Specify a bit range as start:end where start and end are integer
   constant expressions. For a 1-bit bit range, start and end are
   equal. Bit positions range from 0 to 31. Place an equal sign (=)
   after the bit-range specifier followed by the value you wish to
   put in the bit range. You can place either a constant integer
   expression or an operand into the bit range. Start and end
   expressions and integer constant expressions must not reference
   any external symbols or symbols not yet defined in the assembly.
   $OPDEF evaluates these expressions at the time that it defines
   the instruction as opposed to when the defined instruction is
   referenced.

   Operand names are of the form %OPn, where n is the ordinal number
   of the operand as specified from left to right with the FORMAT
   argument.

   For the IREGISTER, FREGISTER, and INDIRECT operands, $OPDEF
   places the 5-bit register number into the bit positions you
   specify.

   For LITERAL operands, $OPDEF places the literal value of the
   operand into the bit positions you specify. Operand literal
   values can be up to 32 bits long. The most significant bits
   are truncated if the size of the operand literal value exceeds
   the bit range you specify. Forward and external references are
   allowed.

   For LIT_IREG operands, $OPDEF places either a literal value or
   a 5-bit register number into the bit positions you specify. If a
   literal, the low bit is 1, and the literal value is placed in the
   upper bits. If an integer register, the low four bits are 0, and
   the high five bits contain the register number.

   For DISPLACEMENT operands, $OPDEF defines two parts: a 5-bit
   register number and a displacement value that can be up to 32
   bits long. The most significant bits are truncated from the
   displacement value if the size of the displacement value exceeds
   the bit range you specify. You can reference the register number
   by placing .REG after the operand name. For example: %OP2.REG.
   Similarly, you can reference the displacement value by placing
   .DISP after the operand name. For example: %OP2.DISP. Forward
   references are allowed. Relocatable expressions are not allowed.

   For BRANCH_OFFSET operands, $OPDEF stores the signed longword
   offset between the next instruction and the specified address in
   the bit positions you specify. The address expression specified
   for a BRANCH_OFFSET operand can be a backward or forward
   reference to a location within the current psect. It cannot
   be an external address or an address in a different psect. The
   resulting offset can be up to 32 bits in size. If the size of the
   offset exceeds the bit range you specify, the most significant
   bits are truncated.

   $OPDEF fills any bit positions you leave unspecified with zeros.
 

DEFAULTS

   DEFAULTS is an optional list of operand defaults of the form
   <%OPn=value, ...>, where n is the number of the operand to which
   the value is to apply as a default. Operand defaults may be
   specified in any order. If you specify a default for one or more
   operands, you need not specify a default for all operands.

   The following example specifies a default of R31 for the first
   instruction argument:

       $OPDEF RET, FORMAT=<CUSTOM=IREGISTER,INDIRECT>,   -
           ENCODING=<26:31=^x1A,                         -
               21:25=%OP1,                               -
               16:20:%OP2,                               -
               14;14=^x2,0:13=0>,                        -
           DEFAULTS=<%OP1=R31>
 

5  Description
   You can use the $OPDEF macro to define your own opcodes.

   $OPDEF defines a macro using an unqualified version of the
   mnemonic name you specify. When this macro is invoked with the
   instruction qualifiers you specify when you define it with $OPDEF
   (if any), it expands to the instruction representation you have
   defined with $OPDEF. You can specify the qualifiers in any order
   as long as the combination of qualifiers you use is the same.

   Other uses of the mnemonic name remain valid provided you do not
   use the mnemonic name as a macro name in a .MACRO directive. For
   instance, you can use the same mnemonic name in the opcode field
   with different or no qualifiers. If the qualifiers (or absence
   thereof) do not match those specified in your $OPDEF instruction
   definition, the macro defined by $OPDEF processes as though you
   had not defined an instruction by that mnemonic name. To do
   so, it expands to a single statement. This expansion statement
   is identical to the mnemonic-name macro invocation statement,
   except it is processed in a context that prevents the mnemonic-
   name macro from expanding recursively. Instead, the statement
   is processed as a normal, MACRO-64 instruction statement. In
   this case, you may notice references to the mnemonic-name macro
   expansion in a MACAUXMSG diagnostic message if the instruction
   statement contains errors.

   For instance, if you define a STQ/P instruction using $OPDEF,
   you can still use the STQ instruction without the /P qualifier.
   If you do, and your STQ instruction statement contains an error,
   the assembler generates a MACAUXMSG message indicating that the
   error occurred during the expansion of macro STQ. Aside from
   the fact that the STQ instruction is processed in the context of
   the expansion of the STQ macro, $OPDEF's definition of the STQ/P
   instruction has no effect on your use of the STQ instruction.
 

5  Example

       $OPDEF MNEMONIC=BANG, FORMAT=PAL, -
              ENCODING=^X0.0099
 

4  .PACKED
   Packed decimal string storage macro.

   Format

     .PACKED  decimal-string[,symbol]
 

5  Parameters
 

decimal-string

   A decimal number from 0 to 31 digits long with an optional sign.
   Digits can be in the range 0 to 9.
 

symbol

   An optional symbol that is assigned a value equivalent to the
   number of decimal digits in the string. The sign is not counted
   as a digit.
 

5  Description
   .PACKED generates packed decimal data with two digits per byte.
   Packed decimal data is useful in calculations requiring exact
   accuracy. It is operated on by the decimal string instructions.

   A packed decimal string is a contiguous sequence of bytes in
   memory. It is specified by two attributes: the address A of
   the first byte and a length L, which is the number of digits in
   the string and not the length of the string in bytes. The bytes
   of a packed decimal string are divided into two, 4-bit fields
   (nibbles). Each nibble except the low nibble (bits 3:0) of the
   last (highest-addressed) byte must contain a decimal digit. The
   low nibble of the highest-addressed byte must contain a sign. The
   representation for the digits and sign is indicated as follows:

   Digit
   or
   Sign  Decimal        Hexadecimal

   0     0              0
   1     1              1
   2     2              2
   3     3              3
   4     4              4
   5     5              5
   6     6              6
   7     7              7
   8     8              8
   9     9              9
   +     10,12,14, or   A,C,E, or F
   -     15             B or D
         11 or 13

   The preferred sign representation is 12 for plus (+)  and 13 for
   minus (-). The length L is the number of digits in the packed
   decimal string (not counting the sign); L must be in the range
   0 to 31. When the number of digits is odd, the digits and the
   sign fit into a string of bytes whose length is defined by the
   following equation: L/2(integer part only) + 1. When the number
   of digits is even, it is required that an extra 0 appear in the
   high nibble (bits 7:4) of the first byte of the string. Again,
   the length in bytes of the string is L/2 + 1.

   The address A of the string specifies the byte of the string
   containing the most-significant digit in its high nibble. Digits
   of decreasing significance are assigned to increasing byte
   addresses and from high nibble to low nibble within a byte. 
   Thus, +123 has a length of 3. The packed decimal number -12 
   has a length of 2. 
 

5  Example

       .PACKED -12,PACKED_SIZED        ; PACKED_SIZE gets value of 2
       .PACKED +500
       .PACKED 0
       .PACKED -0,SUM_SIZE             ; SUM_SIZE gets value of 1
 

4  $PROCEDURE_DESCRIPTOR
   Defines a procedure descriptor structure at the current psect and
   offset.

   Format

     $PROCEDURE_DESCRIPTOR
 

5  Description
   The arguments for the $PROCEDURE_DESCRIPTOR macro are the same as
   the $ROUTINE macro, with the following exceptions:

   o  The ENTRY argument is required.

   o  There are no CODE_SECTION, LINKAGE_SECTION, DATA_SECTION,
      DATA_SECTION_POINTER, or STANDARD_PROLOGUE arguments.

   o  There is an additional END_PROLOGUE argument. This argument
      must be a label that you define at the end of the routine's
      prologue sequence. This argument is required for stack and
      register procedure types.
 

5  Notes

   o  Because the $ROUTINE macro invokes the $PROCEDURE_DESCRIPTOR
      macro for you, you do not need to use the
      $PROCEDURE_DESCRIPTOR macro if you use $ROUTINE. You may wish
      to use $PROCEDURE_DESCRIPTOR when you are not using $ROUTINE.
 

5  Example

           $PROCEDURE_DESCRIPTOR p1,           -
                             KIND=NULL,        -
                             ENTRY=p1_entry
 

4  $RESET_LP_LIST
   Clears the list of linkage pairs maintained by the $LINKAGE_PAIR
   and $CALL macros.

   Format

     $RESET_LP_LIST
 

5  Description
   The $LINKAGE_PAIR and $CALL macros maintain an assembly-time
   list of linkage pairs that the $LINKAGE_PAIR macro has stored in
   the linkage section. This list enables $LINKAGE_PAIR and $CALL
   to use the same linkage pair for multiple routine calls to the
   same routine. You can clear this list of linkage pairs with the
   $RESET_LP_LIST macro.

   Under normal circumstances, you do not need to clear the linkage-
   pair list. Some of the times when you do are as follows:

   o  When you change the psect assigned to the linkage section.

   o  If distance from the linkage section of your current routine
      falls more than 32K bytes beyond where the linkage pair has
      been stored.
 

5  Example

        ; Define the linkage section psect for routines A & B
        $LINK$ = "AB_LINK,NOEXE,OCTA"

        $ROUTINE A, KIND=STACK
        .BASE  R27, $LS
        $CALL D ; Linkage pair is stored in A's linkage
          ;  section and put on the assembly-time list
        $RETURN
        $END_ROUTINE A

        $ROUTINE B, KIND=STACK
        .BASE  R27, $LS
        $CALL D ; Linkage pair is found on the list,
          ;  and used from A's linkage section
        $RETURN
        $END_ROUTINE B

        ; Define a different linkage section for routine C
        $LINK$ = "C_LINK,NOEXE,OCTA"

        ; Linkage pairs that are on the list are in A & B's linkage
        ; section, which is not easily accessible by C.  Therefore,
        ; clear the list.
        $RESET_LP_LIST

        $ROUTINE C, KIND=STACK
        .BASE  R27, $LS
        $CALL D ; Linkage pair is stored in C's linkage
          ;  section and put on the assembly-time list
        $RETURN
        $END_ROUTINE B
 

4  $RETURN
   Generates a standard epilogue instruction sequence.

   Format

     $RETURN
 

5  Description
   Generates a standard epilogue instruction sequence when used
   within a stack or register routine defined with the $ROUTINE
   macro. The epilogue sequence generated by $RETURN restores any
   registers you specify with the SAVED_REGS argument to $ROUTINE
   and performs stack frame management as necessary. You can use
   $RETURN whether or not you specify STANDARD_PROLOGUE as TRUE or
   accept the default.

   You can use $RETURN any number of times within a given stack or
   register routine to affect a return to the calling routine.

   You must not use the $BEGIN_EPILOGUE or $END_EPILOGUE macros
   for an epilogue sequence generated by $RETURN. $RETURN invokes
   $BEGIN_EPILOGUE and $END_EPILOGUE for you.
 

5  Example

       $ROUTINE FOOZLE, KIND=REGISTER, SAVE_FP=R1
           :
           :
           :
       $RETURN
       $END_ROUTINE FOOZLE
 

4  $ROUTINE
   Defines the current routine and creates a context for the
   routine.

   Format

     $ROUTINE  NAME=routine name -

               ALIASES=alias names -

               LOCAL=boolean value -

               STANDARD_PROLOGUE=boolean value -

               ENTRY=code entry point -

               CODE_SECTION=code section psect name -

               DATA_SECTION=data section psect name -

               DATA_SECTION_POINTER=boolean value -

               LINKAGE_SECTION=linkage section psect name -

               KIND=routine type-

               HANDLER_REINVOKABLE=boolean value -

               BASE_REG_IS_FP=boolean value-

               REI_RETURN=boolean value -

               STACK_RETURN_VALUE=boolean value -

               RSA_OFFSET=integer value -

               SAVE_FP=register name -

               SAVE_RA=return address register name -

               SIZE=numeric value -

               SAVED_REGS=list of registers -

               HANDLER=exception handler address -

               HANDLER_DATA=data address for exception handler -

               SYNCH_EXCEPTIONS=boolean value-

               PROC_VALUE=procedure value -

               ENVIRONMENT=environment value -

               FUNC_RETURN=function return type -

               ARGLIST=argument type list -

               USES_VAX_ARGLIST=boolean value -

               OVERRIDE_FLAGS=procedure descriptor flags -

               DEFAULT_SIGNATURE=boolean value -

               COMMON_BASE=list of registers -

               TARGET_INVO=boolean value -

               EXCEPTION_MODE=mode -
 

5  Parameters
 

NAME

   The name of the routine. This argument is required for all
   procedure kinds. There is no default. For example:

   NAME=FOOZLE
 

ALIASES

   List of alias names for the routine. This argument is optional
   for all procedure types. There is no default. For example:

   ALIASES=<FOO,BAR,FOOBAR,foo,bar,foobar,Foo,Bar,FooBar>
 

LOCAL

   Boolean value indicating whether the routine is local (TRUE) or
   externally visible (FALSE). This argument is optional for all
   procedure kinds. The default is FALSE. For example:

   LOCAL=TRUE
 

STANDARD_PROLOGUE

   Specifies a Boolean value to indicate whether $ROUTINE should
   generate a standard instruction prologue sequence at the
   beginning of the routine's code section. This argument is
   optional and valid only with REGISTER and STACK procedures. If
   the procedure type is stack or register, the default is TRUE and
   $ROUTINE generates a standard prologue sequence. The prologue
   sequence generated by $ROUTINE saves the registers you specify
   with the SAVED_REGS argument and performs stack-frame management
   as necessary.

   If you also specify BASE_REG_IS_FP=FALSE, the standard prologue
   sequence generated by $ROUTINE makes a copy of the procedure
   descriptor address that is in R27 upon entry into R29 (FP). While
   you cannot change the value in R29 before the epilogue, you can
   use R29 as a working, linkage-section register. If you specify
   the STANDARD_PROLOGUE argument as FALSE, you must code your own
   prologue sequence and mark the end of the prologue with the $END_
   PROLOGUE macro. Whether or not you specify STANDARD_PROLOGUE as
   TRUE or accept the default, you can generate a standard epilogue
   sequence for stack and register procedures with the $RETURN
   macro. For example:

   STANDARD_PROLOGUE=FALSE
 

ENTRY

   The name of the code-entry point. This argument is the code
   entry-point label that $ROUTINE defines for you at the beginning
   of the code section for the routine. If this argument is omitted,
   $ROUTINE generates a label. For example:

   ENTRY=FOOZLE_ENTRY
 

CODE_SECTION

   The psect name and attributes of the code section. This argument
   is optional for all procedure kinds. If omitted, the default
   is the name and attributes defined by the $CODE$ lexical string
   symbol. If you specify a name and attributes for the CODE_SECTION
   argument, $ROUTINE redefines the $CODE$ lexical string symbol
   such that the specified values become the new default. Initially,
   $CODE$ is defined as follows:

   $CODE$ = "$CODE$,OCTA,PIC,CON,REL,LCL,SHR,EXE,NORD,NOWRT"

   Since you must delimit the psect name and attributes using
   commas, be sure to enclose this argument within angle brackets
   to avoid having the assembler interpret the name and attributes
   as different arguments to $ROUTINE. For example:

   CODE_SECTION=<MY_CODE,EXE,QUAD,NOWRT>
 

DATA_SECTION

   The psect name and attributes of the data section. This argument
   is optional for all procedure kinds. If omitted, the default
   is the name and attributes defined by the $DATA$ lexical string
   symbol. If you specify a name and attributes for the DATA_SECTION
   argument, $ROUTINE redefines the $DATA$ lexical string symbol
   such that the specified values become the new default. Initially,
   $DATA$ is defined as follows:

   $DATA$ = "$DATA$,OCTA,NOPIC,CON,REL,LCL,NOSHR,NOEXE,RD,WRT"

   Since you must delimit the psect name and attributes using
   commas, be sure to enclose this argument within angle brackets
   to avoid having the assembler interpret the name and attributes
   as different arguments to $ROUTINE. For example:

   DATA_SECTION=<MY_DATA,NOEXE,QUAD,RD,WRT>
 

DATA_SECTION_POINTER

   Boolean value indicating whether $ROUTINE should store a pointer
   to the data section in the linkage section and define $DP as
   the address of that pointer. This argument is optional for all
   procedure kinds. The default is FALSE. For example:

   DATA_SECTION_POINTER=TRUE

   You can use the DATA_SECTION_POINTER argument as follows:

            $ROUTINE TALLY_HO, DATA_SECTION_POINTER=TRUE
            $DATA_SECTION
    TALLY:  .QUAD 0
            $CODE_SECTION
            .BASe       R27, $LS  ; Inform assembler that R27->$LS
            LDQ         R1, $DP   ; R1->$DS
            .BASE R1,$DS          ;Inform assembler that R1-$DS
            LDQ         R0, TALLY ; R0<-TALLY
            LDA         R0, 1(R0) ; R0<-R0++
            STQ         R0, TALLY ; TALLY<-R0
            RET         (R26)     ; Return
            $END_ROUTINE TALLY_HO

   In this example, the DATA_SECTION_POINTER argument is specified
   in order to obtain linkage to the data section. The first LDQ
   instruction loads R1 with the pointer to the data section
   that $ROUTINE stores in the linkage section. The next three
   instructions increment the value in the TALLY variable in the
   data section. Finally, the routine returns the incremented value
   to its caller in R0.
 

LINKAGE_SECTION

   The psect name and attributes of the linkage section. This
   argument is optional for all procedure kinds. If omitted, the
   default is the name and attributes defined by the $LINK$ lexical
   string symbol. If you specify a name and attributes for the
   LINKAGE_SECTION argument, $ROUTINE redefines the $LINK$ lexical
   string symbol such that the specified values become the new
   default. Initially, $LINK$ is defined as follows:

   $LINK$ = "$LINK$,OCTA,NOPIC,CON,REL,LCL,NOSHR,NOEXE,RD,NOWRT"

   Since you must delimit the psect name and attributes using
   commas, be sure to enclose this argument within angle brackets
   to avoid having the assembler interpret the name and attributes
   as different arguments to $ROUTINE. For example:

   LINKAGE_SECTION=<MY_LINK,NOEXE,QUAD,RD,NOWRT>
 

KIND

   Specifies the kind of routine being defined. This must be one
   of the following: STACK, REGISTER, NULL, or BOUND. This is an
   optional argument. The default is NULL. For example:

   KIND=STACK
 

HANDLER_REINVOKABLE

   Specifies a Boolean value to indicate whether the condition
   handler can be re-invoked. This argument is optional and valid
   only with STACK and REGISTER procedures. It defaults to FALSE
   if no value is specified and the procedure kind is STACK or
   REGISTER. Note that this argument is only valid if a value is
   also specified for the HANDLER argument. For example:

   HANDLER_REINVOKABLE=TRUE
 

BASE_REG_IS_FP

   Specifies a Boolean value to indicate whether register R29
   (FP) is used as the frame-pointer base register (TRUE) or not
   (FALSE). If specified as FALSE, R29 must be used to hold the
   address of the procedure descriptor (or the address of the
   address of the procedure descriptor-see the OpenVMS Calling
   Standard. You can use R29 to hold a working copy of the linkage-
   section address passed in R27. In addition, your prologue and
   epilogue instruction sequences can be shorter and more efficient.
   However, you cannot make standard calls to other routines if
   BASE_REG_IS_FP is specified as FALSE. This argument is optional
   and valid only with stack and register procedure kinds. It
   defaults to TRUE if the procedure type is stack or register.
   For example:

   BASE_REG_IS_FP=FALSE
 

REI_RETURN

   Specifies a Boolean value to indicate whether this routine
   returns using an REI instruction. This argument is optional and
   valid only with STACK, REGISTER, and NULL procedure kinds. It
   defaults to FALSE if the procedure kind is STACK, REGISTER, or
   NULL. For example:

   REI_RETURN=TRUE
 

STACK_RETURN_VALUE

   This argument is obsolete. Do not specify this argument.
 

RSA_OFFSET

   An integer value specifying the stack offset (in bytes) of the
   register save area. This argument is optional and valid only
   for STACK procedures. If you specify BASE_REG_IS_FP as TRUE,
   the value you specify with RSA_OFFSET must be at least 8. RSA_
   OFFSET defaults to 8 if BASE_REG_IS_FP is specified as TRUE, 0
   otherwise. For example:

   RSA_OFFSET=32
 

SAVE_FP

   The register that contains a copy of the value of FP (R29) upon
   entry to this routine. The prologue instruction sequence must
   copy FP to the register specified by SAVE_FP and the epilogue
   instruction sequence(s) must restore FP from the register
   specified by SAVE_FP. This argument is required and only valid
   for REGISTER procedures. There is no default. For example:

   SAVE_FP=R1
 

SAVE_RA

   The register that contains the return address. This argument
   is optional and only valid for REGISTER procedures. If SAVE_RA
   is not R26, the prologue instruction sequence must copy R26 to
   the register specified by SAVE_RA and the epilogue instruction
   sequence(s) must use the return address stored in the register
   specified by SAVE_FP to affect its return to caller. SAVE_RA
   defaults to R26 if the procedure kind is REGISTER. For example:

   SAVE_RA=R22
 

SIZE

   A numeric value that must be a multiple of 16 specifying the
   size of the fixed-stack area in bytes. This parameter is valid
   only for REGISTER and STACK procedure kinds. It defaults to the
   minimum value possible given the other arguments you specify or
   default. $ROUTINE computes the amount of stack storage needed for
   the register save area (if any) and defines the $RSA_END symbol
   to be the offset of the first byte beyond the register save area.
   If you wish to allocate a fixed area of stack beyond the register
   save area, you can specify an expression with the SIZE argument
   that includes the term $RSA_END plus the amount of fixed-stack
   storage you need for your application. For example:

   SIZE=$RSA_END+32
 

SAVED_REGS

   A list of registers saved on the stack by the prologue code of
   this routine. It is valid only for STACK procedures and you must
   specify at least FP (R29) with this argument. It defaults to FP
   (R29) for STACK procedures. For example:

   SAVED_REGS=<R5,FP,F2,F3,F4>

   The OpenVMS Calling Standard specifies that registers R0, R1,
   R28, R30 (SP), and R31 must never be saved and restored. If
   you specify these registers with the SAVED_REGS argument, the
   $ROUTINE macro issues a diagnostic warning message.
 

HANDLER

   The address of an exception handler. It is optional and valid
   only for STACK and REGISTER procedure kinds. By default, the
   procedure is defined not to have an exception handler. For
   example:

   HANDLER=MY_HANDLER
 

HANDLER_DATA

   The address of data for the specified handler, if any. This
   argument is optional and valid only for stack and register
   procedure kinds and has no default value. You cannot specify a
   HANDLER_DATA argument if you do not specify the HANDLER argument.
   For example:

   HANDLER_DATA=MY_HANDLER_DATA
 

SYNCH_EXCEPTIONS

   An argument to indicate whether exceptions must be synchronized
   or not. This argument is optional with STACK and REGISTER
   routines and is not allowed with other kinds of routines. This
   argument defaults to TRUE if you specify an exception handler
   with the HANDLER argument. Otherwise, it defaults to FALSE.
   When this argument is TRUE and you specify or accept the default
   STANDARD_PROLOGUE=TRUE, $ROUTINE generates a TRAPB instruction
   as part of the standard prologue sequence. In addition, when this
   argument is true, the $RETURN macro generates a TRAPB instruction
   as part of the standard epilogue sequence. When this argument is
   FALSE, neither $ROUTINE nor $RETURN generate TRAPB instructions.
 

PROC_VALUE

   The procedure value of a bound procedure's parent. This argument
   is required for BOUND procedures and is invalid for all other
   procedure kinds. For example:

   PROC_VALUE=PARENT_PROC
 

ENVIRONMENT

   Specifies an environment value. This parameter is optional and
   valid only for BOUND procedures. It has no default value. For
   example:

   ENVIRONMENT=0
 

FUNC_RETURN

   Specifies the function return type. This argument is optional
   and valid for all procedure kinds. If specified, it must be one
   of the following: I64, D64, I32, U32, FF, FD, FG, FS, FT, FFC,
   FDC, FGC, FSC, or FTC. These values correspond to those listed in
   Table 3-7 of the OpenVMS Calling Standard that have an additional
   "RASE$K_FR_" prefix. There is no default. For example:

   FUNC_RETURN=U32
 

ARGLIST

   Argument type list. This argument is optional and valid for
   all procedure kinds. If the argument list contains one or more
   elements, each of the first six elements must be one of the
   following: Q, I32, U32, FF, FD, FG, FS, or FT. The seventh and
   subsequent arguments (if any) must be either I32 or Q.

   These values correspond to the PSIG$K_RA_* and MASE$K_MA_*
   signature encodings in Table 3-6 of the OpenVMS Calling Standard.
   There is no default. If you specify this argument, $ROUTINE
   generates a procedure signature block. For example:

   ARGLIST=<Q,I32,FF,FF,U32>.
 

USES_VAX_ARGLIST

   Specifies a Boolean value indicating whether the routine uses a
   VAX argument list. This argument is optional for all procedure
   kinds and defaults to FALSE. If you specify this argument,
   $ROUTINE generates a procedure signature block. For example:

   USES_VAX_ARGLIST=TRUE
 

OVERRIDE_FLAGS

   Specifies overriding flags for the PDSC$W_FLAGS field in the
   procedure descriptor. This argument is optional and valid for
   all procedure kinds. However, it is required for BOUND procedures
   when the parameter specified with the PROC_VALUE argument is an
   external or forward reference. There is no default. For example:

   OVERRIDE_FLAGS=PARENT_FLAGS
 

DEFAULT_SIGNATURE

   Specifies a Boolean value to indicate whether the standard
   procedure signature is used. TRUE means to use the standard
   signature. It is optional and valid for all procedure kinds.
   The default is FALSE if you specify either the ARGLIST or USES_
   VAX_ARGLIST arguments. Otherwise, the default is TRUE. Note that
   this argument must be FALSE or blank if you specify either the
   ARGLIST or USES_VAX_ARGLIST arguments. For example:

   DEFAULT_SIGNATURE=TRUE
 

COMMON_BASE

   An argument to specify one or more base registers that are used
   in common with other routines. This argument is optional for
   all routine kinds. By default, $ROUTINE invalidates any previous
   .BASE directives that may be in effect when you invoke $ROUTINE.
   In this way, you are prevented from inadvertently processing the
   second or subsequent routines in a module with .BASE directives
   in effect that apply only to a previous routine. However, you
   may wish to share a common base register assignment between a
   number of routines. To do so, you can reissue the appropriate
   .BASE directive or directives after each invocation of $ROUTINE.
   Alternatively, you can specify one or more common base registers
   with the COMMON_BASE argument, and enter the appropriate .BASE
   directive or directives only once at the beginning of the module.
   Specify the value for the COMMON_BASE argument as a list of
   integer registers. For example:

   COMMON_BASE=<R5,R13>

   In this example, $ROUTINE invalidates any previous .BASE
   directives except those for registers R5 and R13. Previous .BASE
   directives for registers R5 and R13 are unaffected.
 

TARGET_INVO

   Specifies a Boolean value indicating whether or not the exception
   handler for this procedure is invoked when this procedure is the
   target of an invocation unwind. (TARGET_INVO=TRUE) causes the
   exception handler to be invoked during an unwind. The default is
   TARGET_INVO=FALSE.
 

EXCEPTION_MODE

   An argument to specify one of the following exception modes with
   STACK and REGISTER procedures:

   o  SIGNAL-raise all exceptions except underflow.

   o  SIGNAL_ALL-raise all exceptions.

   o  SILENT-raise no exceptions.

   o  FULL_IEEE-only raise exceptions as per IEEE control bits.

   The default is EXCEPTION_MODE=SIGNAL.
 

5  Description
   $ROUTINE defines a routine, makes it the current routine, and
   performs the following actions:

   o  Creates and associates a linkage section, code section, and
      data section with the routine.

   o  Defines a procedure descriptor and optional signature block in
      accordance with the values of macro arguments.

   o  Optionally stores a pointer to the data section within the
      linkage section.

   o  Creates the following numeric and lexical symbols:

      Symbol      Description

      $CS         Address at start of the current routine's code
                  section.
      $DS         Address at start of the current routine's data
                  section.
      $DP         Optional address of a pointer to the current
                  routine's data section. This symbol has a value
                  that is an address in the current routine's
                  linkage section at which the $ROUTINE macro has
                  placed the address of the data section ($DS) as
                  follows:

                  $DP = .
                  .ADDRESS $DS

                  $DP enables you to access the data area of the
                  current routine from its linkage section.
      $LS         Address of the current routine's linkage section.
      $SIZE       Size of fixed area of stack frame of the current
                  routine. This symbol is valid only with STACK and
                  REGISTER routines.
      $RSA_       The offset within the fixed-stack area to the
      OFFSET      register save area. This symbol is valid only with
                  STACK routines.
      $RSA_END    The offset within the fixed-stack area to the the
                  first byte beyond the end of the register save
                  area (if any).
      $CODE$      A lexical string symbol that defines the routine's
                  code psect name and attributes.
      $DATA$      A lexical symbol that defines the routine's data
                  psect name and attributes.
      $LINK$      A lexical string symbol that defines the routine's
                  linkage psect name and attributes.

   o  Optionally generates a standard instruction prologue sequence
      at the beginning of the code section.

      If you specify /NAMES=AS_IS on the command line, all but
      the last three of these symbols are defined in both complete
      uppercase and complete lowercase. These symbols are intended
      for your use outside of the macros themselves. For example,
      the values of these numeric symbols may be useful as a
      mnemonic when coding an instruction with a register as in
      the following example:

       lda   SP,-$SIZE(SP)

      The last three symbols, $CODE$, $DATA$, and $LINK$, are only
      defined in uppercase. They are used by the $ROUTINE macro
      for the default code, data, and linkage section psect names
      and attributes. You can define these symbols before invoking
      $ROUTINE to alter the default program sections as follows:

      -  $CODE$ = "MY_CODE,EXE,OCTA,SHR,NORD,NOWRT,GBL"

      -  $DATA$ = "MY_DATA,NOEXE,OCTA,NOSHR,RD,WRT,GBL"

      -  $LINK$ = "MY_LINK,NOEXE,OCTA,SHR,RD,NOWRT,GBL"

      These statements cause $ROUTINE to use the previous psect
      names and attributes by default. If you specify any of the
      CODE_SECTION, DATA_SECTION, or LINKAGE_SECTION arguments in
      your invocation of $ROUTINE, $ROUTINE uses the psect name and
      attributes specified with the argument.

      In addition, $ROUTINE redefines the corresponding $CODE$,
      $DATA$, or $LINK$ lexical string symbol to the value
      you specify when you specify any of the CODE_SECTION,
      DATA_SECTION, or LINKAGE_SECTION arguments with $ROUTINE.
 

5  Example

               $ROUTINE MAIN1, KIND=NULL

               $ROUTINE MAIN1,         -
                   KIND=STACK,         -
                   SIZE=48,            -
                   SAVED_REGS=<R2,FP,F5>
 

3  MACRO-64_Alpha_Architecture_Quick_Reference
   This topic provides figures and tables showing the data types
   and addressing capabilities of the Alpha architecture. The
   information is derived from the Alpha Architecture Quick
   Reference Guide. Minor changes have been made to reflect the
   usage of the Alpha architecture that is specific to MACRO-64.

   For more information, see the Alpha Architecture Reference Manual
   and the OpenVMS Calling Standard.
 

 

4  Register_Usage_Conventions
   Register Usage Conventions for OpenVMS Alpha lists the register
   usage conventions for OpenVMS Alpha. MACRO-64 recognizes FP and
   SP as register synonyms, but does not recognize AI, RA, or PV as
   register synonyms.

   Table 11 Register Usage Conventions for OpenVMS Alpha

   R0             Int func ret value
   R1             Scratch
   R2-R15         Saved
   R16-           Argument
   R21
   R22-           Scratch
   R24
   R25     AI     Argument information
   R26     RA     Return address
   R27     PV     Procedure value
   R28            Volatile scratch
   R29     FP     Stack frame base
   R30     SP     Stack pointer
   R31            Zero
   F0             F-P function ret value
   F1             F-P complex func ret value
   F2-F9          Saved
   F10-           Scratch
   F15
   F16-           Argument
   F22
   F23-           Scratch
   F30
   F31            Zero
 

4  Instruction_Operand_Notation
   Instruction Operand Notation shows the notation for instruction
   operands. The notation format is as follows:

   <name>.<access type><data type>

   Table 12 Instruction Operand Notation

   <name>:
   disp Displacement field
   fnc  PALcode function field
   Ra   Integer register operand in the Ra field
   Rb   Integer register operand in the Rb field
   #b   Integer literal operand in the Rb field
   Rc   Integer register operand in the Rc field
   Fa   Floating-point register operand in the Ra field
   Fb   Floating-point register operand in the Rb field
   Fc   Floating-point register operand in the Rc field

   <access type>:
   a    The operand is used in an address calculation to form an
        effective address. The data-type code that follows indicates
        the units of addressability (or scale factor) applied to
        this operand when the instruction is decoded.
   i    The operand is an immediate literal.
   m    The operand is both read and written.
   r    The operand is read only.
   w    The operand is write only.

   <data type>:
   b    Byte
   f    F_floating
   g    G_floating
   l    Longword
   q    Quadword
   s    IEEE single floating (S_floating)
   t    IEEE double floating (T_floating)
   w    Word
   x    The data type is specified by the instruction.
 

4  Instruction_Qualifier_Notation
   Instruction Qualifier Notation shows the notation for instruction
   qualifiers.

   Table 13 Instruction Qualifier Notation

   /QualifierMeaning

   C         Chopped rounding
   D         Dynamic rounding
             (mode determined by FPCR<DYN>)
   I         Inexact result enable
   M         Minus infinity rounding
   S         Software completion enable
   U         Floating underflow enable
   V         Integer overflow enable
 

4  F-P_Control_Register_(FPCR)_Format
   F-P Control Register (FPCR) Format shows the format for the F-P
   control register.

   Table 14 F-P Control Register (FPCR) Format

   Bits   Symbol  Meaning

   63     SUM     Bitwise OR of <57:52>
   62:60  RAZ     Read as zero; ignored when written
          /IGN
   59:58  DYN     IEEE rounding mode selected:
                  00   Chopped
                  01   Minus infinity
                  10   Normal rounding
                  11   Plus infinity
   57     IOV     Integer overflow of destination precision
   56     INE     Floating mathematically inexact result
   55     UNF     Floating underflow of destination exponent
   54     OVF     Floating overflow of destination exponent
   53     DZE     Floating divide with divisor of zero
   52     INV     Floating invalid operand value
   51:0   RAZ     Read as zero; ignored when written
          /IGN
 

4  Decodable_Pseudo-Operations
   Decodable Pseudo-Operations lists the decodable pseudo-operations
   and their associated actual instructions.

   Table 15 Decodable Pseudo-Operations

   Pseudo-              Actual
   Operation            Instruction

   BR       target      BR         R31,target
   CLR      Rx          BIS        R31,R31,Rx
   FABS     Fx,Fy       CPYS       F31,Fx,Fy
   FCLR     Fx          CPYS       F31,F31,Fx
   FMOV     Fx,Fy       CPYS       Fx,Fx,Fy
   FNEG     Fx,Fy       CPYSN      Fx,Fx,Fy
   FNOP                 CPYS       F31,F31,F31
   MOV      Lit,Rx      LDA        Rx,lit(R31)
   MOV      {Rx         BIS        R31,{Rx/Lit8},Ry
            /Lit8},Ry
   MF_FPCR  Fx          MF_FPCR    Fx,Fx,Fx
   MT_FPCR  Fx          MT_FPCR    Fx,Fx,Fx
   NEGF     Fx,Fy       SUBF       F31,Fx,Fy
   NEGF/S   Fx,Fy       SUBF/S     F31,Fx,Fy
   NEGG     Fx,Fy       SUBG       F31,Fx,Fy
   NEGG/S   Fx,Fy       SUBG/S     F31,Fx,Fy
   NEGL     {Rx         SUBL       R31,{Rx/Lit},Ry
            /Lit8},Ry
   NEGL/V   {Rx         SUBL/V     R31,{Rx/Lit},Ry
            /Lit8},Ry
   NEGQ     {Rx         SUBQ       R31,{Rx/Lit},Ry
            /Lit8},Ry
   NEGQ/V   {Rx         SUBQ/V     R31,{Rx/Lit},Ry
            /Lit8},Ry
   NEGS     Fx,Fy       SUBS       F31,Fx,Fy
   NEGS/SU  Fx,Fy       SUBS/SU    F31,Fx,Fy
   NEGS/SUI Fx,FY       SUBS/SUI   F31,Fx,Fy
   NEGT     Fx,Fy       SUBT       F31,Fx,Fy
   NEGT/SU  Fx,Fy       SUBT/SU    F31,Fx,Fy
   NEGT/SUI Fx,FY       SUBT/SUI   F31,Fx,Fy
   NOP                  BIS        R31,R31,R31
   NOT      {Rx         ORNOT      R31,{Rx/Lit},Ry
            /Lit8},Ry
   SEXTL    {Rx         ADDL       R31,{Rx/Lit},Ry
            /Lit},Ry
   UNOP                 LDQ_U      R31,0(Rx)
 

4  Common_Architecture_Opcodes_in_Numerical_Order
   This table lists the common architecture opcodes in numerical
   order.

   MACRO-64 Alpha Architecture Quick Reference

   A.6 Common Architecture Opcodes in Numerical Order

   Table_A-6_Common_Architecture_Opcodes_in_Numerical_Order

   Opcode________________Opcode________________Opcode___

   00      CALL_PAL      11.26   CMOVNE        15.01E    CVTDG/C
   01      OPC01         11.28   ORNOT         15.020    ADDG/C
   02      OPC02         11.40   XOR           15.021    SUBG/C
   03      OPC03         11.44   CMOVLT        15.022    MULG/C
   04      OPC04         11.46   CMOVGE        15.023    DIVG/C
   05      OPC05         11.48   EQV           15.02C    CVTGF/C
   06      OPC06         11.64   CMOVLE        15.02D    CVTGD/C
   07      OPC07         11.66   CMOVGT        15.02F    CVTGQ/C
   08      LDA           12.02   MSKBL         15.03C    CVTQF/C
   09      LDAH          12.06   EXTBL         15.03E    CVTQG/C
   0A      OPC0A         12.0B   INSBL         15.080    ADDF
   0B      LDQ_U         12.12   MSKWL         15.081    SUBF
   0C      OPC0C         12.16   EXTWL         15.082    MULF
   0D      OPC0D         12.1B   INSWL         15.083    DIVF
   0E      OPC0E         12.22   MSKLL         15.09E    CVTDG
   0F      STQ_U         12.26   EXTLL         15.0A0    ADDG
   10.00   ADDL          12.2B   INSLL         15.0A1    SUBG
   10.02   S4ADDL        12.30   ZAP           15.0A2    MULG
   10.09   SUBL          12.31   ZAPNOT        15.0A3    DIVG
   10.0B   S4SUBL        12.32   MSKQL         15.0A5    CMPGEQ
   10.0F   CMPBGE        12.34   SRL           15.0A6    CMPGLT
   10.12   S8ADDL        12.36   EXTQL         15.0A7    CMPGLE
   10.1B   S8SUBL        12.39   SLL           15.0AC    CVTGF
   10.1D   CMPULT        12.3B   INSQL         15.0AD    CVTGD
   10.20   ADDQ          12.3C   SRA           15.0AF    CVTGQ
   10.22   S4ADDQ        12.52   MSKWH         15.0BC    CVTQF
   10.29   SUBQ          12.57   INSWH         15.0BE    CVTQG
   10.2B   S4SUBQ        12.5A   EXTWH         15.100    ADDF/UC
   10.2D   CMPEQ         12.62   MSKLH         15.101    SUBF/UC
   10.32   S8ADDQ        12.67   INSLH         15.102    MULF/UC
   10.3B   S8SUBQ        12.6A   EXTLH         15.103    DIVF/UC
   10.3D   CMPULE        12.72   MSKQH         15.11E    CVTDG
                                                         /UC
   10.40   ADDL/V        12.77   INSQH         15.120    ADDG
                                                         /UC
   10.49   SUBL/V        12.7A   EXTQH         15.121    SUBG
                                                         /UC
   10.4D   CMPLT         13.00   MULL          15.122    MULG
                                                         /UC
   10.60   ADDQ/V        13.20   MULQ          15.123    DIVG
                                                         /UC
   10.69   SUBQ/V        13.30   UMULH         15.12C    CVTGF
                                                         /UC
   10.6D   CMPLE         13.40   MULL/V        15.12D    CVTGD
                                                         /UC
   11.00   AND           13.60   MULQ/V        15.12F    CVTGQ
                                                         /VC
   11.08   BIC           14      OPC14         15.180    ADDF
                                                         /U
   11.14   CMOVLBS       15.000  ADDF/C        15.181    SUBF
                                                         /U
   11.16   CMOVLBC       15.001  SUBF/C        15.182    MULF
                                                         /U
   11.20   BIS           15.002  MULF/C        15.183    DIVF
                                                         /U
   11.24   CMOVEQ        15.003  DIVF/C        15.19E    CVTDG
                                                         /U
   15.1A0  ADDG/U        15.580  ADDF/SU       16.0A6    CMPTLT
   15.1A1  SUBG/U        15.581  SUBF/SU       16.0A7    CMPTLE
   15.1A2  MULG/U        15.582  MULF/SU       16.0AC    CVTTS
   15.1A3  DIVG/U        15.583  DIVF/SU       16.0AF    CVTTQ
   15.1AC  CVTGF/U       15.59E  CVTDG/SU      16.0BC    CVTQS
   15.1AD  CVTGD/U       15.5A0  ADDG/SU       16.0BE    CVTQT
   15.1AF  CVTGQ/V       15.5A1  SUBG/SU       16.0C0    ADDS
                                                         /D
   15.400  ADDF/SC       15.5A2  MULG/SU       16.0C1    SUBS
                                                         /D
   15.401  SUBF/SC       15.5A3  DIVG/SU       16.0C2    MULS
                                                         /D
   15.402  MULF/SC       15.5AC  CVTGF/SU      16.0C3    DIVS
                                                         /D
   15.403  DIVF/SC       15.5AD  CVTGD/SU      16.0E0    ADDT
                                                         /D
   15.41E  CVTDG/SC      15.5AF  CVTGQ/SV      16.0E1    SUBT
                                                         /D
   15.420  ADDG/SC       16.000  ADDS/C        16.0E2    MULT
                                                         /D
   15.421  SUBG/SC       16.001  SUBS/C        16.0E3    DIVT
                                                         /D
   15.422  MULG/SC       16.002  MULS/C        16.0EC    CVTTS
                                                         /D
   15.423  DIVG/SC       16.003  DIVS/C        16.0EF    CVTTQ
                                                         /D
   15.42C  CVTGF/SC      16.020  ADDT/C        16.0FC    CVTQS
                                                         /D
   15.42D  CVTGD/SC      16.021  SUBT/C        16.0FE    CVTQT
                                                         /D
   15.42F  CVTGQ/SC      16.022  MULT/C        16.100    ADDS
                                                         /UC
   15.480  ADDF/S        16.023  DIVT/C        16.101    SUBS
                                                         /UC
   15.481  SUBF/S        16.02C  CVTTS/C       16.102    MULS
                                                         /UC
   15.482  MULF/S        16.02F  CVTTQ/C       16.103    DIVS
                                                         /UC
   15.483  DIVF/S        16.03C  CVTQS/C       16.120    ADDT
                                                         /UC
   15.49E  CVTDG/S       16.03E  CVTQT/C       16.121    SUBT
                                                         /UC
   15.4A0  ADDG/S        16.040  ADDS/M        16.122    MULT
                                                         /UC
   15.4A1  SUBG/S        16.041  SUBS/M        16.123    DIVT
                                                         /UC
   15.4A2  MULG/S        16.042  MULS/M        16.12C    CVTTS
                                                         /UC
   15.4A3  DIVG/S        16.043  DIVS/M        16.12F    CVTTQ
                                                         /VC
   15.4A5  CMPGEQ/S      16.060  ADDT/M        16.140    ADDS
                                                         /UM
   15.4A6  CMPGLT/S      16.061  SUBT/M        16.141    SUBS
                                                         /UM
   15.4A7  CMPGLE/S      16.062  MULT/M        16.142    MULS
                                                         /UM
   15.4AC  CVTGF/S       16.063  DIVT/M        16.143    DIVS
                                                         /UM
   15.4AD  CVTGD/S       16.06C  CVTTS/M       16.160    ADDT
                                                         /UM
   15.4AF  CVTGQ/S       16.06F  CVTTQ/M       16.161    SUBT
                                                         /UM
   15.500  ADDF/SUC      16.07C  CVTQS/M       16.162    MULT
                                                         /UM
   15.501  SUBF/SUC      16.07E  CVTQT/M       16.163    DIVT
                                                         /UM
   15.502  MULF/SUC      16.080  ADDS          16.16C    CVTTS
                                                         /UM
   15.503  DIVF/SUC      16.081  SUBS          16.16F    CVTTQ
                                                         /VM
   15.51E  CVTDG/SUC     16.082  MULS          16.180    ADDS
                                                         /U
   15.520  ADDG/SUC      16.083  DIVS          16.181    SUBS
                                                         /U
   15.521  SUBG/SUC      16.0A0  ADDT          16.182    MULS
                                                         /U
   15.522  MULG/SUC      16.0A1  SUBT          16.183    DIVS
                                                         /U
   15.523  DIVG/SUC      16.0A2  MULT          16.1A0    ADDT
                                                         /U
   15.52C  CVTGF/SUC     16.0A3  DIVT          16.1A1    SUBT
                                                         /U
   15.52D  CVTGD/SUC     16.0A4  CMPTUN        16.1A2    MULT
                                                         /U
   15.52F  CVTGQ/SVC     16.0A5  CMPTEQ        16.1A3    DIVT
                                                         /U
   16.1AC  CVTTS/U       16.5AF  CVTTQ/SV      16.7BC    CVTQS
                                                         /SUI
   16.1AF  CVTTQ/V       16.5C0  ADDS/SUD      16.7BE    CVTQT
                                                         /SUI
   16.1C0  ADDS/UD       16.5C1  SUBS/SUD      16.7C0    ADDS
                                                         /SUID
   16.1C1  SUBS/UD       16.5C2  MULS/SUD      16.7C1    SUBS
                                                         /SUID
   16.1C2  MULS/UD       16.5C3  DIVS/SUD      16.7C2    MULS
                                                         /SUID
   16.1C3  DIVS/UD       16.5E0  ADDT/SUD      16.7C3    DIVS
                                                         /SUID
   16.1E0  ADDT/UD       16.5E1  SUBT/SUD      16.7E0    ADDT
                                                         /SUID
   16.1E1  SUBT/UD       16.5E2  MULT/SUD      16.7E1    SUBT
                                                         /SUID
   16.1E2  MULT/UD       16.5E3  DIVT/SUD      16.7E2    MULT
                                                         /SUID
   16.1E3  DIVT/UD       16.5EC  CVTTS/SUD     16.7E3    DIVT
                                                         /SUID
   16.1EC  CVTTS/UD      16.5EF  CVTTQ/SVD     16.7EC    CVTTS
                                                         /SUID
   16.1EF  CVTTQ/VD      16.6AC  CVTST/S       16.7EF    CVTTQ
                                                         /SVID
   16.2AC  CVTST         16.700  ADDS/SUIC     16.7FC    CVTQS
                                                         /SUID
   16.500  ADDS/SUC      16.701  SUBS/SUIC     16.7FE    CVTQT
                                                         /SUID
   16.501  SUBS/SUC      16.702  MULS/SUIC     17.010    CVTLQ
   16.502  MULS/SUC      16.703  DIVS/SUIC     17.020    CPYS
   16.503  DIVS/SUC      16.720  ADDT/SUIC     17.021    CPYSN
   16.520  ADDT/SUC      16.721  SUBT/SUIC     17.022    CPYSE
   16.521  SUBT/SUC      16.722  MULT/SUIC     17.024    MT_
                                                         FPCR
   16.522  MULT/SUC      16.723  DIVT/SUIC     17.025    MF_
                                                         FPCR
   16.523  DIVT/SUC      16.72C  CVTTS/SUIC    17.02A   FCMOVEQ
   16.52C  CVTTS/SUC     16.72F  CVTTQ/SVIC    17.02B   FCMOVNE
   16.52F  CVTTQ/SVC     16.73C  CVTQS/SUIC    17.02C   FCMOVLT
   16.540  ADDS/SUM      16.73E  CVTQT/SUIC    17.02D   FCMOVGE
   16.541  SUBS/SUM      16.740  ADDS/SUIM     17.02E   FCMOVLE
   16.542  MULS/SUM      16.741  SUBS/SUIM     17.02F   FCMOVGT
   16.543  DIVS/SUM      16.742  MULS/SUIM     17.030    CVTQL
   16.560  ADDT/SUM      16.743  DIVS/SUIM     17.130    CVTQL/V
   16.561  SUBT/SUM      16.760  ADDT/SUIM     17.530    CVTQL/SV
   16.562  MULT/SUM      16.761  SUBT/SUIM     18.0000   TRAPB
   16.563  DIVT/SUM      16.762  MULT/SUIM     18.0400   EXCB
   16.56C  CVTTS/SUM     16.763  DIVT/SUIM     18.4000   MB
   16.56F  CVTTQ/SVM     16.76C  CVTTS/SUIM    18.4400   WMB
   16.580  ADDS/SU       16.76F  CVTTQ/SVIM    18.8000   FETCH
   16.581  SUBS/SU       16.77C  CVTQS/SUIM    18.A000   FETCH_M
   16.582  MULS/SU       16.77E  CVTQT/SUIM    18.C000   RPCC
   16.583  DIVS/SU       16.780  ADDS/SUI      18.E000   RC
   16.5A0  ADDT/SU       16.781  SUBS/SUI      18.F000   RS
   16.5A1  SUBT/SU       16.782  MULS/SUI      19        PAL19
   16.5A2  MULT/SU       16.783  DIVS/SUI      1A.0      JMP
   16.5A3  DIVT/SU       16.7A0  ADDT/SUI      1A.1      JSR
   16.5A4  CMPTUN/SU     16.7A1  SUBT/SUI      1A.2      RET
   16.5A5  CMPTEQ/SU     16.7A2  MULT/SUI      1A.3      JSR_
                                                      COROUTINE
   16.5A6  CMPTLT/SU     16.7A3  DIVT/SUI      1B        PAL1B
   16.5A7  CMPTLE/SU     16.7AC  CVTTS/SUI     1C        OPC1C
   16.5AC  CVTTS/SU      16.7AF  CVTTQ/SVI     1D        PAL1D
   1E      PAL1E         2A      LDL_L         36        FBGE
   1F      PAL1F         2B      LDQ_L         37        FBGT
   20      LDF           2C      STL           38        BLBC
   21      LDG           2D      STQ           39        BEQ
   22      LDS           2E      STL_C         3A        BLT
   23      LDT           2F      STQ_C         3B        BLE
   24      STF           30      BR            3C        BLBS
   25      STG           31      FBEQ          3D        BNE
   26      STS           32      FBLT          3E        BGE
   27      STT           33      FBLE          3F        BGT
   28      LDL           34      BSR
   29      LDQ           35      FBNE
 

4  OpenVMS_PALcode_Instruction_Summary
   OpenVMS Unprivileged PALcode Instructions lists the OpenVMS
   unprivileged PALcode instructions and OpenVMS Privileged PALcode
   Instructions lists the OpenVMS privileged PALcode instructions.

   Table 16 OpenVMS Unprivileged PALcode Instructions

   Mnemonic    Opcode   Description

   AMOVRM      00.00A1  Atomic move from register to memory
   AMOVRR      00.00A0  Atomic move from register to register
   BPT         00.0080  Breakpoint
   BUGCHK      00.0081  Bugcheck
   CHMK        00.0083  Change mode to kernel
   CHME        00.0082  Change mode to executive
   CHMS        00.0084  Change mode to supervisor
   CHMU        00.0085  Change mode to user
   GENTRAP     00.00AA  Generate software trap
   IMB         00.0086  I-stream memory barrier
   INSQHIL     00.0087  Insert into longword queue at head
                        interlocked
   INSQHILR    00.00A2  Insert into longword queue at head
                        interlocked resident
   INSQHIQ     00.0089  Insert into quadword queue at head
                        interlocked
   INSQHIQR    00.00A4  Insert into quadword queue at head
                        interlocked resident
   INSQTIL     00.0088  Insert into longword queue at tail
                        interlocked
   INSQTILR    00.00A3  Insert into longword queue at tail
                        interlocked resident
   INSQTIQ     00.008A  Insert into quadword queue at tail
                        interlocked
   INSQTIQR    00.00A5  Insert into quadword queue at tail
                        interlocked resident
   INSQUEL     00.008B  Insert entry into longword queue
   INSQUEL/D   00.008D  Insert entry into longword queue deferred
   INSQUEQ     00.008C  Insert entry into quadword queue
   INSQUEQ/D   00.008E  Insert entry into quadword queue deferred
   PROBER      00.008F  Probe for read access
   PROBEW      00.0090  Probe for write access
   RD_PS       00.0091  Move processor status
   READ_UNQ    00.009E  Read unique context
   REI         00.0092  Return from exception or interrupt
   REMQHIL     00.0093  Remove from longword queue at head
                        interlocked
   REMQHILR    00.00A6  Remove from longword queue at head
                        interlocked resident
   REMQHIQ     00.0095  Remove from quadword queue at head
                        interlocked
   REMQHIQR    00.00A8  Remove from quadword queue at head
                        interlocked resident
   REMQTIL     00.0094  Remove from longword queue at tail
                        interlocked
   REMQTILR    00.00A7  Remove from longword queue at tail
                        interlocked resident
   REMQTIQ     00.0096  Remove from quadword queue at tail
                        interlocked
   REMQTIQR    00.00A9  Remove from quadword queue at tail
                        interlocked resident
   REMQUEL     00.0097  Remove entry from longword queue
   REMQUEL/D   00.0099  Remove entry from longword queue deferred
   REMQUEQ     00.0098  Remove entry from quadword queue
   REMQUEQ/D   00.009A  Remove entry from quadword queue deferred
   RSCC        00.009D  Read system cycle counter
   SWASTEN     00.009B  Swap AST enable for current mode
   WRITE_UNQ   00.009F  Write unique context
   WR_PS_SW    00.009C  Write processor status software field

   Table 17 OpenVMS Privileged PALcode Instructions

   Mnemonic       Opcode   Description

   CFLUSH         00.0001  Cache flush
   CSERVE         00.0009  Console service
   DRAINA         00.0002  Drain aborts
   HALT           00.0000  Halt processor
   LDQP           00.0003  Load quadword physical
   MFPR_ASN       00.0006  Move from processor register ASN
   MFPR_ESP       00.001E  Move from processor register ESP
   MFPR_FEN       00.000B  Move from processor register FEN
   MFPR_IPL       00.000E  Move from processor register IPL
   MFPR_MCES      00.0010  Move from processor register MCES
   MFPR_PCBB      00.0012  Move from processor register PCBB
   MFPR_PRBR      00.0013  Move from processor register PRBR
   MFPR_PTBR      00.0015  Move from processor register PTBR
   MFPR_SCBB      00.0016  Move from processor register SCBB
   MFPR_SISR      00.0019  Move from processor register SISR
   MFPR_SSP       00.0020  Move from processor register SSP
   MFPR_TBCHK     00.001A  Move from processor register TBCHK
   MFPR_USP       00.0022  Move from processor register USP
   MFPR_VPTB      00.0029  Move from processor register VPTB
   MFPR_WHAMI     00.003F  Move from processor register WHAMI
   MTPR_ASTEN     00.0026  Move to processor register ASTEN
   MTPR_ASTSR     00.0027  Move to processor register ASTSR
   MTPR_DATFX     00.002E  Move to processor register DATFX
   MTPR_ESP       00.001F  Move to processor register ESP
   MTPR_FEN       00.000B  Move to processor register FEN
   MTPR_IPIR      00.000D  Move to processor register IPRI
   MTPR_IPL       00.000E  Move to processor register IPL
   MTPR_MCES      00.0011  Move to processor register MCES
   MTPR_PERFMON   00.002B  Move to processor register PERFMON
   MTPR_PRBR      00.0014  Move to processor register PRBR
   MTPR_SCBB      00.0017  Move to processor register SCBB
   MTPR_SIRR      00.0018  Move to processor register SIRR
   MTPR_SSP       00.0021  Move to processor register SSP
   MTPR_TBIA      00.001B  Move to processor register TBIA
   MTPR_TBIAP     00.001C  Move to processor register TBIAP
   MTPR_TBIS      00.001D  Move to processor register TBIS
   MTPR_TBISD     00.0024  Move to processor register TBISD
   MTPR_TBISI     00.0025  Move to processor register TBISI
   MTPR_USP       00.0023  Move to processor register USP
   MTPR_VPTB      00.002A  Move to processor register VPTB
   STQP           00.0004  Store quadword physical
   SWPCTX         00.0005  Swap privileged context
   SWPPAL         00.000A  Swap PALcode image
 

4  PALcode_Opcodes_in_Numerical_Order
   PALcode Opcodes in Numerical Order lists the PALcode opcodes in
   numerical order.

   Table 18 PALcode Opcodes in Numerical Order

   Opcode(16Opcode(10)penVMS

   00.0000  00.0000  HALT
   00.0001  00.0001  CFLUSH
   00.0002  00.0002  DRAINA
   00.0003  00.0003  LDQP
   00.0004  00.0004  STQP
   00.0005  00.0005  SWPCTX
   00.0006  00.0006  MFPR_ASN
   00.0007  00.0007  MTPR_ASTEN
   00.0008  00.0008  MTPR_ASTSR
   00.0009  00.0009  CSERVE
   00.000A  00.0010  SWPPAL
   00.000B  00.0011  MFPR_FEN
   00.000C  00.0012  MTPR_FEN
   00.000D  00.0013  MTPR_IPIR
   00.000E  00.0014  MFPR_IPL
   00.000F  00.0015  MTPR_IPL
   00.0010  00.0016  MFPR_MCES
   00.0011  00.0017  MTPR_MCES
   00.0012  00.0018  MFPR_PCBB
   00.0013  00.0019  MFPR_PRBR
   00.0014  00.0020  MTPR_PRBR
   00.0015  00.0021  MFPR_PTBR
   00.0016  00.0022  MFPR_SCBB
   00.0017  00.0023  MTPR_SCBB
   00.0018  00.0024  MTPR_SIRR
   00.0019  00.0025  MFPR_SISR
   00.001A  00.0026  MFPR_TBCHK
   00.001B  00.0027  MTPR_TBIA
   00.001C  00.0028  MTPR_TBIAP
   00.001D  00.0029  MTPR_TBIS
   00.001E  00.0030  MFPR_ESP
   00.001F  00.0031  MTPR_ESP
   00.0020  00.0032  MFPR_SSP
   00.0021  00.0033  MTPR_SSP
   00.0022  00.0034  MFPR_USP
   00.0023  00.0035  MTPR_USP
   00.0024  00.0036  MTPR_TBISD
   00.0025  00.0037  MTPR_TBISI
   00.0026  00.0038  MFPR_ASTEN
   00.0027  00.0039  MFPR_ASTSR
   00.0029  00.0040  MFPR_VPTB
   00.002A  00.0041  MTPR_VPTB
   00.002B  00.0042  MTPR_PERFMON
   00.002E  00.0043  MTPR_DATFX
   00.003F  00.0063  MFPR_WHAMI
   00.0080  00.0128  BPT
   00.0081  00.0129  BUGCHK
   00.0082  00.0130  CHME
   00.0083  00.0131  CHMK
   00.0084  00.0132  CHMS
   00.0085  00.0133  CHMU
   00.0086  00.0134  IMB
   00.0087  00.0135  INSQHIL
   00.0088  00.0136  INSQTIL
   00.0089  00.0137  INSQHIQ
   00.008A  00.0138  INSQTIQ
   00.008B  00.0139  INSQUEL
   00.008C  00.0140  INSQUEQ
   00.008D  00.0141  INSQUEL/D
   00.008E  00.0142  INSQUEQ/D
   00.008F  00.0143  PROBER
   00.0090  00.0144  PROBEW
   00.0091  00.0145  RD_PS
   00.0092  00.0146  REI
   00.0093  00.0147  REMQHIL
   00.0094  00.0148  REMQTIL
   00.0095  00.0149  REMQHIQ
   00.0096  00.0150  REMQTIQ
   00.0097  00.0151  REMQUEL
   00.0098  00.0152  REMQUEQ
   00.0099  00.0153  REMQUEL/D
   00.009A  00.0154  REMQUEQ/D
   00.009B  00.0155  SWASTEN
   00.009C  00.0156  WR_PS_SW
   00.009D  00.0157  RSCC
   00.009E  00.0158  READ_UNQ
   00.009F  00.0159  WRITE_UNQ
   00.00A0  00.0160  AMOVRR
   00.00A1  00.0161  AMOVRM
   00.00A2  00.0162  INSQHILR
   00.00A3  00.0163  INSQTILR
   00.00A4  00.0164  INSQHIQR
   00.00A5  00.0165  INSQTIQR
   00.00A6  00.0166  REMQHILR
   00.00A7  00.0167  REMQTILR
   00.00A8  00.0168  REMQHIQR
   00.00A9  00.0169  REMQTIQR
   00.00AA  00.0170  GENTRAP
 

4  Common_Architecture_Instructions
 

3  Using_LSE_with_MACRO-64
   This topic explains how to use the Language-Sensitive Editor
   (LSE) with the MACRO-64 language. For LSE to function correctly,
   LSE must be installed prior to the MACRO-64 assembler.
 

4  Invoking_LSE
   To use LSE with the MACRO-64 language, you must name your program
   source file with a .M64 file extension. For example, to edit a
   file named TEST.M64, enter the following command:

   $ LSE TEST.M64

   Using the .M64 file extension invokes the LSE editor and places
   you in the MACRO-64 language environment.

   If you choose to use a different file extension, you can still
   use LSE in the MACRO-64 language environment. For example, to
   edit a file named TEST.ASM, enter the following command:

   $ LSE/LANGUAGE=MACRO64 TEST.ASM

   If you use LSE with MACRO-64, and you want the same behavior on
   the OpenVMS Alpha operating system as on the OpenVMS VAX operating
   system, enter the following LSE command:

   $ SET COMMAND LANGUAGE VMS
 

4  Running_Diagnostics
   You can run diagnostics in LSE to debug programs without leaving
   the LSE editor. For more information, see the Guide to Language-
   Sensitive Editor for VMS Systems and the MACRO-64 release notes.

   When running diagnostics in an LSE editing session, MACRO-64
   displays error messages of different severity levels.
 

3  Error_Messages

   The description of each message gives the severity, followed by
   additional explanatory text and suggested action.
 

4  ADDTRUNC
Storing an address expression into a storage allocation less than
the size of an address results in data truncation.

   Informational: The assembler stored a value that is too large for
   the allocated space, resulting in data truncation.

   User Action: Allocate more storage.
 

4  ALIGNFILLIGN
The optional .ALIGN fill pattern argument is ignored in psects with
the EXE and NOMIX attributes.

   Warning: The optional fill pattern is ignored because it is
   only valid for psects that do not possess the EXE and NOMIX
   attributes.

   User Action: Omit the fill pattern or specify the MIX psect
   attribute.
 

4  ALIGNFILLTRUNC
The value you specify for the .ALIGN optional fill pattern must be
an integer in the range of 0 . . . 255. Data truncation occurs with
the currently specified fill pattern in a byte storage location.

   Warning: The value you specify as the fill pattern for the .ALIGN
   directive must be within the range of 0 . . . 255. Data truncation
   occurs whenever you specify a value that is outside of this
   range.

   User Action: Specify a smaller value for the fill pattern.
 

4  ALIGNLABELIGN
The ALIGN_LABEL option has been replaced by the ALIGN_CODE option.

   Error: The ALIGN_LABEL option has been replaced by the ALIGN_CODE
   option.

   User Action: Use the recommended new option.
 

4  ALIGNTOBIG
Specified alignment is too large for PSECT.

   Error: The alignment you specified is too large for the current
   psect.

   User Action: Check the psect attributes to insure that the psect
   alignment is greater than or equal to the alignment you are
   requesting.
 

4  ASCIITRUNC
ASCII constant contains too many characters; value is truncated.

   Error: Your ASCII constant contains more than eight characters
   with the ^A or ^a radix specifier. The assembler deletes the
   extra characters.

   User Action: Check your source code. Use eight or less
   characters.
 

4  BADALIGN
Alignment specifier is out of range.

   Error: The alignment specifier used with the .PSECT or .ALIGN
   directive is out of range.

   User Action: See the descriptions of the .PSECT and .ALIGN
   directives.
 

4  BADENDARG
Bad argument to .END directive.

   Error: The optional argument to the .END directive is invalid.

   User Action: If you specify the argument, it must reference a
   procedure descriptor within the module. Specify a valid procedure
   descriptor name or omit the argument.
 

4  BADINSARG
Argument N is invalid for this instruction.

   Error: The argument number shown is invalid for the instruction.

   User Action: Check the argument and required format as specified
   in the documentation.
 

4  BADLIB
Error opening library file XXXXX.

   Error: The assembler encountered an error when attempting to open
   the indicated library file.

   User Action: Check the file format and file protections.
 

4  BADMACPARAMNAME
Illegal macro parameter name.

   Error: The indicated macro parameter name is illegal.

   User Action: Examine your source code and see Chapter 1 in the
   Reference Manual for information about valid parameter names.
 

4  BADMACRONAME
Illegal macro name.

   Error: The indicated macro name is illegal.

   User Action: Check your source code and see Chapter 2 in the
   Reference Manual for information about valid macro names.
 

4  BADOPERAND
Invalid operand type for operator.

   Error: The resolved operand type is invalid for the specified
   operator.

   User Action: See Chapter 2 in the Reference Manual for
   descriptions of operators, operands, and expressions.
 

4  BADPARAMSTR
Illegal parameter string.

   Error: The string specified as a macro parameter is invalid.

   User Action: Examine your source code and see Chapter 1 in the
   Reference Manual for information about valid parameter names.
 

4  BADSYSCALL
Internal error. Bad system call.

   Error: The assembler encountered an unexpected internal error
   when performing a system call.

   User Action: Report the problem to Digital.
 

4  BASEFAIL
Argument N is invalid. The assembler failed to find a base register
specified with a previous .BASE directive to form a register
expression of the form offset(Rn).

   Error: The assembler could not find a base register, which
   you specified with a previous .BASE directive, to form a valid
   register expression of the form offset(Rn).

   User Action: Check the instruction in the source code and see the
   description of the .BASE directive.
 

4  BASERANGE
Argument N invalid. The assembler attempted to use base register Rn
to form a register expression of the form offset(Rn). However, the
argument offset exceeds the allowable range of -32,768 to +32,767.

   Error: The assembler attempted to use a base register, which
   you specified with a previous .BASE directive, to form a valid
   register expression of the form offset(Rn). This attempt failed
   because the specified argument offset exceeded the valid range of
   the base register offset (_32,768 to +32,767). The register cited
   in the message represents the register that produced an offset
   closest to the range of -32,768 to +32,767.

   User Action: Check the instruction in the source code and see
   description of the .BASE directive.
 

4  BEGEXPSC
.BEGIN_EXACT is invalid in a psect with the NOEXE and NOMIX
attributes.

   Error: A .BEGIN_EXACT directive is not valid in a psect with the
   NOEXE and NOMIX attributes.

   User Action: Check your source code.
 

4  BYTEALIGNIGN
The BYTE_ALIGN option has been replaced by the ALIGN_DATA option.

   Error: The BYTE_ALIGN option has been replaced by the ALIGN_DATA
   option.

   User Action: Use the recommended new option.
 

4  CONPSECTATTR
Contradictory PSECT attribute.

   Error: A previously specified psect attribute conflicts with the
   flagged psect attribute.

   User Action: See the description of the .PSECT directive and
   psect attributes.
 

4  CONTEOF
Assembler encountered end of file after line continuation.

   Error: The assembler encountered end of file after a line that
   specified a continuation.

   User Action: Check your source code.
 

4  DATAALIGNTOBIG
Data requires alignment too large for PSECT.

   Error: The alignment required for a specified data item is too
   large for the psect.

   User Action: Check the psect attributes to insure that the psect
   alignment is greater than or equal to the required alignment of
   the data items. See the description of the .PSECT directive and
   psect attributes.
 

4  DATANOTINNOEXE
Data declarations must be in a psect with the MIX or NOEXE
attribute.

   Error: A data declaration, such as a data-storage directive, has
   been specified in a psect with incorrect psect attributes.

   User Action: Make sure the psect has the MIX or NOEXE attribute
   set. See the description of the .PSECT directive and psect
   attributes.
 

4  DIRNOTINNOEXE
Directive must be in a psect with the MIX or NOEXE attribute.

   Error: The directive you specify must appear in a psect with the
   MIX or NOEXE attribute set.

   User Action: Make sure you specify a psect with the MIX or NOEXE
   attribute set. See the description of the .PSECT directive and
   psect attributes.
 

4  DISPTOOLGE
Branch offset is too large for this instruction.

   Error: The offset you specified is too large for this
   instruction.

   User Action: Check the range of the specified target to insure it
   falls between -1048576 . . . +1048575, inclusive.
 

4  DUPLEXTERN
External item has multiple definitions.

   Error: The item you declared as externally defined with the
   .EXTERNAL attribute has another conflicting definition within
   this assembly unit.

   User Action: Check the definitions for the specified item.
 

4  DUPLGLOBAL
Duplicate global name.

   Warning: The assember detected a duplicate global name.

   User Action: Check all references in your source code to this
   name.
 

4  DUPMACPARAMNAME
Duplicate macro parameter name.

   Error: The assembler detected a duplicate macro parameter name.

   User Action: Check your source code.
 

4  ENDEXPSC
.END_EXACT is invalid in a psect with the NOEXE and NOMIX
attributes.

   Error: A .END_EXACT directive is not valid in a psect with the
   NOEXE and NOMIX attributes.

   User Action: Check your source code.
 

4  EOLEXP
Assembler expected an end of line.

   Error: The assembler expected no more input from the current
   line.

   User Action: Check your source code.
 

4  ESCAPE
Illegal escape sequence in string literal; assembler expected \, ",
x, or X.

   Error: The escape sequence you specified in the string literal is
   illegal.

   User Action: Check your source code.
 

4  EXP32BITTRUNC
Assembler expected an integer in the range 0 . . . (2^32)-1 for
an unsigned expression OR -(2^31) . . . +(2^31)-1 for a signed
expression. Data truncation to 32 bits.

   Warning: The assembler found an integer that was not within the
   expected range.

   User Action: Check your source code. The literal must be within
   the range of 0 . . . (2^32)-1 for an unsigned expression OR
   -(2^31) . . . +(2^31)-1 for a signed expression. Data truncation
   to 32 bits occurs.
 

4  EXP32BITTYPE
Assembler expected an integer in the range 0 . . . (2^32)-1 for
unsigned expression OR -(2^31) . . . +(2^31)-1 for signed expression.

   Error: The assembler expected an unsigned integer value within
   the range of 0 . . . (2^32)-1 or a signed integer value within in
   the range of -(2^31) . . . +(2^31)-1.

   User Action: Check your source code.
 

4  EXPBINEXPTERM
Assembler found XXXXX when expecting a binary operator or expression
terminator.

   Error: The assembler expected a binary operator, such as the plus
   sign (+)  for binary addition, or an item to end the expression,
   such as the right-angle bracket (>).

   User Action: Check the flagged item in the source statement.
 

4  EXPFPREG
Argument N is invalid. Assembler expected a floating point register.

   Error: The instruction argument cited is invalid. The assembler
   expected a floating-point register.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPGENREG
Argument N is invalid. Assembler expected a general register.

   Error: The instruction argument cited is invalid. The assembler
   expected a general register.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPIDPROC
Argument N is invalid. Assembler expected an identifier representing
a procedure value.

   Error: The argument cited is invalid. The assembler expected a
   user identifier that represents a procedure value.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPINTPAL
Assembler expected an integer expression or PAL opcode.

   Error: Integer expession or PAL opcode missing.

   User Action: Replace the flagged item with an integer or PAL
   opcode.
 

4  EXPLAB
Argument N is invalid. Assembler expected a label defined in the
same psect.

   Error: The cited argument is invalid. The assembler expected a
   label definition to occur in the same psect as its reference.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPLITVAL
Argument N is invalid. Assembler expected an integer literal value
in the inclusive range 0 . . . 255.

   Error: The instruction argument cited is invalid. The assembler
   expected an integer literal within the range of 0 . . . 255.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPMACRONAME
Assembler expected a valid macro name.

   Error: The assembler expected a valid macro name in this context.

   User Action: Check your source code to insure that the item
   flagged is a user identifier, opcode, or nonmacro directive.
 

4  EXPPALOPLIT
Argument N is invalid. Assembler expected an integer literal value
in the inclusive range 0 . . . 67108863.

   Error: The instruction argument cited is invalid. The assembler
   expected an integer literal.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPREGOFF
Argument N is invalid. Assembler expected a general register
expression of the form offset(Rn).

   Error: The cited argument is invalid. The assembler expected a
   general register expression of the form integer_offset(Rn) for
   this argument.

   User Action: Check the source code and the instruction
   documentation.
 

4  EXPRESEXP
Argument N is invalid. Assembler expected an expression with no
forward references resolvable to psect +/- offset.

   Error: The argument cited is invalid. The assembler expected an
   expression with no forward references.

   User Action: Check your source code and the instruction
   documentation.
 

4  EXPSTACKOVER
Internal SEM expression stack overflow.

   Fatal: An internal error has occurred.

   User Action: Gather as much information as possible about the
   circumstances under which the error occurred and report the
   problem to Digital.
 

4  EXPTOOCMPLX
Expression is too complex to evaluate.

   Error: The expression is too complex for the assembler to
   evaluate.

   User Action: Try grouping the expression components using angle
   brackets (< >). The most complex expression form handled by
   the assembler resolves to the form: <psect/symbol +/- offset>
   OPERATOR <psect/symbol +/- offset>, where OPERATOR is one of: +,
   -, *, /, @, \, &, or !. See Chapter 2 in the Reference Manual for
   further descriptions of the assembler evaluation of expressions.
 

4  EXPZEROFF
Argument N is invalid. Assembler expected a general register
expression of the form 0(Rn) or (Rn).

   Error: The cited argument is invalid. The assembler expected a
   general register expression of the form 0(Rn).

   User Action: Check your source code and see Chapter 2 in
   the Reference Manual for information about general register
   expressions.
 

4  FOUNDEXP
Assembler found XXXXX when expecting one of the following: XXXXX.

   Error: The assembler found an unexpected item in a location where
   it expected something else.

   User Action: Check the unexpected item found in the source
   statement. Examine those items cited as expected as alternatives
   for the unexpected item.
 

4  FREGDEF
You cannot define a floating-point register in terms of an integer
register.

   Warning: You are attempting to define a floating-point register
   symbol in terms of an integer register.

   User Action: Specify either a floating-point register or an
   expression within the range of 0 to 31 with the .DEFINE_FREG
   directive. See the description of the .DEFINE_FREG directive.
 

4  GENERROR
Generated ERROR:

   Error: This statement was generated using the .ERROR directive.

   User Action: Examine your source code.
 

4  GENPRINT
Generated PRINT:

   Informational: This statement was generated using the .PRINT
   directive.

   User Action: Examine your source code.
 

4  GENWARN
Generated WARNING:

   Warning: This statement was generated using the .WARNING
   directive.

   User Action: Examine your source code.
 

4  HEXSTR
Illegal hexadecimal escape sequence in string literal.

   Error: The specified hexadecimal escape sequence is invalid.

   User Action: Check your source code and the documentation.
 

4  IDENTTRUNC
The string length of the module IDENT is greater than 31 characters.
It is truncated to 31 characters.

   Warning: The string argument you specified with the .IDENT
   directive is too long.

   User Action: Specify a shorter string argument. See the
   description of the .IDENT directive.
 

4  IDFOUND
Assembler found identifier in the opcode field when expecting one
of the following: opcode, directive, macro invocation, or symbol
definition.

   Error: The identifier cited was unexpected. The assembler
   expected either an opcode, a directive, a macro invocation, or
   a symbol definition.

   User Action: Check your source code.
 

4  IDTOOLONG
Identifier is longer than 31 characters.

   Error: The identifier exceeds the 31 character maximum size.

   User Action: Check your source code and either rename or truncate
   the identifier.
 

4  ILLASCII
Illegal ASCII constant.

   Error: The assembler found an illegal ASCII constant with the 6A
   or ^a radix specifier.

   User Action: Check your source code.
 

4  ILLBIN
Illegal binary constant.

   Error: The assembler found an illegal binary constant with the ^B
   or ^b radix specifier.

   User Action: Check your source code.
 

4  ILLDEC
Illegal decimal constant.

   Error: The assembler found an illegal binary constant with the ^D
   or ^d radix specifier.

   User Action: Check your source code.
 

4  ILLEXPON
Illegal exponent in floating-point constant.

   Error: The specified exponent of the floating-point constant is
   illegal.

   User Action: Check your source code and see Chapter 5 in the
   Reference Manual for information about floating-point constants.
 

4  ILLFLOAT
Illegal floating-point constant.

   Error: The specified floating-point constant is illegal.

   User Action: Check your source code and see Chapter 5 in the
   Reference Manual for information about floating-point constants.
 

4  ILLHEX
Illegal hexadecimal constant.

   Error: The assembler found an illegal binary constant with the ^X
   or ^x radix specifier.

   User Action: Check your source code.
 

4  ILLIFOP
Illegal .IF operator.

   Error: An illegal operator was encountered as an .IF operator.

   User Action: Check your source code and see the description of
   the .IF directive.
 

4  ILLINCL
Illegal .INCLUDE file specification.

   Error: The assembler encountered an illegal .INCLUDE directive.

   User Action: Check your source code and see the description of
   the .INCLUDE directive.
 

4  ILLOCT
Illegal octal constant.

   Error: The assembler found an illegal binary constant with the ^O
   or ^o radix specifier.

   User Action: Check your source code.
 

4  ILLOPERANDMIX
Illegal operand mixing for operator.

   Error: The resolved operand types are invalid when used together
   with the specified operator.

   User Action: See Chapter 2 in the Reference Manual for
   descriptions of operators, operands, and expressions.
 

4  ILLPROCRET
Illegal procedure return; linkage register (argument 1) must be R31
when software hint (argument 3) is 1.

   Error: Illegal procedure return.

   User Action: Check the instruction arguments. When argument 3,
   software hint, is 1, the first argument specifying the linkage
   register must be R31.
 

4  ILLRADIX
Illegal radix specifier in numeric constant; specify A, B, C, D, O,
or X.

   Error: The assembler found an illegal radix specifier.

   User Action: Check your source code and use one of A, B, C, D, O,
   or X.
 

4  INCLDEPTH
.INCLUDE nest depth exceeds N - check for circular .INCLUDE.

   Error: The assembler attempted to exceed the maximum level of
   include file depth.

   User Action: Check your source code for circular file inclusion.
 

4  INCLOPEN
.INCLUDE file open error.

   Error: The assembler could not open the included file.

   User Action: Check the file attributes and so forth of the
   specified .INCLUDE file.
 

4  INSNOTINPSC
Instructions must be in a MIX, NOEXE; MIX, EXE; or NOMIX, EXE PSECT.

   Error: You specified an instruction in a psect with incorrect
   psect attributes.

   User Action: Make sure the psect has MIX or EXE and NOMIX
   attributes set.
 

4  INTERNAL
Internal assembler error. Please report the problem to Digital.

   Fatal: An internal error has occurred.

   User Action: Gather as much information as possible about the
   circumstances under which the error occurred and report the
   problem to Digital.
 

4  INTERR
Internal processing error in the SYN facility. Please report the
problem to Digital.

   Fatal: An internal error has occurred.

   User Action: Gather as much information as possible about the
   circumstances under which the error occurred and report the
   problem to Digital.
 

4  INVALIGNFILL
You specified an invalid optional fill pattern with the .ALIGN
directive.

   Error: You specified an invalid optional fill pattern.

   User Action: Check your source code, in particular the second
   argument to the .ALIGN directive, the alignment fill specifier,
   to insure that it resolves to an integer. See the description of
   the .ALIGN directive.
 

4  INVBASEEXP
Invalid expression for .BASE directive.

   Error: The expression is not valid for .BASE directive.

   User Action: The expression you specified for a base register
   with the .BASE directive should contain no forward references and
   resolve to one of the following at this point in assembly: psect
   +/- offset, external symbol reference +/- offset, integer, label
   +/- offset, where the label is defined in a psect with the EXE
   and NOMIX attributes. See Chapter 5 in the Reference Manual for
   more information about the assembler evaluation of expressions.
 

4  INVBASEREG
Invalid base register. Base register must be one of R0 through R30.

   Error: You specified an invalid base register.

   User Action: Specify a base register as a general register from
   the range of R0 . . . R30. R31 cannot be specified as a base
   register and is implicitly defined as .BASE R31, 0.
 

4  INVBRTGT
Invalid branch target. Branch target label must be defined in same
psect as the branch instruction which references the label.

   Error: The specified label you reference as the target of a
   branch instruction must be defined in the same psect in which
   it is referenced.

   User Action: See Chapter 4 in the Reference Manual for more
   information about labels.
 

4  INVCA
You specified an invalid code address with the procedure descriptor.
The code address must be a nontemporary label defined in a psect
with the EXE or MIX attribute after its use with .PROCEDURE_
DESCRIPTOR.

   Error: The code address you specified as the second argument to
   the .PROCEDURE_DESCRIPTOR directive is invalid.

   User Action: The code address must be a non-temporary label
   defined in a psect with the EXE or NOMIX attribute. Check your
   source code.
 

4  INVEXP
Assembler found XXXXX when expecting a valid expression.

   Error: The assembler expected one of the following: integer,
   floating-point constant, identifier, register, period (.),  left-
   angle bracket (<),  or unary operator.

   User Action: Check the unexpected item found in the source
   statement.
 

4  INVEXPRFORDIR
Invalid expression type for directive.

   Error: The assembler resolved value for the expression in the
   cited directive is invalid.

   User Action: See Chapters 1 and 5 in the Reference Manual for
   more information about the directive arguments and types.
 

4  INVEXPRFORSYM
Invalid expression type for symbol.

   Error: The assembler resolved value for the expression that is
   assigned to a local or global symbol is invalid.

   User Action: Expressions assigned to a symbol must contain no
   forward references and must resolve to an integer or psect
   /label +/- offset. See Chapter 2 in the Reference Manual for
   more information about how the assembler determines symbol and
   expression values.
 

4  INVFPCONST
Invalid floating-point value. Check value range for floating-point
data type.

   Error: The assembler detected an invalid floating-point value.

   User Action: Check the specified range for the directive type.
 

4  INVINSQUAL
You specified an invalid instruction qualifier list for the opcode.

   Error: The instruction qualifier you specified with the opcode is
   invalid.

   User Action: See Appendix A in the Reference Manual for a
   complete list of opcodes and valid instruction qualifiers.
 

4  INVLCA
Assembler found an invalid or undefined code address for the
procedure descriptor.

   Error: An invalid or undefined code address corresponds to the
   specified procedure descriptor.

   User Action: Check your source code for the specified code
   address.
 

4  INVLISTOPT
You specified an invalid option with the .LIST or .SHOW directive.

   Error: You specified an invalid option with the .LIST or .SHOW
   directive.

   User Action: See the descriptions of the .LIST and .SHOW
   directives for valid .LIST and .SHOW options.
 

4  INVLPD
Invalid procedure descriptor.

   Error: You specified an invalid procedure descriptor. There was
   no definition of a procedure descriptor by the specified name.

   User Action: Check your source code.
 

4  INVNLISTOPT
You specified an invalid option with the .NLIST or .NOSHOW
directive.

   Error: You specified an invalid option with the .NLIST or .NO_
   SHOW directive.

   User Action: See the descriptions of the .NLIST and .NO_SHOW
   directives for valid .NLIST and .NO_SHOW options.
 

4  INVOFF
You attempted to specify data intialization with a current psect
offset that is outside the range of 0 to 2147483647.

   Error: The current psect offset is invalid for specifying a data
   initialization.

   User Action: Check your source code and the value of the current
   psect offset.
 

4  INVREGNUMEXP
Invalid register-number expression. Specify an integer expression
between 0 and 31 or a previously defined or predefined register.

   Error: You specified an illegal expression for a register symbol
   definition.

   User Action: Specify a value between 0 and 31. You can also
   define a register in terms of a previously-defined or predefined
   register.
 

4  INVREPCOUNT
The integer value of the .REPEAT expression is not within the
inclusive range of 0 . . . 65535. A 0 value is assumed.

   Warning: The value of the .REPEAT expression must be within the
   range of 0 . . . 65,535, inclusive. Therefore, a 0 expression
   value is assumed.

   User Action: Specify a repetition count between 0 and 65,535,
   inclusive.
 

4  INVSAVEOPT
You specified an invalid option with the .SAVE_PSECT directive.

   Error: You specified an invalid option with the .SAVE_PSECT
   directive.

   User Action: See the description of the .SAVE_PSECT directive for
   valid .SAVE_PSECT options.
 

4  INVTEMPLAB
Invalid use of temporary label.

   Error: A temporary label reference is not allowed in this
   context.

   User Action: See Chapter 2 in the Reference Manual for
   information about using temporary labels.
 

4  INVTERM
Assembler found N when expecting a valid expression term.

   Error: The assembler found an unexpected item where it expected
   one of the following expressions: floating-point number, integer,
   register, decimal point (.),  identifier, or left-angle bracket
   (<).

   User Action: Check the item flagged by the assembler.
 

4  IREGDEF
You cannot define an integer register in terms of a floating-point
register.

   Warning: You are attempting to define an integer register symbol
   in terms of a floating-point register. IREGDEF

   User Action: Specify either an integer register or an expression
   within the range of 0 to 31 with the .DEFINE_IREG directive.
 

4  LABELNOTDEF
Undefined label.

   Error: The label you specified is undefined.

   User Action: See Chapters 2 and 4 for descriptions of the valid
   labels.
 

4  LABELREDECL
Illegal redefinition of label.

   Error: You have illegally defined this label in multiple places
   in this assembly unit.

   User Action: Check all references to this label in your source
   code.
 

4  LABNOTINPSECT
Label must be declared in a PSECT.

   Error: You are attempting to declare a temporary, local, or
   global label without first establishing a psect.

   User Action: Make sure you enter the appropriate .PSECT directive
   before declaring the label in your source stream.
 

4  LEXOPEDITSPEC
Unrecognized edit specifier.

   Error: The assembler does not recognize the edit specifier for
   the %EDIT lexical operator.

   User Action: Check your source code and see the description of
   the %EDIT lexical operator.
 

4  LEXOPENDM
Illegal modification of .ENDM directive keyword by lexical
operation.

   Error: While your macro definition contains a .ENDM directive
   that ends the macro definition, the .ENDM directive is modified
   by a lexical operator so that it can no longer be recognized as a
   .ENDM directive keyword after lexical processing.

   User Action: Change the statement to avoid modifying the .ENDM
   directive keyword with lexical operator processing. See Chapter
   3 in the Reference Manual for information about using lexical
   operators.
 

4  LEXOPENDR
Illegal modification of .ENDR directive keyword by lexical
operation.

   Error: While your repeat range contains a .ENDR directive that
   ends the repeat block, the .ENDR directive is modified by a
   lexical operator so that it can no longer be recognized as a
   .ENDR directive keyword after lexical processing.

   User Action: Change the statement to avoid modifying the .ENDR
   directive keyword with lexical operator processing. See Chapter
   3 in the Reference Manual for information about using lexical
   operators.
 

4  LEXOPSYNTAX
Illegal lexical operator syntax (missing left or right parenthesis,
missing comma, or other lexical operator syntax error).

   Error: The indicated lexical operator has a syntax error.

   User Action: Check the source code to insure correct syntax.
 

4  LEXSYM
XXXXX is already a lexical string symbol name; it cannot also be a
numeric symbol name.

   Error: You cannot define a lexical string symbol and a numeric
   symbol by the same name.

   User Action: Check your source code and remove either the lexical
   string or the numeric symbol definition.
 

4  LIBMOD_BADFORMAT
Library module XXXXX contains illegal syntax (missing .MACRO or
label preceding .MACRO, missing or not matching .ENDM, or other
macro syntax error).

   Error: The assembler encountered illegal syntax.

   User Action: Check the syntax of the macro.
 

4  LIBMOD_EMPTY
Library module XXXXX is empty.

   Warning: The assembler encountered an empty library module.

   User Action: Replace the library module.
 

4  LIBMOD_EXTRA
Library module XXXXX contains extraneous text after .ENDM; the
assembler ignores the extra text.

   Warning: The assembler encountered extraneous text after an .ENDM
   directive in a library module. The assembler ignores this text.

   User Action: Correct the library module.
 

4  LIBMOD_NOT_FOUND
Library module XXXXX not found.

   Error: The assembler could not find the indicated library module.

   User Action: Check the spelling of the macro library and module
   names.
 

4  LOCCTRNOTDATA
Location counter cannot be set in a psect with the EXE and NOMIX
attributes.

   Error: You cannot modify the location counter in a psect with the
   EXE and NOMIX attributes.

   User Action: If you need to modify the location counter, specify
   the MIX psect attribute. See Chapter 5 iin the Reference Manual
   for a description of the MIX psect attribute.
 

4  MACCASEMATCH
Library macro name is spelled using different alphabetic case than
in .MCALL directive or macro invocation.

   Error: There is an alphabetic case difference between that
   specified in the macro library and what you specified for the
   macro name.

   User Action: Check the case of the macro name in your source code
   and the case of the macro in the specified macro library.
 

4  MACEXPNEST
Macro expansion exceeds maximum nesting depth (macro recursion not
detected).

   Error: The macro is not recursive but exceeds the maximum
   allowable expansion depth.

   User Action: Check your source code for possible restructuring.
 

4  MACPARAMGENDEF
You can specify a generated label default value or a default string
value, but not both.

   Error: You specified both a default string value and a generated
   label default value when you can only specify one.

   User Action: Examine your source code.
 

4  MACPARAMSYNTAX
Illegal macro parameter syntax. Assembler found XXXXX when expecting
one of XXXXX.

   Error: Macro parameter syntax is invalid.

   User Action: Try replacing the unexpected argument with one of
   those items cited as expected.
 

4  MACRECURSE
Recursive macro exceeds maximum macro expansion nesting depth.

   Error: The macro is recursive and exceeds the maximum expansion
   nesting depth.

   User Action: Check your source code for a missing basis step in
   the recursive macro.
 

4  MACZERO
Assembler cannot evaluate expression. A 0 expression value is
assumed.

   Informational: The assembler cannot evaluate this expression due
   to errors it encountered. Therefore, a 0 value is assumed.

   User Action: Check the expression for forward or external
   references.
 

4  MAXIF
Maximum nesting of .IF directives exceeded.

   Error: The maximum depth nesting of .IF directives has been
   exceeded.

   User Action: Check your source code for possible restructuring.
 

4  MAXLEXOP
More than N lexical operators encountered; check for a recursive
lexical string symbol.

   Error: Your source line contains an excessive number of lexical
   operators. A recursive lexical string symbol definition occurs
   when you initially define a lexical string symbol in terms
   of itself using the lexical substitution operator. While the
   assembler normally interprets lexical substitution operators
   during lexical string symbol definition, it cannot in this case
   because the lexical string symbol is not yet defined. When the
   assembler later expands such a lexical string symbol with the
   imbedded self reference, infinite recursion results.

   User Action: Check your source code for recursive lexical string
   symbol definitions and redefine them to avoid recursion.
 

4  MISSENDC
Missing .ENDC directive(s).

   Warning: The assembler could not find a terminating .ENDC
   conditional directive.

   User Action: Check your source code.
 

4  MISSINGENDM
Missing .ENDM directive.

   Error: The assembler could not find a terminating .ENDM directive
   to match a .MACRO directive.

   User Action: Check your source code.
 

4  MISSINGENDR
Missing .ENDR directive.

   Error: The assembler could not find an .ENDR directive to
   terminate an .IRP or a.REPEAT block.

   User Action: Check your source code.
 

4  MISSQUOTE
Missing closing double-quote character in string literal.

   Error: The closing double-quote is missing from the string
   literal.

   User Action: Check your source code and insert a closing double-
   quote for a string literal.
 

4  MODCODLOCCTR
Restoring the location counter in the current context causes an
illegal modification of the location counter for a psect with the
EXE and NOMIX attributes.

   Error: You cannot modify the location counter in a psect with the
   EXE and NOMIX attributes.

   User Action: If you need to modify the location counter, specify
   the MIX psect attribute. See Chapter 5 in the Reference Manual
   for a description of the MIX psect attribute.
 

4  NOBEGEX
Assembler encountered an unmatched .END_EXACT directive.

   Error: The assembler encountered an .END_EXACT directive before a
   .BEGIN_EXACT directive.

   User Action: Check your source code.
 

4  NOCA
You did not specify a code address as argument 2 with
.PROCEDURE_DESCRIPTOR.

   Error: You did not specify a code address as the second argument
   to the .PROCEDURE_DESCRIPTOR directive.

   User Action: The code address must be a nontemporary label
   defined in a psect with the EXE or NOMIX attribute. Check your
   source code.
 

4  NOQUAL
Instruction qualifiers are invalid with this opcode.

   Error: You cannot specify instruction qualifiers with this
   opcode.

   User Action: See Appendix A in the Reference Manual for a
   complete list of opcodes and valid instruction qualifiers.
 

4  NOTAQUAL
An item you specified in the qualifier list is invalid with this
opcode.

   Error: The instruction qualifier you specified with the opcode is
   invalid.

   User Action: See Appendix A in the Reference Manual for a
   complete list of opcodes and valid instruction qualifiers.
 

4  NOTENOUGHARGS
Not enough arguments for instruction.

   Error: The instruction needs one or more additional arguments.

   User Action: Check the argument numbers and required formats as
   specified in Chapter 5 in the Reference Manual.
 

4  NOTINMACRO
This statement must occur only within a macro.

   Error: The statement you specified is only allowed within a
   macro.

   User Action: See Chapter 2 in the Reference Manual for a
   description of the statement specified.
 

4  NOTINSEM
Missing functionality in SEM.

   Error: This functionality is missing in the assembler.

   User Action: Please report the problem to Digital.
 

4  NUMSYM
XXXXX is already a numeric symbol name; it cannot also be a lexical
string symbol name.

   Error: You cannot define a numeric symbol and a lexical string
   symbol by the same name.

   User Action: Check your source code and remove either the numeric
   or the lexical string symbol definition.
 

4  OPTIGN
The assembler is ignoring one or more VAX MACRO options.

   Informational: The assembler detected and ignored a VAX MACRO
   option.

   User Action: Remove the VAX MACRO options from your MACRO-64
   Assembler for OpenVMS Alpha Systems program.
 

4  OVERLAP
Assembler detected overlapping initializers at offset NN. This
initial value overlaps but is not an exact replacement for a
previous initial value.

   Error: You are trying to assign or initialize multiple values to
   the same location. This is not allowed.

   User Action: Check your source code.
 

4  PSECTALIGNCON
PSECT alignment conflicts with earlier declaration.

   Error: A previously specified psect alignment attribute conflicts
   with the flagged psect attribute.

   User Action: Check all declarations of the psect. See the
   description of the .PSECT directive and psect attributes.
 

4  PSECTATTRCON
PSECT attribute conflicts with earlier declaration.

   Error: A previously specified psect attribute conflicts with the
   flagged psect attribute.

   User Action: Check all declarations of the psect. See the
   description of the .PSECT directive and psect attributes.
 

4  REGREDEF
You attempted to redefine a previously defined register symbol with
a different value.

   Warning: You are attempting to change the definition of a
   register symbol that either you have previously defined or that
   MACRO-64 has predefined.

   User Action: Check for conflicts with the register-symbol
   identifier you have specified. If you wish to redefine a register
   symbol, you must first cancel its previous definition with the
   .UNDEFINE_REG directive.
 

4  REDUNDELSE
You cannot specify more than one .ELSE directive within a single .IF
block.

   Error: The assembler encountered more than one .ELSE directive
   within a single .IF block.

   User Action: Check your source code.
 

4  RESTOREWOSAVE
PSECT .RESTORE without .SAVE.

   Error: You entered a .RESTORE_PSECT directive without a previous
   corresponding .SAVE_PSECT directive.

   User Action: Check the uses of .SAVE_PSECT and .RESTORE_PSECT in
   your source code.
 

4  SAVESTACKOVER
Internal SEM PSECT .SAVE stack overflow.

   Fatal: An internal error has occurred.

   User Action: Gather as much information as possible about the
   circumstances under which the error occurred and report the
   problem to Digital.
 

4  SRCREAD
Error reading source file.

   Error: The assembler encountered an error in reading your source
   file.

   User Action: Check file specifications, protections, and so
   forth.
 

4  SYMBOLREDECL
Illegal redefinition of symbol.

   Error: The symbol is already defined as a label or explicitly
   declared as externally defined with the .EXTERNAL directive.

   User Action: Check all uses of this symbol.
 

4  TOOMANYARGS
Too many arguments for instruction.

   Error: The instruction contains one or more arguments than
   necessary.

   User Action: Check the argument numbers and required formats as
   specified in Chapter 5 in the Reference Manual.
 

4  TOOMANYMACARG
You specified more arguments than are defined for this macro.

   Error: You specified more arguments on the macro call than were
   specified for its definition.

   User Action: Check the macro definition and point of call in your
   source code.
 

4  TOOMANYMACPARAMS
Too many macro parameters.

   Error: You specified too many macro parameters.

   User Action: Check your source code.
 

4  TRUNCDATA
Data truncation warning.

   Warning: You specified a data value that is out of range for the
   specified directive, which results in data truncation.

   User Action: Specify a smaller value.
 

4  UNDCA
You specified an undefined code address with the procedure
descriptor.

   Error: The code address you specified as the second argument to
   the .PROCEDURE_DESCRIPTOR directive is undefined.

   User Action: The code address must be a nontemporary label
   defined in a psect with the EXE or NOMIX attribute. Check your
   source code.
 

4  UNDEFSYM
Undefined symbol or label. Assembler assumes an .EXTERNAL
definition.

   Warning: The referenced label or symbol does not have an explicit
   definition and an external definition is assumed.

   User Action: Use the .EXTERNAL directive to declare the symbol.
 

4  UNEXPELSE
Unexpected .ELSE directive.

   Error: The assembler encountered an unexpected .ELSE directive.

   User Action: Check the use of the .ELSE directive in your source
   code to insure proper positioning with a .IF and .ENDC directive.
 

4  UNEXPENDC
Unexpected .ENDC directive.

   Error: The assembler could not find a terminating .ENDC for a
   macro conditional directive, such as .IF.

   User Action: Check your source code.
 

4  UNEXPENDM
Unexpected .ENDM directive.

   Error: The assembler encountered an unexpected .ENDM directive.

   User Action: Check your source code for matching .MACRO/.ENDM
   pairs.
 

4  UNEXPENDR
Unexpected .ENDR directive.

   Error: The assembler encountered an unexpected .ENDR directive.

   User Action: Check your source code for matching .REPEAT/.ENDR
   and .IRP/.ENDR directive pairs.
 

4  UNEXPIFF
Unexpected .IF_FALSE (.IFF) directive.

   Error: The assembler encountered an unexpected .IF_FALSE
   directive.

   User Action: Check your source code to insure that this directive
   occurs within an .IF block.
 

4  UNEXPIFT
Unexpected .IF_TRUE (.IFT) directive.

   Error: The assembler encountered an unexpected .IF_TRUE
   directive.

   User Action: Check your source code to insure that this directive
   occurs within an .IF block.
 

4  UNEXPIFTF
Unexpected .IF_TRUE_FALSE (.IFTF) directive.

   Error: The assembler encountered an unexpected .IF_TRUE_FALSE
   directive.

   User Action: Check your source code to insure that this directive
   occurs within an .IF block.
 

4  UNEXPMEXIT
Unexpected .MEXIT directive.

   Error: The assembler encountered an unexpected .MEXIT directive.

   User Action: Check your source code.
 

4  UNKDIR
Assembler found unknown directive XXXXX.

   Error: An internal error has occured.

   User Action: Gather as much information as possible about the
   circumstances under which the error occurred and report the
   problem to Digital.
 

4  UNKENDISOPTION
You specified an unknown .ENABLE/.DISABLE option.

   Error: The option you specified for .ENABLE/.DISABLE is
   incorrect.

   User Action: Check the option specified with the .ENABLE/.DISABLE
   directive.
 

4  UNKNOWNATTR
Unknown PSECT attribute.

   Error: The assembler does not recognize the specified psect
   attribute.

   User Action: See the description of the .PSECT directive and
   psect attributes.
 

4  UNTERMEX
Assembler detected N unterminated .BEGIN_EXACT directive(s) in psect
XXXXX.

   Error: Unmatched .BEGIN_EXACT directive(s) occur for the
   indicated psect.

   User Action: Check your source code.
 

4  VAXDIR
The assembler is ignoring one or more VAX MACRO directives or
options. Assembler continues processing with the next line.

   Informational: The assembler detected and ignored a VAX MACRO
   directive or option.

   User Action: Remove the VAX MACRO directives from your MACRO-64
   Assembler for OpenVMS Alpha Systems program.
 

4  VMACELSE
You cannot specify .ELSE in the same .IF block with either .IF_FALSE
(.IFF), .IF_TRUE (.IFT), or .IF_TRUE_FALSE (.IFTF).

   Error: The assembler encountered an .ELSE directive within the
   same .IF block as an .IF_FALSE, .IF_TRUE, or .IF_FALSE directive.

   User Action: Check your source code and remove either the .ELSE
   directive or the .IF_x directive.
 

4  WRONGMACID
Macro name in .ENDM does not match corresponding .MACRO.

   Error: The macro name you specified as the optional argument to
   the .ENDM directive does not match the name you specified with
   the corresponding .MACRO directive.

   User Action: Check your souce code for matching .MACRO/.ENDM
   directive pairs.
 

4  WRONGPL
The code address you specify with the .PROCEDURE_DESCRIPTOR
directive must occur BEFORE its definition as a local or global
label.

   Error: The code address you specify as the second argument to the
   .PROCEDURE_DESCRIPTOR directive must occur before its definition
   as a nontemporary label defined in a psect with the EXE or NOMIX
   attribute.

   User Action: Check your source code.
 

3  Example_Location
   When you install MACRO-64 from the Freeware CD, a number of 
   MACRO-64 examples are placed in the SYS$EXAMPLES directory.
   To find these examples, enter the following command at the
   DCL prompt:

   $ DIRECTORY SYS$EXAMPLES:MACRO64$*.M64

   Each example contains comments that tell you what the example
   does, and how to assemble and run the example.
 

2  /MIGRATION
   The MACRO/MIGRATION command invokes the MACRO Compiler for
   OpenVMS Systems to compile one or more VAX MACRO assembly
   language source files into native OpenVMS Alpha object code.

   Format

     MACRO/MIGRATION  filespec[+...]
 

3  Parameters
 

filespec[+...]

   Specifies a VAX MACRO assembly language source file to be
   compiled. If you specify more than one file, separate the
   file specifications with plus signs (+).  File specifications
   separated by plus signs are concatenated into one input file and
   produce a single object file and, if indicated, a listing file.

                                  NOTE

      Unlike the VAX assembler, the MACRO compiler does not
      support the creation of separate object files when the
      source files are separated by a comma (,).

   You cannot include a wildcard character in a file specification.
   For each file specification, the compiler command supplies a
   default file type of MAR.

   The compiler creates output files of one version higher than the
   highest version existing in the target directory.
 

3  Description
   The qualifiers to the MACRO/MIGRATION command serve as either
   command (global) qualifiers or positional qualifiers. A command
   qualifier affects all the files specified in the command. A
   positional qualifier affects only the file that it qualifies.
   All MACRO/MIGRATION qualifiers except /LIBRARY are usable as
   either command or positional qualifiers. The /LIBRARY qualifier
   is a positional qualifier only.

   Many of the qualifiers take one or more arguments. If you specify
   only one argument, you can omit the parentheses.

   The compiler supports most of the standard MACRO qualifiers.
   Some of these qualifiers have additional options unique to the
   compiler and some of them are missing one or more VAX MACRO
   options. The compiler also supports several qualifiers unique to
   the compiler. All of these qualifiers are shown in the following
   table:

   Standard MACRO Qualifiers           Unique Qualifiers

   /DEBUG (with additional options)    /FLAG
   /DIAGNOSTICS                        /MACHINE
   /DISABLE (with additional options)  /OPTIMIZE
   /ENABLE (with additional options)   /PRESERVE
   /LIBRARY                            /RETRY_COUNT
   /LIST                               /SYMBOLS
   /OBJECT                             /TIE
   /SHOW                               /UNALIGNED
                                       /WARN
 

3  Qualifiers
 

/DEBUG

      /DEBUG=(option[,...])
      /NODEBUG

   Includes or excludes local symbols in the symbol table or
   traceback information in the object module. You can specify one
   or more of the following options:

   Option      Description

   ALL         Makes local symbols and traceback information in
               the object module available to the debugger. This
               qualifier is equivalent to /ENABLE=(DEBUG,TRACEBACK).

   NONE        Makes local symbols and traceback information
               in the object module unavailable to the
               debugger. This qualifier is equivalent to
               /DISABLE=(DEBUG,TRACEBACK).

   SYMBOLS     Makes all local symbols in the object module
               available and all traceback information unavailable
               to the debugger. This qualifier is equivalent to
               /ENABLE=SYMBOLS.

   TRACEBACK   Makes traceback information in the object module
               available and local symbols unavailable to
               the debugger. This qualifier is equivalent to
               /ENABLE=TRACEBACK.

   The default value for /DEBUG is ALL. The /DEBUG
   qualifier overrides /ENABLE=(DEBUG,TRACEBACK) or
   /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the
   command line.

                                  NOTE

      Debugging can be simplified by specifying /NOOPTIMIZE. This
      qualifier prevents the movement of generated code across
      source line boundaries.

   For more information about debugging, see the OpenVMS Debugger
   Manual.
 

/DIAGNOSTICS

      /DIAGNOSTICS[=filespec]
      /NODIAGNOSTICS (default)

   Creates a file containing assembler messages and diagnostic
   information. If you omit the file specification, the default file
   name is the same as the source program; the default file type is
   DIA.

   No wildcard characters are allowed in the file specification.

   The diagnostics file is reserved for use with layered products,
   such as the VAX Language-Sensitive Editor (LSE).
 

/DISABLE

      /DISABLE=(option[,...])
      /NODISABLE

   Provides initial settings for the compiler functions that can be
   controlled by the .DISABLE and .ENABLE MACRO directives.

   You can specify one or more of the following functions:

   Option      Description

   DEBUG       Excludes local symbol table information in
               the object file for use with the debugger.
               If the /DEBUG qualifier is also specified,
               it overrides /DISABLE=(DEBUG,TRACEBACK) or
               /ENABLE=(DEBUG,TRACEBACK), regardless of their order
               on the command line.

   FLAGGING    Deactivates compiler flagging.

   GLOBAL      Disables the assumption that undefined symbols are
               external symbols.

   OVERFLOW    Deactivates production of overflow trap code for the
               following opcodes: ADDx, ADWC, INCx, ADAWI, SUBx,
               SBWC, DECx, MNEGx, MULx, CVTxy, (where x is greater
               than y, for example CVTLB), AOBxx, ACBL, and SOBxx.

   QUADWORD    Disables support for quadword literal and address
               expressions.

   SUPPRESSION Prevents the listing of unreferenced symbols in the
               symbol table.

   TRACEBACK   Disables the provision of traceback information
               to the debugger. If the /DEBUG qualifier is also
               specified, it overrides /DISABLE=(DEBUG,TRACEBACK) or
               /ENABLE=(DEBUG,TRACEBACK), regardless of their order
               on the command line.

   By default, at compiler activation, FLAGGING, GLOBAL, and
   SUPPRESSION are enabled, and DEBUG, OVERFLOW, QUADWORD, and
   TRACEBACK are disabled.

   The /NODISABLE qualifier has the same effect as omitting the
   /DISABLE qualifier. It can also be used to negate the effects of
   any /DISABLE qualifiers specified earlier in the command line.

                                  NOTE

      If /DISABLE is used two or more times in the command line,
      the last /DISABLE will override all previous uses of
      /DISABLE. The options not specified in the final /DISABLE
      will revert to their default values.

      Furthermore, if /ENABLE and /DISABLE are used in the same
      command line for the same option, /DISABLE will always
      prevail, regardless of its position in the command line.

      Workaround: If you want to disable two or more options,
      specify them in the following way:

      /DISABLE=(xxxx, yyyy)
 

/ENABLE

      /ENABLE=(option[,...])
      /NOENABLE

   Provides initial settings for the compiler functions that can be
   controlled by the .DISABLE and .ENABLE MACRO directives.

   You can specify one or more of the following functions:

   Option      Description

   DEBUG       Includes local symbol table information in
               the object file for use with the debugger.
               If the /DEBUG qualifier is also specified,
               it overrides /ENABLE=(DEBUG,TRACEBACK) or
               /DISABLE=(DEBUG,TRACEBACK), regardless of their order
               on the command line.

   FLAGGING    Activates compiler flagging.

   GLOBAL      Assumes undefined symbols are external symbols.

   OVERFLOW    Activates production of overflow trap code for the
               following opcodes: ADDx, ADWC, INCx, ADAWI, SUBx,
               SBWC, DECx, MNEGx, MULx, CVTxy (where x is greater
               than y, for example CVTLB), AOBxx, ACBL, and SOBxx.

   QUADWORD    Provides support for quadword literal and address
               expressions.

   SUPPRESSION Provides listing of unreferenced symbols in the
               symbol table.

   TRACEBACK   Provides traceback information to the debugger.
               If the /DEBUG qualifier is also specified,
               it overrides /ENABLE=(DEBUG,TRACEBACK) or
               /DISABLE=(DEBUG,TRACEBACK), regardless of their order
               on the command line.

   By default, at compiler activation, FLAGGING, GLOBAL, TRACEBACK,
   and SUPPRESSION are enabled, and DEBUG, OVERFLOW, and QUADWORD
   are disabled.

   The /NOENABLE qualifier has the same effect as not specifying the
   /ENABLE qualifier. It can also be used to negate the effects of
   any /ENABLE qualifiers specified earlier in the command line.

                                  NOTE

      For every option of the /ENABLE qualifier, if /ENABLE and
      /DISABLE are used in the same command line for the same
      option, /DISABLE will always prevail, regardless of its
      position in the command line.

      You may want to enable an option previously disabled through
      the use of a symbol. For example, you may have incorporated
      the following frequently used options into the DCL symbol
      MAC, as follows:

      MAC::== MACRO/MIGRATION/NOTIE/DISABLE=FLAGGING

      To enable FLAGGING using the symbol MAC, issue the following
      command:

      $ MAC /NODISABLE/ENABLE=FLAGGING
 

/FLAG

      /FLAG=(option[,...])
      /NOFLAG

   Specifies which classes of informational messages the compiler
   reports. The options are:

   Option          Description

   ALIGNMENT       Reports unaligned stack and memory references.

   ALL             Enables all options.

   ARGLIST         Reports that the argument list has been homed.

   CODEGEN         Reports run-time code generation, such as self-
                   modifying code.

   DIRECTIVES      Reports unsupported directives.

   HINTS           Reports input/output/auto-preserved register
                   hints.

   INSTRUCTIONS    Reports instructions that use absolute addresses
                   that might compile correctly, but should be
                   examined anyway, because the desired absolute
                   address might be different on the system.

   JUMPS           Reports branches between routines.

   NONE            Disables all options.

   STACK           Reports all messages caused by user stack
                   manipulation.

   At compiler activation, the default is /FLAG=(ALIGNMENT, ARGLIST,
   CODEGEN, DIRECTIVES, INSTRUCTIONS, JUMPS, STACK).

                                  NOTE

      Use of the /NOFLAG and /FLAG qualifiers together to
      activate a specific subset of cross-compiler messages
      does not work as expected. When used together, as in
      /NOFLAG/FLAG=(keyword,keyword), instead of activating only
      the messages specified by the keywords, all cross-compiler
      messages are activated. However, use of /FLAG=(none,keyword)
      activates only those messages specified by the keyword.

   Note that specifying /NOFLAG or /FLAG=NONE does not disable the
   reporting of coding constructs that would prevent a successful
   compilation. The compiler continues to report code that you must
   change, such as an up-level stack reference.
 

/LIBRARY

      /LIBRARY
      /NOLIBRARY

   Positional qualifier.

   The associated input file to the /LIBRARY qualifier must be a
   macro library. The default file type is MLB. The /NOLIBRARY
   qualifier has the same effect as not specifying the /LIBRARY
   qualifier, or negates the effects of any /LIBRARY qualifiers
   specified earlier in the command line.

   The compiler can search up to 16 libraries, one of which
   is always STARLET.MLB. This number applies to a particular
   compilation, not necessarily to a particular MACRO command. If
   you enter the MACRO command so that more than one source file is
   compiled, but the source files are compiled separately, you can
   specify up to 16 macro libraries for each separate compilation.
   More than one macro library in a compilation causes the libraries
   to be searched in reverse order of their specification.

   A macro call in a source program causes the compiler to begin the
   following sequence of searches if the macro is undefined:

   1. The libraries specified with the .LIBRARY directive are
      searched first, in reverse order of the order in which they
      were declared.

   2. If the macro definition is not found in any of the libraries
      specified with the .LIBRARY directive, a search of the
      libraries specified in the MACRO command line (in the reverse
      order in which they were specified).

   3. If the macro definition is not found in any of the libraries
      specified in the command line, a search of STARLET.MLB.
 

/LIST

      /LIST[=filespec]
      /NOLIST

   Creates or omits an output listing, and optionally provides an
   output file specification for it. The default file type for the
   listing file is LIS. No wildcard characters are allowed in the
   file specification.

   An interactive MACRO command does not produce a listing file
   by default. The /NOLIST qualifier, present either explicitly or
   by default, causes errors to be reported on the current output
   device.

   The /LIST qualifier is the default for a MACRO command in a batch
   job. The /LIST qualifier allows you to control the defaults
   applied to the output file specification by the placement of
   the qualifier in the command line.
 

/MACHINE

      /MACHINE
      /NOMACHINE (default)

   Enables machine code listing, if it and the /LIST qualifier are
   both specified in the command line.
 

/OBJECT

      /OBJECT[=filespec]
      /NOOBJECT

   Creates or omits an object module. It also defines the file
   specification. By default, the compiler creates an object module
   with the same file name as the first input file. The default file
   type for object files is OBJ. No wildcard characters are allowed
   in the file specification.

   The /OBJECT qualifier controls the defaults applied to the output
   file specification by the placement of the qualifier in the
   command line.
 

/OPTIMIZE

      /OPTIMIZE[=(option[,...])]
      /NOOPTIMIZE

   Enables or disables optimization options. All options are enabled
   by default except VAXREGS.

   The options are:

   Option         Description

   [NO]PEEPHOLE   Peephole optimization
   [NO]SCHEDULE   Code scheduling
   [NO]ADDRESSES  Common base address loading
   [NO]REFERENCES Common data referencing
   [NO]VAXREGS    OpenVMS Alpha systems only: Allow the use of VAX
                  registers (R0 through R12) as temporary registers
                  when they appear to be unused
   ALL            All optimizations
   NONE           No optimizations

   Note that, on OpenVMS Alpha systems, /OPTIMIZE=ALL turns on
   VAXREGS, which may generate incorrect code unless all register
   usage of all routines in the module have been correctly declared.
 

/PRESERVE

      /PRESERVE[=(option[,...])]
      /NOPRESERVE (default)

   Directs the compiler to generate special OpenVMS Alpha or OpenVMS
   I64 code throughout a module for all VAX MACRO instructions that
   rely on VAX guarantees of operation atomicity or granularity.

   The options are:

   Option         Description

   GRANULARITY    Preserves the rules of VAX granularity of writes.
                  Specifying /PRESERVE=GRANULARITY causes the
                  compiler to use Alpha Load-locked and Store-
                  conditional instruction sequences or the Itanium
                  compare-exchange (cmpxchg) instruction in code it
                  generates for VAX instructions that perform byte,
                  word, or unaligned longword writes.

   ATOMICITY      Preserves atomicity of VAX modify operations.
                  Specifying /PRESERVE=ATOMICITY causes the
                  compiler to use Alpha Load-locked and Store-
                  conditional instruction sequences or the Itanium
                  compare-exchange (cmpxchg) instruction in code
                  it generates for VAX instructions with modify
                  operands.

   /PRESERVE and /PRESERVE=(GRANULARITY,ATOMICITY) are equivalent.
   When preservation of both granularity and atomicity is enabled,
   and the compiler encounters a VAX coding construct that requires
   both granularity and atomicity guarantees, it enforces atomicity
   over granularity.

   If you are aware of specific sections of VAX MACRO code that
   require VAX granularity and atomicity guarantees, you may not
   need the compiler to enforce these guarantees for the entire
   module. Instead, you can use the .PRESERVE and .NOPRESERVE
   directives to apply the guarantees only to those sections.
   Because the compiler does not need to generate expanded code
   for the entire module, these these directives can help optimize
   the code.

   Atomicity is guaranteed on multiprocessing systems as well as
   uniprocessing systems when you specify /PRESERVE=ATOMICITY.

   When the /PRESERVE qualifier is present, you can control the
   number of times compiler-generated code retries a granular or
   atomic update by specifying the /RETRY_COUNT qualifier.

                                WARNING

      If /PRESERVE=ATOMICITY is turned on, any unaligned data
      references will result in a fatal reserved operand fault.
      If /PRESERVE=GRANULARITY is turned on, unaligned word
      references to addresses assumed aligned will also cause a
      fatal reserved operand fault.
 

/RETRY_COUNT

      /RETRY_COUNT=count

   Specifies to the compiler the number of times the following
   operations should be performed in generated code:

   o  Retries of operations performed in source by a VAX interlocked
      instruction

   o  Retries of atomic or granular updates if the /PRESERVE
      qualifier or .PRESERVE directive is present

   If the /RETRY_COUNT qualifier is not present, the compiler
   generates code that performs an infinite number of retries of
   these operations.
 

/SHOW

      /SHOW[=(function[,...])]
      /NOSHOW[=(function[,...])]

   Provides initial settings for the functions controlled by the
   compiler directives .SHOW and .NOSHOW.

   You can specify one or more of the following functions:

   Option        Description

   CONDITIONALS  Lists unsatisfied conditional code associated with
                 .IF and .ENDC MACRO directives.

   CALLS         Lists macro calls and repeat range expansions.

   DEFINITIONS   Lists macro definitions.

   EXPANSIONS    Lists macro expansions.

   BINARY        Lists binary code generated by the expansion of
                 macro calls.
 

/SYMBOLS

      /SYMBOLS
      /NOSYMBOLS (default)

   Generates a symbol table and psect synopsis table for the listing
   file if it and the /LIST qualifier are both specified in the
   command line.
 

/TIE

      /TIE (default)
      /NOTIE

   Ensures that proper external callouts are generated for
   translated images. Translated images are images that were
   translated with the DECMigrate (also known as VEST) facility.
   The Translated Image Environment (TIE) allows translated images
   to execute as if on an OpenVMS VAX system. Use /NOTIE for better
   performance if you do not make calls to translated images.
 

/UNALIGNED

      /UNALIGNED
      /NOUNALIGNED (default)

   Forces the compiler to use unaligned loads and stores for all
   register-based memory references (except those that are FP-based
   or SP-based or are references to local aligned static data).

   By default, the compiler assumes that addresses in registers used
   as base pointers (except those that are FP-based or SP-based)
   are longword-aligned at routine entry, and generates code to load
   BYTE, WORD, and LONG data accordingly. This can result in run-
   time alignment faults, with significant performance impact, if
   the assumption is incorrect. Specifying /UNALIGNED causes the
   compiler to generate code assuming pointers are unaligned. This
   code is significantly larger, but is more efficient than handling
   an alignment fault.

                                  NOTE

      The compiler does not track quadword register alignment.
      For quadword memory references (such as in VAX MOVQ
      instructions), the compiler assumes the base address is
      quadword aligned, unless it has determined the address
      may not be longword-aligned in its register tracking code.
      Quadword references in OpenVMS Alpha and OpenVMS I64 built-
      in uses are always assumed to be quadword aligned. Since
      these must be in new code, the data should be properly
      aligned.

   The /UNALIGNED qualifier is generally appropriate only for
   modules where data is often unaligned, but which are not
   sufficiently performance sensitive to merit the correction of
   the data alignment in the source.
 

/WARN

      /WARN=[[option]...]
      /NOWARN

   Turns off all informational level or warning level messages. Both
   are on by default. The options are:

   Option     Description

   INFO       Turns on all informational level messages
   NOINFO     Turns off all informational level messages
   WARN       Turns on all informational and warning level messages
   NOWARN     Turns off all informational and warning level messages
 

3  VAX_MACRO_Assembler_Directives
   The MACRO Compiler for OpenVMS Systems supports most of the
   standard VAX MACRO assembler directives discussed in the VAX
   MACRO and Instruction Set Reference Manual. However, some
   directives that are supported by the VAX MACRO assembler do not
   make sense for compiled code. Consequently, the compiler flags
   them and continues execution. You can disable the flagging of
   these directives by specifying /NOFLAG=DIRECTIVES.

   The directives that you can disable are:

   o  .ENABLE and .DISABLE ABSOLUTE-for forcing absolute addressing
      modes

   o  .ENABLE and .DISABLE TRUNCATION-for enabling floating point
      truncation

   o  .LINK-for specifying linker options in a linker options file

   o  .DEFAULT-for setting displacement lengths

   o  .OPDEF and .REFn-for defining opcodes

   o  Alignment directives (.ALIGN, .EVEN, and .ODD) in code psects

   o  .TRANSFER

   o  .MASK

                                  NOTE

      The length of the argument to a .ASCID directive is limited
      to 996 characters when using the MACRO Compiler for OpenVMS
      Systems. No such restriction exists in the VAX MACRO
      Assembler.
 

3  MACRO_Compiler_Directives
   You can use certain arguments to these directives to indicate
   register sets. You express a register set by listing the
   registers, separated by commas, within angle brackets. For
   example:

   <R1,R2,R3>

   If only one register is in the set, no angle brackets are needed.
   For example:

   R1
 

4  .BRANCH_LIKELY
   Instructs the compiler that the following branch will likely be
   taken.

   Format

     .BRANCH_LIKELY

   There are no parameters for this directive.
 

5  Description
   The Alpha hardware predicts that forward conditional branches
   are not taken and that backwards conditional branches are taken.
   Based on the Alpha architecture, those assumptions are built into
   the compiler and influences the code generated for conditional
   branches.

   When .BRANCH_LIKELY precedes a forward conditional branch, the
   compiler will change the conditional branch and reorder the code
   such that the unlikely path will be a forward branch instead of
   the likely branch.

   The Itanium architecture includes branch prediction explicitly on
   each branch instruction. However, the compiler will still reorder
   the code to conform to the assumption that forward branches are
   not taken and backward branches are taken. The compiler will set
   the branch prediction flags as appropriate.
 

5  Example

 MOVL (R0),R1
 .BRANCH_LIKELY
 BNEQ    10$
   .
   .
   .
 10$

     The compiler will move the code between the BNEQ instruction
     and label 10$ to the end of the module, and change the BNEQ 10$
     to a BEQL to the moved code. It will then continue immediately
     following the BEQL instruction with generation of the code
     starting at label 10$.
 

4  .BRANCH_UNLIKELY
   Instructs the compiler that the following branch will likely
   not be taken. Therefore, the compiler generates code that
   incorporates that assumption.

   Format

     .BRANCH_UNLIKELY

   There are no parameters for this directive.
 

5  Description
   See the description of the .BRANCH_LIKELY directive for the
   assumptions used by the compiler when predicting branches.

   On OpenVMS Alpha systems, when .BRANCH_UNLIKELY precedes a
   conditional backwards branch, the compiler will change the
   conditional branch and the code such that the branch is a forward
   branch to an unconditional backwards branch. .BRANCH_UNLIKELY
   should only be used in cases where the branch is very unlikely,
   not just less frequent than the fall-through case.

   .BRANCH_UNLIKELY has no effect if it precedes a conditional
   forwards branch.
 

5  Example

 MOVL    #QUEUE,R0         ;Get queue header
 10$:    MOVL    (R0),R0   ;Get entry from queue
         BEQL    20$       ;Forward branch assumed unlikely
         .
         .                 ;Process queue entry
         .
         TSTL    (R0)      ;More than one entry (known to be unlikely)
         .BRANCH_UNLIKELY
         BNEQ    10$       ;This branch made into forward
 20$:                      ;conditional branch

     The .BRANCH_UNLIKELY directive is used here because the Alpha
     hardware would predict a backward branch to 10$ as likely to be
     taken. The programmer knows it is a rare case, so the directive
     is used to change the branch to a forward branch, which is
     predicted not taken.
 

4  .CALL_ENTRY
   Declares the entry point of a called routine to the compiler.
   This entry declaration will save and restore the full 64 bits of
   any registers (except R0 and R1) that are modified by the routine
   and are not declared as scratch or output.

   Format

     .CALL_ENTRY  [max_args=number] [,home_args=TRUE|FALSE]

                  [,quad_args=TRUE|FALSE] [,input] [,output]

                  [,scratch] [,preserve] [,label]
 

5  Parameters
 

max_args=number

   Maximum number of arguments the called procedure expects. The
   compiler uses this value as the number of longwords it allocates
   in the fixed temporary region of the stack frame, if the argument
   list must be homed. If homing is not necessary, the max_args
   count is not required. The compiler flags procedure entry
   points, where max_args has not been specified, that require homed
   argument lists.

   Note that, for .CALL_ENTRY routines in which max_args exceeds
   14, the compiler uses the received argument count, or max_args,
   whichever is smaller, when homing the argument list.
 

home_args=TRUE|FALSE

   Indication to the compiler that the called procedure's argument
   list should or should not be homed. The home_args argument
   overrides the compiler's default logic for determining the
   circumstances under which an argument list must be homed.
 

quad_args=TRUE|FALSE

   Indication to the compiler that the called procedure's argument
   list will have quadword references.
 

input=<>

   Register set that indicates those registers from which the
   routine receives input values.

   This register set informs the compiler that the registers
   specified have meaningful values at routine entry and are
   unavailable for use as temporary registers even before the first
   compiler-detected use of the registers. Specifying registers in
   this register set affects compiler temporary register usage in
   two cases:

   o  If you are using the VAXREGS (OpenVMS Alpha only) optimization
      option. This optimization allows the compiler to use as
      temporary registers any of the VAX registers which are not
      explicitly being used by the VAX MACRO code.

   o  If you are explicitly using any of the Alpha or Itanium
      registers (R13 and above).

   In either of these cases, if you do not specify a register that
   is being used as input in the input argument, the compiler may
   use the register as a temporary register, corrupting the input
   value.

   This register set has no effect on the compiler's default
   register preservation behavior. If you are not using the VAXREGS
   optimization switch or any of the Alpha registers, the input mask
   is used only to document your routine.
 

output=<>

   Register set that indicates those registers to which the routine
   assigns values that are returned to the routine's caller.
   Registers included in this register set are not saved and
   restored by the compiler, even if they are modified by the
   routine.

   This register set also informs the compiler that the registers
   specified have meaningful values at routine exit and are
   unavailable for use as temporary registers even after the last
   compiler-detected use of the registers. Specifying registers in
   this register set affects compiler temporary register usage in
   two cases:

   o  If you are using the VAXREGS (OpenVMS Alpha only) optimization
      switch. This optimization allows the compiler to use as
      temporary registers any of the VAX registers which are not
      explicitly being used by the VAX MACRO code.

   o  If you are explicitly using any of the Alpha or Itanium
      registers (R13 and above).

   In either of these cases, if you do not specify a register that
   is being used as output in the output argument, the compiler may
   use the register as a temporary register, corrupting the output
   value.
 

scratch=<>

   Register set that indicates registers that are used within the
   routine but which should not be saved and restored at routine
   entry and exit. The caller of the routine does not expect to
   receive output values nor does it expect the registers to be
   preserved. Registers included in this register set are not saved
   and restored by the compiler, even if they are modified by the
   routine.

   This also pertains to the compiler's temporary register usage.
   On OpenVMS Alpha systems, the compiler may use registers R13 and
   above as temporary registers if they are unused in the routine
   source code. Because R13 through R15 must be preserved, if
   modified, on OpenVMS Alpha systems, the compiler preserves those
   registers if it uses them.

   However, if they appear in the scratch register set declaration,
   the compiler will not preserve them if it uses them as temporary
   registers. As a result, these registers may be scratched at
   routine exit, even if they were not used in the routine source
   but are in the scratch set. If the VAXREGS (OpenVMS Alpha only)
   optimization is used, this applies to registers R2 through R12,
   as well.


preserve=<>

   Register set that indicates those registers that should be
   preserved over the routine call. This should include only those
   registers that are modified and whose full 64-bit contents should
   be saved and restored.

   This register set causes registers to be preserved whether or
   not they would have been preserved automatically by the compiler.
   Note that because R0 and R1 are scratch registers, by calling
   standard definition, the compiler never saves and restores them
   unless you specify them in this register set. Registers R16 and
   above are not allowed. 

   This register set overrides the output and scratch register sets.
   If you specify a register both in the preserve register set and
   in the output or scratch register sets, the compiler will report
   the warning:

   %AMAC-W-REGDECCON, register declaration conflict in routine A
 

label=name

   Optionally specify a label as in a VAX MACRO .ENTRY directive.
   This can be used if a module is to be common between OpenVMS
   VAX and OpenVMS Alpha or OpenVMS I64, if the OpenVMS VAX version
   needs to reference the entry with a .MASK directive, and if the
   OpenVMS Alpha or OpenVMS I64 version needs to use one or more
   of the special .CALL_ENTRY parameters. When the label parameter
   is specified and the symbol VAX is defined, an .ENTRY directive
   is used. If the symbol VAX is not defined, it creates the label
   and does a normal .CALL_ENTRY. Note that label is not the first
   parameter. Therefore, you cannot simply replace .ENTRY with
   .CALL_ENTRY. You must use the label parameter declaration.
 

4  .DEFINE_PAL
   OpenVMS Alpha only.

   Defines an arbitrary PALcode function such that it can be called
   later in the MACRO source.

   Format

     .DEFINE_PAL  name, pal_opcode, [,operand_descriptor_list]
 

5  Parameters
 

name

   Name of the PALcode function. The compiler applies the prefix
   EVAX_ to the specified name (for instance, EVAX_MTPR_USP).
 

pal_opcode

   Opcode value of the PALcode function.

   Be sure to use angle brackets around the function code when
   specifying it in hexadecimal format (^X). If you specify
   the function code in decimal format, angle brackets are not
   necessary.
 

operand_descriptor_list

   A list of operand descriptors that specifies the number of
   operands and the type of each. Up to six operand descriptors are
   allowed in the list. Be careful to specify operands correctly so
   that the compiler can correctly track register and stack usage.
   The following table lists the operand descriptors:

   Access
   Type                              Data Type

               Byte         Word        Longword    Octaword

   Address     AB           AW          AL          AQ
   Read-only   RB           RW          RL          RQ
   Modify      MB           MW          ML          MQ
   Write-only  WB           WW          WL          WQ
 

5  Description
   By default, the compiler defines many Alpha PALcode instructions
   as built-ins. If you need to use an Alpha PALcode instruction
   that is not available as a compiler built-in, you must define the
   built-in yourself using the .DEFINE_PAL directive.
 

5  Example

 .DEFINE_PAL MTPR_USP, <^X23>, RQ

                                  NOTE

      This is an example-the compiler compiles MTPR instructions
      directly to PAL calls.
 

4  .DISABLE
   Disables compiler features over a range of source code.

   Format

     .DISABLE  argument-list
 

5  Parameters
 

argument-list

   You can use one or more of the symbolic arguments listed in the
   following table:

   Option      Description

   DEBUG       Excludes local symbol table information in the object
               file for use with the debugger.
   FLAGGING    Deactivates compiler flagging.
   GLOBAL      Disables the assumption that undefined symbols are
               external symbols.
   OVERFLOW    Deactivates production of overflow trap code for the
               following opcodes: ADDx, ADWC, INCx, ADAWI, SUBx,
               SBWC, DECx, MNEGx, MULx, CVTxy (where x is greater
               than y, for example CVTLB), AOBxx, ACBL, and SOBxx.
   QUADWORD    Disables support for quadword literal and address
               expressions.
   SUPPRESSION Stops the listing of unreferenced symbols in the
               symbol table.
   TRACEBACK   Stops providing traceback information to the
               debugger.
 

4  .ENABLE
   Enables compiler features over a range of source code.

   Format

     .ENABLE  argument-list
 

5  Parameters
 

argument-list

   You can use one or more of the symbolic arguments listed in the
   following table:

   Option      Description

   DEBUG       Includes local symbol table information in the
               object file for use with the debugger. For this
               to take effect, you must compile with /DEBUG or
               /ENABLE=DEBUG.
   FLAGGING    Activates compiler flagging.
   GLOBAL      Assumes undefined symbols are external symbols.
   OVERFLOW    Activates production of overflow trap code for the
               following opcodes: ADDx, ADWC, INCx, ADAWI, SUBx,
               SBWC, DECx, MNEGx, MULx, CVTxy (where x is greater
               than y, for example CVTLB), AOBxx, ACBL, and SOBxx.
   QUADWORD    Provides support for quadword literal and address
               expressions.
   SUPPRESSION Provides a listing of unreferenced symbols in the
               symbol table.
   TRACEBACK   Provides traceback information to the debugger. For
               this to take effect, you must compile with /DEBUG or
               /ENABLE=TRACEBACK.
 

4  .EXCEPTION_ENTRY
   OpenVMS Alpha only.

   Declares the entry point of an exception service routine to the
   compiler.

   Format

     .EXCEPTION_ENTRY  [preserve] [,stack_base]
 

5  Parameters
 

preserve=<>

   Register set that forces the compiler to save and restore across
   the routine call the contents of registers. By default, the
   compiler saves at routine entry and restores at routine exit
   the full 64-bit contents of any register that is modified by a
   routine.

   In the case of an .EXCEPTION_ENTRY routine, exception dispatching
   saves R2 through R7 on the stack (along with the PC and PSL) and
   the values of these registers are restored by the REI instruction
   executed by the routine itself. Other registers, if used, are
   saved in code generated by the compiler, and all other registers
   are saved if the routine issues a CALL or JSB instruction.
 

stack_base

   Register into which the stack pointer (SP) value is moved at
   routine entry. At exception entry points, exception dispatching
   pushes onto the stack registers R2 through R7, the PC, and the
   PSL. Note that the Alpha counterpart for the VAX register known
   as the PSL is the processor status (PS) register. The value
   returned to the register specified in the stack_base helps an
   exception service routine locate the values of these registers.

   You can use the macro $INTSTKDEF in SYS$LIBRARY:LIB.MLB to define
   symbols for the area on the stack where R2-R7, the PC, and the
   PSL are stored. The symbols are:

   o  INTSTK$Q_R2

   o  INTSTK$Q_R3

   o  INTSTK$Q_R4

   o  INTSTK$Q_R5

   o  INTSTK$Q_R6

   o  INTSTK$Q_R7

   o  INTSTK$Q_PC

   o  INTSTK$Q_PS

   You can then use these symbols in the exception routine, as
   offsets to the stack_base value. By using the appropriate
   symbolic offset with the stack_base value, the exception routine
   can access the saved contents of any of these registers. For
   example, the exception routine could examine the PSL to see what
   access mode was in effect when the exception was taken.
 

5  Description
   The .EXCEPTION_ENTRY directive indicates the entry point of an
   exception service routine. At routine entry, R3 must contain the
   address of the procedure descriptor. The routine must exit with
   an REI instruction.

   You should declare with the .EXCEPTION_ENTRY directive all of the
   following interrupt service routines:

   o  Interval clock

   o  Interprocessor interrupt

   o  System/processor correctable error

   o  Power failure

   o  System/processor machine abort

   o  Software interrupt
 

4  .GLOBAL_LABEL
   Declares a global label in a routine that is not an entry point
   to the routine.

   Format

     Label: .GLOBAL_LABEL

   There are no parameters for this directive.
 

5  Description
   The .GLOBAL_LABEL directive declares a global label within a
   routine that is not a routine entry point. Unless declared with
   .GLOBAL_LABEL, global labels in code (specified with "::") are
   assumed to be entry point labels, which require declaration. If
   they are not declared, they are flagged as errors.

   The compiler also allows the address of a global label to be
   stored (for instance, by means of  PUSHAL instruction). (The
   compiler flags as an error any attempt to store a label that has
   not been declared as a global label or an entry point.)

   By using the .GLOBAL_LABEL directive, you are acknowledging that
   the stored code address will not be the target of a CALL or JSB
   instruction. Global labels must appear inside routine boundaries.

   Labels declared with the .GLOBAL_LABEL directive can be used as
   the newpc argument in calls to the $UNWIND (Unwind Call Stack)
   system service because it allows the address of the label to be
   stored.

   However, there is no provision in the compiler to automatically
   adjust the stack pointer at such labels to remove arguments
   passed on the stack or compensate for stack alignment. If
   the call stack is unwound back to an alternate PC in the
   calling routine, the stack may still contain arguments and
   alignment bytes, and any stack-based references that expect this
   adjustment to the caller's original stack depth (which happened
   automatically on VAX) will be incorrect.

   Code that contains labels declared with this directive that are
   to be used as alternate PC targets for $UNWIND must be examined
   carefully to ensure correct behavior, with particular emphasis on
   any references based on the stack pointer.
 

4  .JSB_ENTRY
   Declares the entry point of a JSB routine to the compiler. This
   entry declaration will save and restore the full 64 bits of any
   registers (except R0 and R1) that are modified by the routine and
   are not declared as scratch or output. See also .JSB32_ENTRY.

   Format

     .JSB_ENTRY  [input] [,output] [,scratch] [,preserve]
 

5  Parameters
 

input=<>

   Register set that indicates those registers from which the
   routine receives input values.

   This register set informs the compiler that the registers
   specified have meaningful values at routine entry and are
   unavailable for use as temporary registers even before the first
   compiler-detected use of the registers. Specifying registers in
   this register set affects compiler temporary register usage in
   two cases:

   o  If you are using the VAXREGS (OpenVMS Alpha only) optimization
      option. This optimization allows the compiler to use as
      temporary registers any of the VAX registers which are not
      explicitly being used by the VAX MACRO code.

   o  If you are explicitly using any of the Alpha or Itanium
      registers (R13 and above).

   In either of these cases, if you do not specify a register that
   is being used as input in the input argument, the compiler may
   use the register as a temporary register, corrupting the input
   value.

   This register set has no effect on the compiler's default
   register preservation behavior. If you are not using the VAXREGS
   optimization switch or any of the Alpha registers, the input mask
   is used only to document your routine.
 

output=<>

   Register set that indicates those registers to which the routine
   assigns values that are returned to the routine's caller.
   Registers included in this register set are not saved and
   restored by the compiler, even if they are modified by the
   routine.

   This register set also informs the compiler that the registers
   specified have meaningful values at routine exit and are
   unavailable for use as temporary registers even after the last
   compiler-detected use of the registers. Specifying registers in
   this register set affects compiler temporary register usage in
   two cases:

   o  If you are using the VAXREGS (OpenVMS Alpha only) optimization
      option. This optimization allows the compiler to use as
      temporary registers any of the VAX registers which are not
      explicitly being used by the VAX MACRO code.

   o  If you are explicitly using any of the Alpha or Itanium
      registers (R13 and above).

   In either of these cases, if you do not specify a register that
   is being used as output in the output argument, the compiler may
   use the register as a temporary register, corrupting the output
   value.
 

scratch=<>

   Register set that indicates registers that are used within the
   routine but which should not be saved and restored at routine
   entry and exit. The caller of the routine does not expect to
   receive output values nor does it expect the registers to be
   preserved. Registers included in this register set are not saved
   and restored by the compiler, even if they are modified by the
   routine.

   On OpenVMS Alpha systems, the compiler may use registers R13 and
   above as temporary registers if they are unused in the routine
   source code. Because R13 through R15 must be preserved, if
   modified, on OpenVMS Alpha systems, the compiler preserves those
   registers if it uses them.

   However, if they appear in the scratch register set declaration,
   the compiler will not preserve them if it uses them as temporary
   registers. As a result, these registers may be scratched at
   routine exit, even if they were not used in the routine source
   but are in the scratch set. If the VAXREGS (OpenVMS Alpha only)
   optimization is used, this applies to registers R2 through R12,
   as well.

 

preserve=<>

   Register set that indicates those registers that should be
   preserved over the routine call. This should include only those
   registers that are modified and whose full 64-bit contents should
   be saved and restored.

   This register set causes registers to be preserved whether or
   not they would have been preserved automatically by the compiler.
   Note that because R0 and R1 are scratch registers, by calling
   standard definition, the compiler never saves and restores them
   unless you specify them in this register set.

   This register set overrides the output and scratch register sets.
   If you specify a register both in the preserve register set and
   in the output or scratch register sets, the compiler will report
   the following warning:

   %AMAC-W-REGDECCON, register declaration conflict in routine A

                                  NOTE

      For procedures declared with the .JSB_ENTRY directive,
      the MACRO compiler automatically generates a null frame
      procedure descriptor on OpenVMS Alpha.

      Because no new context is set up by a null frame procedure,
      a side effect is that there is no guarantee of completely
      accurate debugger information about such procedures in
      response to SHOW CALLS and SHOW STACK commands. For example,
      the line number in the called null procedure (to which a JSB
      is done) may be reported as the line number in the calling
      procedure from which the JSB is issued.
 

4  .JSB32_ENTRY
   Declares the entry point of a JSB routine to the compiler. This
   directive does not preserve any VAX register values (R2 through
   R12) unless the PRESERVE parameter is specified. The routine
   itself may save and restore registers by pushing them on the
   stack, but this will not preserve the upper 32 bits of the
   registers. See also .JSB_ENTRY.

                                WARNING

      The .JSB32_ENTRY directive can be a great time-saver if you
      are sure that you can use it. If you use .JSB32_ENTRY in a
      situation where the upper 32 bits of a register are being
      used, it may cause very obscure and difficult-to-track bugs
      by corrupting a 64-bit value that may be several calling
      levels above the offending routine.

      .JSB32_ENTRY should never be used in an AST routine,
      condition handler, or any other code that can be executed
      asynchronously.

   Format

     .JSB32_ENTRY  [input] [,output] [,scratch] [,preserve]
 

5  Parameters
 

input=<>

   Register set that indicates those registers from which the
   routine receives input values.

   For the .JSB32_ENTRY directive, this register set is used only to
   document your code.
 

output=<>

   Register set that indicates those registers to which the routine
   assigns values that are returned to the routine's caller.

   For the .JSB32_ENTRY directive, this register set is used only to
   document your code.
 

scratch=<>

   Register set that indicates registers that are used within the
   routine but which should not be saved and restored at routine
   entry and exit. The caller of the routine does not expect to
   receive output values nor does it expect the registers to be
   preserved.

   The scratch argument also pertains to the compiler's temporary
   register usage. On OpenVMS Alpha sytems, the compiler may use
   registers R13 and above as temporary registers if they are unused
   in the routine source code. Because R13 through R15 must be
   preserved, if modified, on Alpha systems, the compiler preserves
   those registers if it uses them.

   However, if they appear in the scratch register set declaration,
   the compiler will not preserve them if it uses them as temporary
   registers. As a result, these registers may be scratched at
   routine exit, even if they were not used in the routine source
   but are in the scratch set.

   Because R2 through R12 are not preserved by default, their
   inclusion in the scratch is for documentation purposes only.
 

preserve=<>

   Register set that indicates those registers that should be
   preserved over the routine call. This should include only those
   registers that are modified and whose full 64-bit contents should
   be saved and restored.

   This register set causes registers to be preserved by the
   compiler. By default, no registers are preserved by the .JSB32_
   ENTRY directive.

   This register set overrides the output and scratch register sets.
   If you specify a register both in the preserve register set and
   in the output or scratch register sets, the compiler will report
   the warning:

   %AMAC-W-REGDECCON, register declaration conflict in routine A
 

5  Description
   The .JSB32_ENTRY directive is an alternative way of declaring a
   JSB entry point. It is designed to streamline the declaration of
   VAX MACRO routines that operate within a well-defined, bounded
   application environment, such as that of a single application
   or a self-contained subsystem. For any routine declared with the
   .JSB32_ENTRY directive, the compiler does not automatically save
   or restore any VAX registers (R2 through R12), therefore leaving
   the current 32-bit operation untouched. When you use the .JSB32_
   ENTRY directive to declare a JSB entry point, you are responsible
   for declaring and saving registers which must be preserved.

   If the externally visible entry points of a subsystem can be
   called from the 64-bit environment, those entry points should
   not be declared with .JSB32_ENTRY. Instead, .JSB_ENTRY (or .CALL_
   ENTRY) should be used so that the full 64-bit register values are
   saved, if necessary.
 

4  .LINKAGE_PSECT
   OpenVMS Alpha only.

   Allows the name of the linkage section psect to be changed.

   Format

     .LINKAGE_PSECT  program-section-name
 

5  Parameters
 

program_section_name

   Name of the program section. The name can contain up to 31
   characters, including any alphanumeric character and the special
   characters underline (_), dollar sign ($), and period (.).
 

5  Description
   The .LINKAGE_PSECT directive allows you to locate a routine's
   linkage section by reference to other psects within the routine.
   This facilitates such operations as locking code within memory
   and forcing code location. An example of forcing code location is
   to explicitly place the psect in the image created by the linker,
   using linker options. This would let you use adjacent psects to
   find their bounds.

   You can use the .LINKAGE_PSECT directive multiple times within
   a single source module to set different linkage sections for
   different routines. However, note that a routine's linkage
   section remains the same for the entire routine. The name
   of the routine's linkage section is the one specified in the
   last .LINKAGE_PSECT directive before the routine's entry point
   directive.

   The compiler reports a fatal error if different linkage sections
   are specified for routines that share code paths.

   The .LINKAGE_PSECT directive sets the psect attributes to be
   the same as the default linkage psect $LINKAGE. The attributes
   are the same as the normal psect default attributes except the
   linkage psect is set NOEXE NOWRT.

   You can change the linkage section psect attributes using the
   .PSECT directive after declaring the psect with .LINKAGE_PSECT.
 

5  Example

       .LINKAGE_PSECT LINK_001
       .PSECT LINK_000
 LS_START:
       .PSECT LINK_002
 LS_END:

     This code allows a program to use LS_START and LS_END in
     computations to determine the location and size of the linkage
     section (LINK_001) of the routine.
 

4  .PRESERVE
   Directs the compiler to generate special OpenVMS Alpha or OpenVMS
   I64 code throughout a module for all VAX MACRO instructions that
   rely on VAX guarantees of operation atomicity or granularity.

   Format

     .[NO]PRESERVE  argument-list
 

5  Parameters
 

argument-list

   One or more of the symbolic arguments listed in the following
   table:

   Option         Description

   GRANULARITY    Preserves the rules of VAX granularity of writes.
                  Specifying .PRESERVE=GRANULARITY causes the
                  compiler to use Alpha Load-locked and Store-
                  conditional instruction sequences or the Itanium
                  compare-exchange (cmpxchg) instruction in code it
                  generates for VAX instructions that perform byte,
                  word, or unaligned longword writes.
   ATOMICITY      Preserves atomicity of VAX modify operations.
                  Specifying .PRESERVE=ATOMICITY causes the
                  compiler to use Alpha Load-locked and Store-
                  conditional instruction sequences or the Itanium
                  compare-exchange (cmpxchg) instruction in code
                  it generates for VAX instructions with modify
                  operands.
 

5  Description
   The .PRESERVE and .NOPRESERVE directives cause the compiler to
   generate special Alpha assembly code for VAX MACRO instructions,
   within portions of the source module, that rely on VAX guarantees
   of operation atomicity or granularity.

   Use of .PRESERVE or .NOPRESERVE without specifying GRANULARITY
   or ATOMICITY will affect both options. When preservation of
   both granularity and atomicity is enabled, and the compiler
   encounters a VAX coding construct that requires both granularity
   and atomicity guarantees, it enforces atomicity over granularity.

   Alternatively, you can use the /PRESERVE and /NOPRESERVE compiler
   qualifiers to affect the atomicity and granularity in generated
   code throughout an entire MACRO source module, though this is not
   recommended, because the overhead of the extra code where it is
   not needed can slow the program down considerably.

   Atomicity is guaranteed for multiprocessing systems as well as
   uniprocessing systems when you specify .PRESERVE ATOMICITY.

   When the .PRESERVE directive is present, you can use the /RETRY_
   COUNT qualifier on the command line to control the number of
   times the compiler-generated code retries a granular or atomic
   update.

                                WARNING

      If .PRESERVE ATOMICITY is turned on, any unaligned data
      references will result in a fatal reserved operand fault.

      If .PRESERVE GRANULARITY is turned on, unaligned word
      references to addresses assumed aligned will also cause a
      fatal reserved operand fault.
 

5  Example

 INCW 1(R0)

     This instruction, when compiled with .PRESERVE GRANULARITY,
     retries the insertion of the new word value, if it is
     interrupted. However, when compiled with .PRESERVE ATOMICITY,
     it will also refetch the initial value and increment it, if
     interrupted. If both options are specified, it will do the
     latter.
 

4  .SET_REGISTERS
   This directive allows you to override the compiler's alignment
   assumptions, and also allows implicit reads/writes of registers
   to be declared.

   Format

     .SET_REGISTERS  argument-list
 

5  Parameters
 

argument-list

   One or more of the arguments listed in the following table. For
   each argument, you can specify one or more registers:

   Option       Description

   aligned=<>   Declares one or more registers to be aligned on
                longword boundaries.
   unaligned=<> Declares one or more registers to be unaligned.
                Because this is an explicit declaration, this
                unaligned condition will not produce a fault at
                run time.
   read=<>      Declares one or more registers, which otherwise the
                compiler could not detect as input registers, to be
                read.
   written=<>   Declares one or more registers, which otherwise the
                compiler could not detect as output registers, to be
                written to.
 

5  Description
   The aligned and unaligned qualifiers to this directive allow
   you to override the compiler's alignment assumptions. Using the
   directive for this purpose in certain cases can produce more
   efficient code.

   The read and written qualifiers to this directive allow implicit
   reads and writes of registers to be declared. They are generally
   used to declare the register usage of called routines and are
   useful for documenting your program.

   With one exception, the .SET_REGISTERS directive remains in
   effect (ensuring proper alignment processing) until the routine
   ends, unless you change the value in the register. The exception
   can occur under certain conditions when a flow path joins the
   code following a .SET_REGISTERS directive.

   The following example illustrates such an exception. R2 is
   declared aligned, and at a subsequent label, 10$, which is
   before the next write access to the register, a flow path joins
   the code. R2 will be treated as unaligned following the label,
   because it is unaligned from the other path.

           INCL R2          ; R2 is now unaligned
            .
            .
            .
           BLBC R0, 10$
            .
            .
            .
           MOVL R5, R2
           .SET_REGISTERS ALIGNED=R2
           MOVL R0, 4(R2)
     10$:  MOVL 4(R2), R3   ; R2 considered unaligned
                            ; due to BLBC branch

   The .SET_REGISTERS directive and its read and written qualifiers
   are required on every routine call that passes or returns data in
   any register from R2 through R12, if you specify the command line
   qualifier and option /OPTIMIZE=VAXREGS (OpenVMS Alpha only). That
   is because the compiler allows the use of unused VAX registers as
   temporary registers when you specify /OPTIMIZE=VAXREGS.
 

5  Examples

   1.DIVL R0,R1

     .SET_REGISTERS ALIGNED=R1
     MOVL     8(R1), R2          ; Compiler will use aligned load.

     In this example, the compiler would normally consider R1
     unaligned after the division. Any memory references using R1 as
     a base register (until it is changed again) would use unaligned
     load/stores. If it is known that the actual value will always
     be aligned, performance could be improved by adding a .SET_
     REGISTERS directive, as shown.

   2.MOV1     4(R0), R1          ;Stored memory addresses assumed

     .SET_REGISTERS UNALIGNED=R1 ;aligned so explicitly set it un-
     MOVL     4(R1), R2          ;aligned to avoid run-time fault.

     In this example, R1 would be considered longword aligned after
     the MOVL. If it is actually unaligned, an alignment fault would
     occur on memory reference that follows at run time. To prevent
     this, the .SET_REGISTERS directive can be used, as shown.

   3..SET_REGISTERS READ=<R3,R4>, WRITTEN=R5

     JSB     DO_SOMETHING_USEFUL

     In this example, the read/written attributes are used to
     explicitly declare register uses which the compiler cannot
     detect. R3 and R4 are input registers to the JSB target
     routine, and R5 is an output register. This is particularly
     useful if the routine containing this JSB does not use these
     registers itself, or if the SET_REGISTERS directive and JSB
     are embedded in a macro. When compiled with /FLAG=HINTS,
     routines which use the macro would then have R3 and R4 listed
     as possible input registers, even if they are not used in that
     routine.
 

4  .SYMBOL_ALIGNMENT
   This directive associates an alignment attribute with a symbol
   definition for a register offset. You can use this directive
   when you know the alignment of the base register. This attribute
   guarantees to the compiler that the base register has the same
   alignment, which enables the compiler to generate optimal code.

   Format

     .SYMBOL_ALIGNMENT  argument-list
 

5  Parameters
 

argument-list

   One of the arguments listed in the following table:

   Option  Description

   long    Declares longword alignment for any symbol that you
           declare after this directive.
   quad    Declares quadword alignment for any symbol that you
           declare after this directive.
   none    Turns off the alignment specified by the preceding
           .SYMBOL_ALIGNMENT directive.
 

5  Description
   The .SYMBOL_ALIGNMENT directive is used to associate an alignment
   attribute with the fields in a structure when you know the base
   alignment. It is used in pairs. The first .SYMBOL_ALIGNMENT
   directive associates either longword (long) or quadword (quad)
   alignment with the symbol or symbols that follow. The second
   directive, .SYMBOL_ALIGNMENT none, turns it off.

   Any time a reference is made with a symbol with an alignment
   attribute, the base register of that reference, in effect,
   inherits the symbol's alignment. The compiler also resets the
   base register's alignment to longword for subsequent alignment
   tracking. This alignment guarantee enables the compiler to
   produce more efficient code sequences.
 

5  Example

 OFFSET1 = 4
 .SYMBOL_ALIGNMENT LONG
 OFFSET2 = 8
 OFFSET3 = 12
 .SYMBOL_ALIGNMENT QUAD
 OFFSET4 = 16
 .SYMBOL_ALIGNMENT NONE
 OFFSET5 = 20
     .
     .
     .
 CLR1 OFFSET2(R8)
     .
     .
     .
 MOVL R2, OFFSET4(R6)

     For OFFSET1 and OFFSET5, the compiler will use only its
     tracking information for deciding if Rn in OFFSET1(Rn) is
     aligned or not. For the other references, the base register
     will be treated as longword (OFFSET2 and OFFSET3) or quadword
     (OFFSET4) aligned.

     After each use of OFFSET2 or OFFSET4, the base register in the
     reference is reset to longword alignment. In this example, the
     alignment of R8 and R6 will be reset to longword, although the
     reference to OFFSET4 will use the stronger quadword alignment.
 

3  MACRO_Compiler_Built-Ins
   On OpenVMS Alpha systems, the compiler provides two sets of
   built-ins:

   o  Alpha instruction built-ins that are used to access Alpha
      instructions for which there are no VAX equivalents.

   o  Alpha PALcode built-ins that are used to emulate the VAX
      instructions for which there are no Alpha equivalents and to
      perform other functions such as quadword queue manipulations.

   Both sets of built-ins are presented in tables. The second column
   of each table specifies the operands the built-in expects, where:

      WL = write longword
      ML = modify longword
      AL = address of longword
      WQ = write quadword
      RQ = read quadword
      MQ = modify quadword
      AQ = address of quadword
      AB = address of byte
      AW = address of word
      WB = write byte
      WW = write word

                                  NOTE

      Be careful when mixing built-ins with VAX MACRO instructions
      on the same registers. The code generated by the compiler
      expects registers to contain 32-bit sign-extended values,
      but it is possible to create 64-bit register values that are
      not in this format. Subsequent longword operations on these
      registers could produce incorrect results.

      Therefore, make sure to return registers to 32-bit sign-
      extended format before using them in VAX MACRO instructions
      as source operands. Note that loading the register with
      a new value using a VAX MACRO instruction (such as MOVL)
      returns it to this format.
 

4  Alpha_Instruction_Built-Ins
   Ported VAX MACRO code sometimes requires access to Alpha
   native instructions to deal directly with a 64-bit quantity
   or to include an Alpha instruction that has no VAX equivalent.
   The compiler provides built-ins to allow you access to these
   instructions.

   The following byte and word built-ins are included in the MACRO
   compiler:

   o  EVAX_LDBU

   o  EVAX_LDWU

   o  EVAX_STB

   o  EVAX_STW

   o  EVAX_SEXTB

   o  EVAX_SEXTW

   You use these built-ins in the same way that you use native VAX
   instructions, using any VAX operand mode. For example, EVAX_
   ADDQ 8(R0),(SP)+,R1 is legal. The only exception is that the
   first operand of any Alpha load/store built-in (EVAX_LD*, EVAX_
   ST*) must be a register.

   On OpenVMS Alpha, the best environment in which to run code
   that contains the byte and word built-ins is on a system that
   implements these instructions in hardware. If you run such code
   on an Alpha system that implements them by software emulation,
   the following limitations exist:

   o  Significant performance loss

      The overhead of handling the exception to trigger the software
      emulation causes a significant performance loss. If software
      emulation is in effect, you will see this message:

      %SYSTEM-I-EMULATED,
       an instruction not implemented on this processor was emulated

   o  Some capabilities not present in the software emulation

      The software emulation is not capable of providing all
      the capabilities that would be present on a system that
      implemented the the instructions in hardware. Code that
      executes in inner access modes and at elevated IPL is allowed
      to use these instructions. For example, activation of the
      software emulator above IPL 2 will not cause a bug check.
      However, certain applications where these instructions
      might be useful, such as direct writes to hardware control
      registers, will be impossible, because such applications
      require the presence of address lines whose function cannot
      be emulated.

   Furthermore, if the code with these built-ins executes on a
   system without either the byte and word software emulator or
   a processor that implements the byte and word instructions in
   hardware, it will incur a fatal exception, such as the following:

   %SYSTEM-F-OPCDEC, opcode reserved to Digital fault at
   PC=00000000000020068,PS=0000001B

                                  NOTE

      Memory references in the MACRO compiler built-ins are always
      assumed to be quadword aligned except in EVAX_SEXTB, EVAX_
      SEXTW, EVAX_LDBU, EVAX_LDWU, EVAX_STB, EVAX_STW, EVAX_LDQU,
      and EVAX_STQU.

   The following table summarizes the Alpha built-ins supported by
   the compiler. The built-ins that are Alpha-only (cannot be used
   to generate or access Itanium instructions) are noted in the
   table.

                                                    Functional on
   Built-in      Operands   Description             OpenVMS I64?

   EVAX_SEXTB    <RQ,WB>    Sign-extend byte        Yes
   EVAX_SEXTW    <RQ,WW>    Sign-extend word        Yes
   EVAX_SEXTL    <RQ,WL>    Sign-extend longword    Yes

   EVAX_LDBU     <WQ,AB>    Load zero-extended      Yes
                            byte from memory
   EVAX_LDWU     <WQ,AQ>    Load zero-extended      Yes
                            word from memory
   EVAX_LDLL     <WL,AL>    Load longword locked    Yes
   EVAX_LDAQ     <WQ,AQ>    Load address of         Yes
                            quadword
   EVAX_LDQ      <WQ,AQ>    Load quadword           Yes
   EVAX_LDQL     <WQ,AQ>    Load quadword locked    Yes
   EVAX_LDQU     <WQ,AQ>    Load unaligned          Yes
                            quadword

   EVAX_STB      <RQ,AB>    Store byte from         Yes
                            register to memory
   EVAX_STW      <RQ,AW>    Store word from         Yes
                            register to memory
   EVAX_STLC     <ML,AL>    Store longword          Yes
                            conditional
   EVAX_STQ      <RQ,AQ>    Store quadword          Yes
   EVAX_STQC     <MQ,AQ>    Store quadword          Yes
                            conditional
   EVAX_STQU     <RQ,AQ>    Store unaligned         Yes
                            quadword

   EVAX_ADDQ     <RQ,RQ,WQ> Quadword add            Yes
   EVAX_SUBQ     <RQ,RQ,WQ> Quadword subtract       Yes
   EVAX_MULQ     <RQ,RQ,WQ> Quadword multiply       Yes
   EVAX_UMULH    <RQ,RQ,WQ> Unsigned quadword       Yes
                            multiply high

   EVAX_AND      <RQ,RQ,WQ> Logical product         Yes
   EVAX_OR       <RQ,RQ,WQ> Logical sum             Yes
   EVAX_XOR      <RQ,RQ,WQ> Logical difference      Yes
   EVAX_BIC      <RQ,RQ,WQ> Bit clear               Yes
   EVAX_ORNOT    <RQ,RQ,WQ> Logical sum with        Yes
                            complement
   EVAX_EQV      <RQ,RQ,WQ> Logical equivalence     Yes
   EVAX_SLL      <RQ,RQ,WQ> Shift left logical      Yes
   EVAX_SRL      <RQ,RQ,WQ> Shift right logical     Yes
   EVAX_SRA      <RQ,RQ,WQ> Shift right             Yes
                            arithmetic

   EVAX_EXTBL    <RQ,RQ,WQ> Extract byte low        Yes
   EVAX_EXTWL    <RQ,RQ,WQ> Extract word low        Yes
   EVAX_EXTLL    <RQ,RQ,WQ> Extract longword low    Yes
   EVAX_EXTQL    <RQ,RQ,WQ> Extract quadword low    Yes
   EVAX_EXTBH    <RQ,RQ,WQ> Extract byte high       Yes
   EVAX_EXTWH    <RQ,RQ,WQ> Extract word high       Yes
   EVAX_EXTLH    <RQ,RQ,WQ> Extract longword high   Yes
   EVAX_EXTQH    <RQ,RQ,WQ> Extract quadword high   Yes

   EVAX_INSBL    <RQ,RQ,WQ> Insert byte low         Yes
   EVAX_INSWL    <RQ,RQ,WQ> Insert word low         Yes
   EVAX_INSLL    <RQ,RQ,WQ> Insert longword low     Yes
   EVAX_INSQL    <RQ,RQ,WQ> Insert quadword low     Yes
   EVAX_INSBH    <RQ,RQ,WQ> Insert byte high        Yes
   EVAX_INSWH    <RQ,RQ,WQ> Insert word high        Yes
   EVAX_INSLH    <RQ,RQ,WQ> Insert longword high    Yes
   EVAX_INSQH    <RQ,RQ,WQ> Insert quadword high    Yes

   EVAX_TRAPB    <>         Trap barrier            No
   EVAX_MB       <>         Memory barrier          Yes
   EVAX_RPCC     <WQ>       Read process cycle      No
                            counter

   EVAX_CMPEQ    <RQ,RQ,WQ> Integer signed          Yes
                            compare, equal
   EVAX_CMPLT    <RQ,RQ,WQ> Integer signed          Yes
                            compare, less than
   EVAX_CMPLE    <RQ,RQ,WQ> Integer signed          Yes
                            compare, less equal
   EVAX_CMPULT   <RQ,RQ,WQ> Integer unsigned        Yes
                            compare, less than
   EVAX_CMPULE   <RQ,RQ,WQ> Integer unsigned        Yes
                            compare, less equal

   EVAX_BEQ      <RQ,AQ>    Branch equal            Yes
   EVAX_BLT      <RQ,AQ>    Branch less than        Yes
   EVAX_BNE      <RQ,AQ>    Branch not equal        Yes

   EVAX_CMOVEQ   <RQ,RQ,WQ> Conditional             Yes
                            move/equal
   EVAX_CMOVNE   <RQ,RQ,WQ> Conditional move/not    Yes
                            equal
   EVAX_CMOVLT   <RQ,RQ,WQ> Conditional move/less   Yes
                            than
   EVAX_CMOVLE   <RQ,RQ,WQ> Conditional move/less   Yes
                            or equal
   EVAX_CMOVGT   <RQ,RQ,WQ> Conditional             Yes
                            move/greater than
   EVAX_CMOVGE   <RQ,RQ,WQ> Conditional             Yes
                            move/greater or equal
   EVAX_CMOVLBC  <RQ,RQ,WQ> Conditional move/low    Yes
                            bit clear
   EVAX_CMOVLBS  <RQ,RQ,WQ> Conditional move/low    Yes
                            bit set

   EVAX_MF_FPCR  <WQ>       Move from floating-     No
                            point control
                            register
   EVAX_MT_FPCR  <WQ,RQ>    Move to floating-       No
                            point control
                            register
   EVAX_ZAP      <RQ,RQ,WQ> Zero bytes              Yes
   EVAX_ZAPNOT   <RQ,RQ,WQ> Zero bytes with NOT     Yes
                            mask
 

4  Alpha_PALcode_Built-Ins
   Alpha PALcode built-ins, primarily for privileged code, are used
   in the same way that Alpha instruction built-ins are used with
   two exceptions:

   o  For the queue PAL functions, the compiler does not move the
      input arguments to the Alpha registers before issuing the PAL
      call as it does for all other functions. Therefore, you must
      supply the code to do that.

   o  When using a built-in for a PAL call that returns a value, the
      source code must explicitly read R0 for the return value.

   Certain Alpha PALcode built-ins, EVAX_INSQHIQR, EVAX_INSQTIQR,
   EVAX_REMQHIQR, and EVAX_REMQHITR, support the manipulation of
   quadword queues, a function that VAX MACRO does not support. If
   you use these built-ins, you must supply the code to move the
   input arguments to R16 (and R17, for EVAX_INSQxxxx), as shown in
   the following example:

   MOVAB  Q_header, R16  ; Set up address of queue header for PAL call
   EVAX_REMQHIQR         ; Remove quadword queue entry
   EVAX_STQ  R0, entry   ; Save entry address returned in R0

   The Alpha PALcode built-ins are listed in the following table.

                                  NOTE

      You can use the .DEFINE_PAL compiler directive to custom-
      define a built-in for an Alpha PALcode operation that is not
      listed in this table.

   Built-in         Operands  Description

   EVAX_CFLUSH      <RQ>      Cache flush
   EVAX_DRAINA      <>        Drain aborts
   EVAX_LDQP        <AQ>      Load quadword physical
   EVAX_STQP        <AQ,RQ>   Store quadword physical
   EVAX_SWPCTX      <AQ>      Swap privileged context
   EVAX_BUGCHK      <RQ>      Bugcheck
   EVAX_CHMS        <>        Change mode supervisor
   EVAX_CHMU        <>        Change mode user
   EVAX_IMB         <>        Instruction memory barrier
   EVAX_SWASTEN     <RQ>      Swap AST enable
   EVAX_WR_PS_SW    <RQ>      Write processor status software field

   EVAX_MTPR_ASTEN  <RQ>      Move to processor register ASTEN
   EVAX_MTPR_ASTSR  <RQ>      Move to processor register ASTSR
   EVAX_MTPR_AT     <RQ>      Move to processor register AT
   EVAX_MTPR_FEN    <RQ>      Move to processor register FEN
   EVAX_MTPR_IPIR   <RQ>      Move to processor register IPIR
   EVAX_MTPR_IPL    <RQ>      Move to processor register IPL
   EVAX_MTPR_PRBR   <RQ>      Move to processor register PRBR
   EVAX_MTPR_SCBB   <RQ>      Move to processor register SCBB
   EVAX_MTPR_SIRR   <RQ>      Move to processor register SIRR
   EVAX_MTPR_TBIA   <>        Move to processor register TBIA
   EVAX_MTPR_TBIAP  <>        Move to processor register TBIAP
   EVAX_MTPR_TBIS   <AQ>      Move to processor register TBIS
   EVAX_MTPR_TBISD  <AQ>      Move to processor register, TB
                              invalidate single DATA
   EVAX_MTPR_TBISI  <AQ>      Move to processor register, TB
                              invalidate single ISTREAM
   EVAX_MTPR_ESP    <AQ>      Move to processor register ESP
   EVAX_MTPR_SSP    <AQ>      Move to processor register SSP
   EVAX_MTPR_USP    <AQ>      Move to processor register USP

   EVAX_MFPR_ASN    <>        Move from processor register ASN
   EVAX_MFPR_AT     <>        Move from processor register AT
   EVAX_MFPR_FEN    <>        Move from processor register FEN
   EVAX_MFPR_IPL    <>        Move from processor register IPL
   EVAX_MFPR_MCES   <>        Move from processor register MCES
   EVAX_MFPR_PCBB   <>        Move from processor register PCBB
   EVAX_MFPR_PRBR   <>        Move from processor register PRBR
   EVAX_MFPR_PTBR   <>        Move from processor register PTBR
   EVAX_MFPR_SCBB   <>        Move from processor register SCBB
   EVAX_MFPR_SISR   <>        Move from processor register SISR
   EVAX_MFPR_TBCHK  <AQ>      Move from processor register TBCHK
   EVAX_MFPR_ESP    <>        Move from processor register ESP
   EVAX_MFPR_SSP    <>        Move from processor register SSP
   EVAX_MFPR_USP    <>        Move from processor register USP
   EVAX_MFPR_WHAMI  <>        Move from processor register WHAMI

   EVAX_INSQHILR    <>        Insert entry into longword queue at
                              head interlocked-resident
   EVAX_INSQTILR    <>        Insert entry into longword queue at
                              tail interlocked-resident
   EVAX_INSQHIQR    <>        Insert entry into quadword queue at
                              head interlocked-resident
   EVAX_INSQTIQR    <>        Insert entry into quadword queue at
                              tail interlocked-resident
   EVAX_REMQHILR    <>        Remove entry from longword queue at
                              head interlocked-resident
   EVAX_REMQTILR    <>        Remove entry from longword queue at
                              tail interlocked-resident
   EVAX_REMQHIQR    <>        Remove entry from quadword queue at
                              head interlocked-resident
   EVAX_REMQTIQR    <>        Remove entry from quadword queue at
                              tail interlocked-resident

   EVAX_GENTRAP     <>        Generate trap exception

   EVAX_READ_UNQ    <>        Read unique context
   EVAX_WRITE_UNQ   <RQ>      Write unique context
 

3  Macros_for_Porting_from_VAX_to_Alpha_or_I64
   The following macros facilitate the porting of VAX MACRO code to
   an OpenVMS Alpha or OpenVMS I64 system. The macros are grouped
   according to their function.
 

4  Calculating_Page-Size_Values
   The following macros provide a standard, architecture-independent
   means for calculating page-size dependent values:

   o  $BYTES_TO_PAGES

   o  $NEXT_PAGE

   o  $PAGES_TO_BYTES

   o  $PREVIOUS_PAGE

   o  $ROUND_RETADR

   o  $START_OF_PAGE

   These macros reside in the directory SYS$LIBRARY:STARLET.MLB and
   can be used by both application code and system code. Because
   application code does not have access to SYSTEM_DATA_CELLS, you
   must supply the relevant masks, shift values, and so on.

   The shift values are correlated with the page size of the
   processor. The rightshift values are negative; the leftshift
   values are positive, as shown in Shift Values.

   Table D-1 Shift Values

   Page size                 rightshift leftshift

   512 bytes (VAX)            -9         9
   8K (OpenVMS Alpha or      -13        13
   OpenVMS I64)
   16K                       -14        14
   32K                       -15        15
   64K                       -16        16

   Typically, the application issues a call to $GETSYI (specifying
   the SYI$_PAGESIZE item descriptor) to obtain the CPU-specific
   page size and then compute other values from the page size that
   is returned.

   The following conventions apply to the macros described in this
   section:

   o  If the destination operand is blank, the source operand is
      used as the destination.

   o  All macros conditionalize code on the symbols VAXPAGE and
      BIGPAGE.

   o  Several macros allow for page-size-independent code on VAX
      systems with the independent=YES argument. These macros
      generate code in which I-stream fetches are changed to memory
      accesses. Because this is inherently slower on a VAX system,
      the default value of the independent argument is NO.
 

5  $BYTES_TO_PAGES
   Converts a byte count to a page count.

   Format

     $BYTES_TO_PAGES  source_bytcnt, dest_pagcnt, rightshift,

                      roundup=YES, quad=YES
 

6  Parameters
 

source_bytcnt

   Source byte count.
 

dest_pagcnt

   Destination of page count.
 

rightshift

   Location of application-provided value to shift (in place of
   multiply). This value is a function of the page size, as shown in
   the table on shift values.
 

roundup=YES

   If YES, page-size-1 is added to byte count before shifting;
   if NO, page count is truncated. Any other value is treated as
   the user-specified address of the page-size-1 value. Note that
   roundup=YES is incompatible with the presence of the rightshift
   argument; invoking the macro with both these arguments generates
   a compile-time warning.
 

quad=YES

   If YES, the conversion supports 64-bit addressing. If NO, the
   conversion does not support 64-bit addressing.
 

5  $NEXT_PAGE
   Computes the virtual address of the first byte in the next page.

   Format

     $NEXT_PAGE  source_va, dest_va, clearbwp=NO,

                 user_pagesize_addr, user_mask_addr, quad=YES
 

6  Parameters
 

source_va

   Source virtual address.
 

dest_va

   Destination of virtual address within next page.
 

clearbwp=NO

   If YES, masks the byte-within-page portion of the source virtual
   address. The clearbwp=NO option is a performance enhancement,
   avoiding unnecessary instructions if you know you are starting
   on a page boundary or you are intending to divide by page-size
   anyway.
 

user_pagesize_addr

   Location of the page-size value (returned by a call to the
   $GETSYI system service specifying the SYI$_PAGESIZE item
   descriptor) in the application data area. If this argument is
   blank, the macro uses MMG$GL_PAGESIZE (bigpage) or MMG$C_VAX_
   PAGE_SIZE (vaxpage).
 

user_mask_addr

   Location of the application-provided byte-within-page mask. If
   this argument is blank, the macro uses MMG$GL_BWP_MASK if user_
   pagesize_addr is also blank. Otherwise, it subtracts 1 from the
   contents of the user_pagesize_addr and uses that value.
 

quad=YES

   If YES, the conversion supports 64-bit addressing. If NO, the
   conversion does not support 64-bit addressing.
 

5  $PAGES_TO_BYTES
   Converts a page count to a byte count.

   Format

     $PAGES_TO_BYTES  source_pagcnt, dest_bytcnt, leftshift,

                      quad=YES
 

6  Parameters
 

source_pagcnt

   Source page count.
 

dest_bytcnt

   Destination of byte count.
 

leftshift

   Location of application-provided value to shift (in place of
   multiply). This value is a function of the page size, as shown in
   the table on shift values.
 

quad=YES

   If YES, the conversion supports 64-bit addressing. If NO, the
   conversion does not support 64-bit addressing.
 

5  $PREVIOUS_PAGE
   Computes the virtual address of the first byte in the previous
   page.

   Format

     $PREVIOUS_PAGE  source_va, dest_va, clearbwp=NO,

                     user_pagesize_addr, user_mask_addr,

                     quad=YES
 

6  Parameters
 

source_va

   Source virtual address.
 

dest_va

   Destination of virtual address within previous page.
 

clearbwp=NO

   If YES, masks the byte-within-page portion of the source virtual
   address. The clearbwp=NO option is a performance enhancement,
   avoiding unnecessary instructions if you know you are starting
   on a page boundary or you are intending to divide by page-size
   anyway.
 

user_pagesize_addr

   Location of the page-size value (returned by a call to the
   $GETSYI system service specifying the SYI$_PAGESIZE item
   descriptor) in the application data area. If this argument is
   blank, the macro uses MMG$GL_PAGESIZE (bigpage) or MMG$C_VAX_
   PAGE_SIZE (vaxpage).
 

user_mask_addr

   Location of the application-provided byte-within-page mask. If
   this argument is blank, the macro uses MMG$GL_BWP_MASK if user_
   pagesize_addr is also blank. Otherwise, it subtracts 1 from the
   contents of the user_pagesize_addr and uses that value.
 

quad=YES

   If YES, the conversion supports 64-bit addressing. If NO, the
   conversion does not support 64-bit addressing.
 

5  $ROUND_RETADR
   Rounds the range implied by the virtual addresses in a retadr
   array returned from a memory management system service to a range
   that is the factor of CPU-specific pages. The return value can be
   supplied as an inadr array in a subsequent call to another memory
   management system service.

   Format

     $ROUND_RETADR  retadr, full_range, user_mask_addr,

                    direction=ASCENDING
 

6  Parameters
 

retadr

   Address of array of two 32-bit addresses, typically returned from
   $CRMPSC or a similar service. This value can be in the form of
   either "label" or "(Rx)".
 

full_range

   Output array of two longwords. FULL_RANGE[0] is retadr[0]
   rounded down to a CPU-specific page boundary, and FULL_RANGE[1]
   is retadr[1] rounded up to one less than a CPU-specific page
   boundary (that is, to the last byte in the page).
 

user_mask_addr

   Location of application-provided byte-within-page mask. If this
   argument is blank, the macro uses MMG$GL_BWP_MASK on an OpenVMS
   Alpha or OpenVMS I64 system and VA$M_BYTE on an OpenVMS VAX
   system.
 

direction=ASCENDING

   Direction of rounding. The keywords are defined in the following
   table:

   ASCENDING          retadr[0] < retadr[1]
   DESCENDING         retadr[1] < retadr[0]
   UNKNOWN            Values are compared at run time, then proper
                      rounding is performed
 

5  $START_OF_PAGE
   Converts a virtual address to the address of the first byte
   within that page.

   Format

     $START_OF_PAGE  source_va, dest_va, user_mask_addr, quad=YES
 

6  Parameters
 

source_va

   Source virtual address.
 

dest_va

   Destination of virtual address of first byte within page.
 

user_mask_addr

   Location of application-provided byte-within-page mask. If this
   argument is blank, the macro uses MMG$GL_BWP_MASK on an OpenVMS
   Alpha or OpenVMS I64 system and MMG$C_VAX_PAGE_SIZE - 1 (defined
   in $pagedef) on an OpenVMS VAX system.
 

quad=YES

   If YES, the conversion supports 64-bit addressing. If NO, the
   conversion does not support 64-bit addressing.
 

4  Saving_and_Restoring_64-Bit_Registers
   Frequently, VAX MACRO source code must save and restore register
   values, because that is part of the defined interface or because
   the code requires work registers.

   On OpenVMS VAX, code can invoke any number of macros to do
   this. On OpenVMS Alpha and OpenVMS I64, you cannot simply
   replace these macros with 64-bit pushes and pops to and from
   the stack, because there is no guarantee that the macro caller
   has a quadword-aligned stack. Instead, you should replace such
   macro invocations with $PUSH64 and $POP64 macros. These macros,
   located in STARLET.MLB, preserve all 64 bits of a register but
   use longword references to do so.
 

5  $POP64
   Pops the 64-bit value on the top of the stack into a register.

   Format

     $POP64  reg
 

6  Parameters
 

reg

   Register into which the macro places the 64-bit value from the
   top of the stack.
 

6  Description
   $POP64 takes the 64-bit value at the top of the stack and places
   it in a register using longword instructions. This is to avoid
   using quadword instructions when an alignment fault should be
   avoided, but restoring all 64 bits is necessary.
 

5  $PUSH64
   Pushes the contents of a 64-bit register onto the stack.

   Format

     $PUSH64  reg
 

6  Parameters
 

reg

   Register to be pushed onto the stack.
 

6  Description
   $PUSH64 takes a 64-bit register and puts it on the stack
   using longword instructions. This is to avoid using quadword
   instructions when an alignment fault should be avoided, but
   saving all 64 bits is necessary.
 

4  Locking_Pages_into_a_Working_Set
   Five macros are provided for locking pages into a working set.
   These macros reside in SYS$LIBRARY:LIB.MLB. For a description
   of how to use these macros, see the HP OpenVMS MACRO Compiler
   Porting and User's Guide.

   Three macros are used for image initialization-time lockdown, and
   two macros are used for on-the-fly lockdown.

                                  NOTE

      If the code is being locked because the IPL will be raised
      above 2, where page faults cannot occur, make sure that
      the delimited code does not call run-time library or other
      procedures. The VAX MACRO compiler generates calls to
      routines to emulate certain VAX instructions. An image that
      uses these macros must link against the system base image so
      that references to these routines are resolved by code in a
      nonpageable executive image.


5  $LOCK_PAGE_INIT
   Required in the initialization routines of an image that is using
   $LOCKED_PAGE_START and $LOCKED_PAGE_END to delineate areas to be
   locked at initialization time.

   Format

     $LOCK_PAGE_INIT  [error]
 

6  Parameters
 

[error]

   Address to which to branch if one of the $LKWSET calls fail. If
   this address is reached, R0 reflects the status of the failed
   call, and R1 contains 0 if the call to lock the code failed, or 1
   if that call succeeded but the call to lock the linkage section
   failed.
 

6  Description
   $LOCK_PAGE_INIT creates the necessary psects and issues the
   $LWKSET calls to lock into the working set the code and linkage
   sections that were declared by $LOCKED_PAGE_START and $LOCKED_
   PAGE_END. R0 and R1 are destroyed by this macro.

   The psects locked by this macro are $LOCK_PAGE_2 and $LOCK_
   LINKAGE_2. If code sections in other modules, written in other
   languages, use these psects, they will be locked by an invocation
   of this macro in a VAX MACRO module.
 

5  $LOCKED_PAGE_END
   Marks the end of a section of code that may be locked at image
   initialization time by the $LOCK_PAGE_INIT macro.

   Format

     $LOCKED_PAGE_END  [link_sect]
 

6  Parameters
 

[link_sect]

   Psect to return to if the linkage psect in effect when the
   $LOCKED_PAGE_START macro was executed was not the default linkage
   psect, $LINKAGE.
 

6  Description
   $LOCKED_PAGE_END is used with $LOCKED_PAGE_START to delineate
   code that may be locked at image initialization time by the
   $LOCK_PAGE_INIT macro. The code delineated by these macros must
   contain complete routines-execution cannot fall through either
   macro, nor can you branch into or out of the locked code. Any
   attempt to branch into or out of the locked code section or to
   fall through the macros will be flagged by the compiler with an
   error.
 

5  $LOCKED_PAGE_START
   Marks the start of a section of code that may be locked at image
   initialization time by the $LOCK_PAGE_INIT macro.

   Format

     $LOCKED_PAGE_START

   There are no parameters for this macro.
 

6  Description
   $LOCKED_PAGE_START is used with $LOCKED_PAGE_END to delineate
   code that may be locked at image initialization time by the
   $LOCK_PAGE_INIT macro. The code delineated by these macros must
   contain complete routines-execution may not fall through either
   macro, nor may the locked code be branched into or out of. Any
   attempt to branch into or out of the locked code section or to
   fall through the macros will be flagged by the compiler with an
   error.
 

5  $LOCK_PAGE
   Marks the beginning of a section of code to be locked on-the-fly.

   Format

     $LOCK_PAGE  [error]
 

6  Parameters
 

[error]

   Address to branch to if one of the $LKWSET calls fail.
 

6  Description
   This macro is placed inline in executable code and must be
   followed by the $UNLOCK_PAGE macro. The $LOCK_PAGE/$UNLOCK_PAGE
   macro pair creates a separate routine in a separate psect. $LOCK_
   PAGE locks the pages and linkage section of this separate routine
   into the working set and JSRs to it. All code between this macro
   and the matching $UNLOCK_PAGE macro is included in the locked
   routine and is locked down.

   All registers are preserved by this macro unless the error
   address parameter is present and one of the calls fail. If that
   happens, R0 reflects the status of the failed call. R1 then
   contains 0 if the call to lock the code failed or 1 if that call
   succeeded but the call to lock the linkage section failed.

   If the ERROR parameter is used, the ERROR label must be placed
   outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
   is because the error routine is branched to before calling the
   subroutine that the $LOCK_PAGE and $UNLOCK_PAGE routines create.

   Note that since the locked code is made into a separate routine,
   any references to local stack storage within the routine will
   have to be changed, as the stack context is no longer the same.
   Also, you cannot branch into or out of the locked code from the
   rest of the routine.
 

5  $UNLOCK_PAGE
   Marks the end of a section of code to be locked on-the-fly.

   Format

     $UNLOCK_PAGE  [error][,LINK_SECT]
 

6  Parameters
 

[error]

   An error address to which to branch if one of the $ULKWSET calls
   fail.
 

[link_sect]

   Linkage psect to return to if the linkage psect in effect when
   the $LOCK_PAGE macro was executed was not the default linkage
   psect, $LINKAGE.
 

6  Description
   $UNLOCK_PAGE returns from the locked routine created by the
   $LOCK_PAGE and $UNLOCK_PAGE macro pair and then unlocks the pages
   and linkage section from the working set. This macro is placed
   inline in executable code after a $LOCK_PAGE macro.

   All registers are preserved by this macro unless the error
   address parameter is present and one of the calls fail. If that
   happens, R0 reflects the status of the failed call. R1 then
   contains 0 if the call to unlock the code failed or 1 if that
   call succeeded but the call to unlock the linkage section failed.

   If the error parameter is used, the error label must be placed
   outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
   is because the error routine is branched to after returning
   from the subroutine created by the $LOCK_PAGE and $UNLOCK_PAGE
   routines.
 

3  Macros_for_64-Bit_Addressing
   These macros reside in the directory SYS$LIBRARY:STARLET.MLB and
   can be used by both application code and system code.

   The page macros accommodate for 64-bit addresses. The support is
   provided by the QUAD=NO/YES parameter.

   You can use certain arguments to these macros to indicate
   register sets. To express a register set, list the registers,
   separated by commas, within angle brackets. For example:

   <R1,R2,R3>

   If the set contains only one register, the angle brackets are not
   required.
 

4  $SETUP_CALL64
   Initializes the call sequence.

   Format

     $SETUP_CALL64  arg_count, inline=true | false
 

5  Parameters
 

arg_count

   The number of arguments in the call.
 

inline

   Forces inline expansion, rather than creation of a JSB routine,
   when set to TRUE. If there are six or fewer arguments on
   OpenVMS Alpha, or eight or fewer on OpenVMS I64, the default
   is inline=false.
 

5  Description
   This macro initializes the state for a 64-bit call. It must be
   used before using $PUSH_ARG64 and $CALL64.

   If there are six or fewer arguments on OpenVMS Alpha, or eight or
   fewer on OpenVMS I64, the code is always in line.

   By default, if there are more than six arguments on OpenVMS
   Alpha or eight arguments on OpenVMS I64, this macro creates a
   JSB routine that is invoked to perform the actual call. However,
   if the inline option is specified as inline=true, the code is
   generated in line.

   This option should be enabled only if the code in which it
   appears has a fixed stack depth. A fixed stack depth can be
   assumed if no RUNTIMSTK or VARSIZSTK messages have been reported.
   Otherwise, if the stack alignment is not at least quadword,
   there might be many alignment faults in the called routine
   and in anything the called routine calls. The default behavior
   (inline=false) does not have this problem.

   If there are more than six arguments on OpenVMS Alpha or eight
   arguments on OpenVMS I64, there can be no references to AP or
   SP between a $SETUP_CALL64 and the matching $CALL64, because
   the $CALL64 code may be in a separate JSB routine. In addition,
   temporary registers (R16 and above) may not survive the $SETUP_
   CALL64. However, they can be used within the range, except where
   (on Alpha only) R16 through R21 interfere with the argument
   registers already set up. In such cases, higher temporary
   registers should be used instead.

                                  NOTE

      The $SETUP_CALL64, $PUSH_ARG64, and $CALL64 macros are
      intended to be used in an inline sequence. That is, you
      cannot branch into the middle of a $SETUP_CALL64/$PUSH_
      ARG64/$CALL64 sequence, nor can you branch around $PUSH_
      ARG64 macros or branch out of the sequence to avoid the
      $CALL64.
 

4  $PUSH_ARG64
   Does the equivalent of argument pushes for a call.

   Format

     $PUSH_ARG64  argument
 

5  Parameters
 

argument

   The argument to be pushed.
 

5  Description
   This macro pushes a 64-bit argument for a 64-bit call. The macro
   $SETUP_CALL64 must be used before you can use $PUSH_ARG64.

   Arguments will be read as aligned quadwords. That is, $PUSH_ARG64
   4(R0) will read the quadword at 4(R0), and push the quadword. Any
   indexed operations will be done in quadword mode.

   To push a longword value from memory as a quadword, first move it
   into a register with a longword instruction, and then use $PUSH_
   ARG64 on the register. Similarly, to push a quadword value that
   you know is not aligned, move it to a temporary register first,
   and then use $PUSH_ARG64.

   If the call contains more than six arguments on OpenVMS Alpha or
   eight arguments on OpenVMS I64, this macro checks for SP or AP
   references in the argument.

   If the call contains more than six arguments on OpenVMS Alpha or
   eight arguments on OpenVMS I64, SP references are not allowed,
   and AP references are allowed only if the inline option is used.

   OpenVMS Alpha systems only: The macro also checks for references
   to argument registers that have already been set up for the
   current $CALL64. If it finds such references, a warning is
   reported to advise the user to be careful not to overwrite an
   argument register before it is used as the source in a $PUSH_
   ARG64.

   OpenVMS Alpha systems only: The same checking is done for AP
   references when there are six or fewer arguments; they are
   allowed, but the compiler cannot prevent you from overwriting
   one before you use it. Therefore, if such references are found,
   an informational message is reported.

   OpenVMS Alpha systems only: Note that if the operand uses a
   symbol whose name includes one of the strings R16 through R21,
   not as a register reference, this macro might report a spurious
   error. For example, if the invocation $PUSH_ARG64 SAVED_R21 is
   made after R21 has been set up, this macro will unnecessarily
   report an informational message about overwriting argument
   registers.

   Also note that $PUSH_ARG64 cannot be in conditional code. $PUSH_
   ARG64 updates several symbols, such as the remaining argument
   count. Attempting to write code that branches around a $PUSH_
   ARG64 in the middle of a $SETUP_CALL64/$CALL64 sequence will not
   work properly.
 

4  $CALL64
   Invokes the target routine.

   Format

     $CALL64  call_target
 

5  Parameters
 

call_target

   The routine to be invoked.
 

5  Description
   This macro calls the specified routine, assuming $SETUP_CALL64
   has been used to specify the argument count, and $PUSH_ARG64 has
   been used to push the quadword arguments. This macro checks that
   the number of pushes matches what was specified in the setup
   call.

   The call_target operand must not be AP- or SP-based.
 

4  $IS_32BITS
   Checks the sign extension of the low 32 bits of a 64-bit value
   and directs the program flow based on the outcome of the check.

   Format

     $IS_32BITS  quad_arg, leq_32bits, gtr_32bits, temp_reg=22
 

5  Parameters
 

quad_arg

   A 64-bit quantity, either in a register or in an aligned quadword
   memory location.
 

leq_32bits

   Label to branch to if quad_arg is a 32-bit sign-extended value.
 

gtr_32bits

   Label to branch to if quad_arg is greater than 32 bits.
 

temp_reg=22

   Register to use as a temporary register for holding the low
   longword of the source value-R22 is the default.
 

5  Description
   $IS_32BITS checks the sign extension of the low 32 bits of a 64-
   bit value and directs the program flow based on the outcome of
   the check.
 

5  Examples

   1.$is_32bits  R9, 10$

     In this example, the compiler checks the sign extension of
     the low 32 bits of the 64-bit value at R9 using the default
     temporary register, R22. Depending on the type of branch
     and the outcome of the test, the program either branches or
     continues in line.

   2.$is_32bits  4(R8), 20$, 30$, R28

     In this example, the compiler checks the sign extension of
     the low 32 bits of the 64-bit value at 4(R8) using R28 as a
     temporary register and, based on the check, branches to either
     20$ or 30$.
 

4  $IS_DESC64
   Tests the specified descriptor to determine if it is a 64-bit
   format descriptor, and directs the program flow based on the
   outcome of the test.

   Format

     $IS_DESC  desc_addr, target, size=long | quad
 

5  Parameters
 

desc_addr

   The address of the descriptor to test.
 

target

   The label to branch to if the descriptor is in 64-bit format.
 

size=long|quad

   The size of the address pointing to the descriptor. The default
   value is size=long.
 

5  Description
   $IS_DESC64 tests the fields that distinguish a 64-bit descriptor
   from a 32-bit descriptor. If it is in 64-bit form, a branch is
   taken to the specified target. The address to be tested is read
   as a longword, unless size=quad is specified.
 

5  Examples

   1.$is_desc64 r9, 10$

     In this example, the descriptor pointed to by R9 is tested, and
     if it is in 64-bit form, a branch to 10$ is taken.

   2.$is_desc64 8(r0), 20$, size=quad

     In this example, the quadword at 8(R0) is read, and the
     descriptor it points to is tested. If it is in 64-bit form,
     a branch to 20$ is taken.