Document revision date: 19 July 1999

Cross-reference directives

Format

.CROSS [symbol-list]

.NOCROSS [symbol-list]

Parameter

symbol-list

A list of legal symbol names separated by commas (,).

Description

When you specify the /CROSS_REFERENCE qualifier in the MACRO command, VAX MACRO produces a cross-reference listing. The .CROSS and .NOCROSS directives control which symbols are included in the cross-reference listing. The .CROSS and .NOCROSS directives have an effect only if /CROSS_REFERENCE was specified in the MACRO command (see the OpenVMS DCL Dictionary).

By default, the cross-reference listing includes the definition and all the references to every symbol in the module.

You can disable the cross-reference listing for all symbols or for a specified list of symbols by using .NOCROSS. Using .NOCROSS without a symbol list disables the cross-reference listing of all symbols. Any symbol definition or reference that appears in the code after .NOCROSS used without a symbol list and before the next .CROSS used without a symbol list is excluded from the cross-reference listing. You reenable the cross-reference listing by using .CROSS without a symbol list.

.NOCROSS with a symbol list disables the cross-reference listing for the listed symbols only. .CROSS with a symbol list enables or reenables the cross-reference listing of the listed symbols.

Notes

1. The .CROSS directive without a symbol list will not reenable the cross-reference listing of a symbol specified in .NOCROSS with a symbol list.
2. If the cross-reference listing of all symbols is disabled, .CROSS with a symbol list will have no effect until the cross-reference listing is reenabled by .CROSS without a symbol list.

Examples

        .NOCROSS                ; Stop cross-reference 
LAB1:   MOVL      LOC1, LOC2    ; Copy data 
        .CROSS                  ; Reenable cross-reference 
      

In this example, the definition of LAB1 and the references to LOC1 and LOC2 are not included in the cross-reference listing.

        .NOCROSS  LOC1         ; Do not cross-reference LOC1 
LAB2:   MOVL      LOC1,LOC2    ; Copy data 
        .CROSS    LOC1         ; Reenable cross-reference 
                               ;   of LOC1 
      

In this example, the definition of LAB2 and the reference to LOC2 are included in the cross-reference, but the reference to LOC1 is not included in the cross-reference.

Debug symbol attribute directive

Format

.DEBUG symbol-list

Parameter

symbol-list

A list of legal symbols separated by commas (,).

Description

.DEBUG specifies that the symbols in the list are made known to the VAX Symbolic Debugger. During an interactive debugging session, you can use these symbols to refer to memory locations or to examine the values assigned to the symbols.

Note

The assembler adds the symbols in the symbol list to the symbol table in the object module. You need not specify global symbols in the .DEBUG directive because global symbols are automatically put in the object module's symbol table. (See the description of .ENABLE for a discussion of how to make information about local symbols available to the debugger.)

Example

.DEBUG  INPUT,OUTPUT,-    ; Make these symbols known 
        LAB_30,LAB_40     ;   to the debugger 
      

Default control directive

Format

.DEFAULT DISPLACEMENT, keyword

Parameter

keyword

One of three keywords---BYTE, WORD, or LONG---indicating the default displacement length.

Description

.DEFAULT determines the default displacement length for the relative and relative deferred addressing modes (see Section 5.2.1 and Section 5.2.2).

Notes

1. The .DEFAULT directive has no effect on the default displacement for displacement and displacement deferred addressing modes (see Section 5.1.6 and Section 5.1.7).
2. If there is no .DEFAULT in a source module, the default displacement length for the relative and relative deferred addressing modes is a longword.

Example

.DEFAULT  DISPLACEMENT,WORD   ; WORD is default 
MOVL      LABEL,R1            ; Assembler uses word 
                              ;   displacement unless 
                              ;   label has been defined 
.DEFAULT  DISPLACEMENT,LONG   ; LONG is default 
INCB    @COUNTS+4             ; Assembler uses longword 
                              ;   displacement unless 
                              ;   COUNTS has been defined 
      

Floating-point storage directive

Format

.D_FLOATING literal-list

.DOUBLE literal-list

Parameter

literal-list

A list of floating-point constants (see Section 3.2.2). The constants cannot contain any unary or binary operators except unary plus or unary minus.

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 and .H_FLOATING for descriptions of other floating-point numbers.

Notes

1. Double-precision floating-point numbers are always rounded. They are not affected by .ENABLE TRUNCATION.
2. The floating-point constants in the literal list must not be preceded by the floating-point operator (^F).

Example

.D_FLOATING  1000,1.0E3,1.0000000E-9    ; Constant 
.DOUBLE      3.1415928, 1.107153423828  ; List 
.D_FLOATING  5, 10, 15, 0, 0.5 
      

Function control directive

Format

.DISABLE argument-list

Parameter

argument-list

One or more of the symbolic arguments listed in Table 6-3 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.

Description

.DISABLE disables the specified assembler functions. See the description of .ENABLE for more information.

Note

The alternate form of .DISABLE is .DSABL.

Function control directive

Format

.ENABLE argument-list

Parameter

argument-list

One or more of the symbolic arguments listed in Table 6-3. 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-3 .ENABLE and .DISABLE Symbolic Arguments

Long Form	Short Form	Default Condition	Function
ABSOLUTE	AMA	Disabled	When ABSOLUTE is enabled, all the PC relative addressing modes are assembled as absolute addressing modes.
DEBUG	DBG	Disabled	When DEBUG is enabled, all local symbols are included in the object module's symbol table for use by the debugger.
GLOBAL	GBL	Enabled	When GLOBAL is enabled, all undefined symbols are considered external symbols. When GLOBAL is disabled, any undefined symbol that is not listed in an .EXTERNAL directive causes an assembly error.
LOCAL_BLOCK	LSB	Disabled	When LOCAL_BLOCK is enabled, the current local label block is ended and a new one is started. When LOCAL_BLOCK is disabled, the current local label block is ended. See Section 3.4 for a complete description of local label blocks.
SUPPRESSION	SUP	Disabled	When SUPPRESSION is enabled, all symbols that are defined but not referred to are not listed in the symbol table. When SUPPRESSION is disabled, all symbols that are defined are listed in the symbol table.
TRACEBACK	TBK	Enabled	When TRACEBACK is enabled, the program section names and lengths, module names, and routine names are included in the object module for use by the debugger. When TRACEBACK is disabled, VAX MACRO excludes this information and, in addition, does not make any local symbol information available to the debugger.
TRUNCATION	FPT	Disabled	When TRUNCATION is enabled, single-precision, floating-point numbers are truncated. When TRUNCATION is disabled, single-precision floating-point numbers are rounded. D_floating, G_floating, and H_floating numbers are not affected by .ENABLE TRUNCATION; they are always rounded.
VECTOR		Disabled	When VECTOR is enabled, the assembler accepts and correctly handles vector code. If vector assembly is not enabled, vector code produces assembly errors.

Description

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

• Creating local label blocks
• Making all local symbols available to the debugger and enabling the traceback feature
• Specifying that undefined symbol references are external references
• Truncating or rounding single-precision floating-point numbers
• Suppressing the listing of symbols that are defined but not referenced
• Specifying that all the PC references are absolute, not relative

Note

The alternate form of .ENABLE is .ENABL.

Example

.ENABLE ABSOLUTE, GLOBAL       ; Assemble relative address mode 
                               ;   as absolute address mode, and consider 
                               ;   undefined references as global 
 
.DISABLE TRUNCATION,TRACEBACK  ; Round floating-point numbers, and 
                               ;   omit debugging information from 
                               ;   the object module 
      

Assembly termination directive

Format

.END [symbol]

Parameter

symbol

The address (called the transfer address) at which program execution is to begin.

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 either the listing file or the object file.

Notes

1. The transfer address must be in a program section that has the EXE attribute (see the description of .PSECT).
2. 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.
3. If the source program contains an unterminated conditional code block when the .END directive is specified, the assembler displays an error message.

Example

.ENTRY  START,0                 ; Entry mask 
  . 
  .                             ; Main program 
  . 
.END    START                   ; Transfer address 
      

End conditional directive

Format

.ENDC

Description

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

End definition directive

Format

.ENDM [macro-name]

Parameters

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.

Description

.ENDM terminates the macro definition. See the description of .MACRO for an example of the use of .ENDM.

Note

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

End range directive

Format

.ENDR

Description

.ENDR indicates the end of a repeat range. It must be the final statement of every indefinite repeat block directive (.IRP and .IRPC) and every repeat block directive (.REPEAT). See the description of these directives for examples of the use of .ENDR.

Entry directive

Format

.ENTRY symbol,expression

Parameters

symbol

The symbolic name for the entry point.

expression

The register save mask for the entry point. The expression must be an absolute expression and must not contain any undefined symbols.

Description

.ENTRY defines a symbolic name for an entry point and stores a register save mask (2 bytes) at that location. The symbol is defined as a global symbol with a value equal to the value of the location counter at the .ENTRY directive. You can use the entry point as the transfer address of the program. Use the register save mask to determine which registers are saved before the procedure is called. These saved registers are automatically restored when the procedure returns control to the calling program. See the description of the procedure call instructions in Chapter 9.

Notes

1. The register mask operator (^M) is convenient to use for setting the bits in the register save mask (see Section 3.6.2.2).
2. An assembly error occurs if the expression has bits 0, 1, 12, or 13 set. These bits correspond to the registers R0, R1, AP, and FP and are reserved for the CALL interface.
3. Digital recommends that you use .ENTRY to define all callable entry points including the transfer address of the program. Although the following construct also defines an entry point, Digital discourages its use:

   symbol:: .WORD expression

   
   Although your program can call a procedure starting with this construct, the entry mask is not checked for any illegal registers, and the symbol cannot be used in a .MASK directive.

4. You should use .ENTRY only for procedures that are called by the CALLS or CALLG instruction. A routine that is entered by the BSB or JSB instruction should not use .ENTRY because these instructions do not expect a register save mask. Begin these routines using the following format:

   symbol:: first instruction

   
   The first instruction of the routine immediately follows the symbol.

Example

.ENTRY  CALC,^M<R2,R3,R7>      ; Procedure starts here. 
                               ; Registers R2, R3, and R7 
                               ;   are preserved by CALL 
                               ;   and RET instructions 
      

Error directive

Format

.ERROR [expression] ;comment

Parameters

expression

An expression whose value is displayed when .ERROR is encountered during assembly.

;comment

A comment that is displayed when .ERROR is encountered during assembly. The comment must be preceded by a semicolon (;).

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).

Notes

1. .ERROR, .WARN, and .PRINT are message display directives. Use them to display information indicating that a macro call contains an error or an illegal set of conditions.
2. When the assembly is finished, the assembler displays the total number of errors, warnings, information messages, and the sequence numbers of the lines causing the errors or warnings.
3. If .ERROR is included in a macro library, end the comment with a semicolon (;). Otherwise, the librarian will strip the comment from the directive and it will not be displayed when the macro is called.
4. The line containing the .ERROR directive is not included in the listing file.
5. If the expression has a value of zero, it is not displayed in the error message.

Example

.IF DEFINED     LONG_MESS 
.IF GREATER     1000-WORK_AREA 
.ERROR 25                        ; Need larger WORK_AREA; 
.ENDC 
.ENDC 
      

In this example, if the symbol LONG_MESS is defined and if the symbol WORK_AREA has a value of 1000 or less, the following error message is displayed:

%MACRO-E-GENERR, Generated ERROR: 25 Need larger WORK_AREA 
      

Even location counter alignment directive

Format

.EVEN

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.

External symbol attribute directive

Format

.EXTERNAL symbol-list

Parameter

symbol-list

A list of legal symbols, separated by commas (,).

Description

.EXTERNAL indicates that the specified symbols are external; that is, the symbols are defined in another object module and cannot be defined until link time (see Section 3.3.3 for a discussion of external references).

Notes

1. If the GLOBAL argument is enabled (see Table 6-3), all unresolved references will be marked as global and external. If GLOBAL is enabled, you need not specify .EXTERNAL. If GLOBAL is disabled, you must explicitly specify .EXTERNAL to declare any symbols that are defined externally but are referred to in the current module.
2. If GLOBAL is disabled and the assembler finds symbols that are neither defined in the current module nor listed in a .EXTERNAL directive, the assembler displays an error message.
3. Note that if your program does not reference, in a relocatable program section, symbols that are declared in the absolute program section (ABS), the unreferenced symbols are filtered out by the assembler and will not be included in the object file. This filtering out will occur even if the symbols are declared global or external.
   If you want to be sure that a symbol will be included even if it is not referenced, declare it in a relocatable program section. If you want to make sure that a symbol you define in an absolute program section is included, reference it in a relocatable program section.
4. The alternate form of .EXTERNAL is .EXTRN.

Example

.EXTERNAL      SIN,TAN,COS     ; These symbols are defined in 
.EXTERNAL      SINH,COSH,TANH  ;   externally assembled modules 
      

	privacy and legal statement
4515PRO_007.HTML