ALP Programming Guide and Reference/Using ALP
This chapter tells you how to:
- Invoke and use ALP
- Use environment variables to pass information to ALP
Invoking ALP
To invoke ALP from the command line, type:
alp
You can also invoke ALP by absolute reference from a makefile or command file; to do this, the directory should be among those referenced by the PATH environment variable.
Using Environment Variables
This section describes the environment variables that you can set and that are used by ALP.
<BaseEXE>_INCLUDE
When ALP processes an INCLUDE directive, ALP translates the value of the BaseEXE internal variable to uppercase and uses this value to construct the name of an ALP-specific environment variable having the form:
<BaseEXE>_INCLUDE
For example, If the value of BaseEXE is alp, then ALP constructs an environment variable called ALP_INCLUDE and tries to locate it in the environment. If found, its contents would be expected to contain a list of directories in a format identical to that of the standard INCLUDE environment variable.
<BaseEXE>_OPTIONS
ALP translates the value of the BaseEXE internal variable to uppercase and uses this value to construct the name of an ALP-specific environment variable having the form:
<BaseEXE>_OPTIONS
For example, if the value of BaseEXE is alp, then ALP constructs an environment variable called ALP_OPTIONS and tries to locate it in the environment. If found, its contents are logically prepended to the assembler command line.
You can use this variable to set alternate default values for assembler command line options. For maximum flexibility, it is recommended that this variable contain a reference to a command line response file using an @Filename directive, which allows the default command line options to be stored in a file rather than in the environment variable itself.
<BaseEXE>_PATH
Whenever ALP needs to search for one of its own component files (such as the messages file), the value of the BaseEXE internal variable is translated to uppercase and is used to construct the name of an ALP specific environment variable having the form "<BaseEXE>_PATH" For example, if the value of BaseEXE is "alp", then an environment variable called ALP_PATH would be constructed and an attempt would be made to locate it in the environment. If found, its contents would be expected to contain a list of directories in a format identical to that of the standard PATH environment variable. ALP then searches this list of paths when attempting to locate the component file.
DPATH
The DPATH environment variable may be utilized for the same purposes as the <BaseEXE>_PATH internal variable if so desired.
INCLUDE
The INCLUDE environment variable may be utilized for the same purposes as the <BaseEXE>_INCLUDE internal variable if so desired.
PATH
The PATH environment variable may be utilized for the same purposes as the <BaseEXE>_PATH internal variable if so desired.
Using the Command Line
This section describes command line parameter types, syntax, and options.
Command Line Parameter Types
Command line parameters are individual "words", or patterns of characters separated by white space. Each individual parameter is recognized by the command line lexical analyzer as having a certain "pattern", and is thus assigned a parameter type, as described in the following sections. Parameters should be separated by one or more blanks, tabs, or (when reading from a response file) new line characters, and double quotation marks may be used on the command line to remove the special meaning from the operating system metacharacters. Although the host operating system may support the enclosing of command line parameters within double quotes (";") (known as "quoting"), the ALP command line parser also performs quote interpretation. This is necessary to properly interpret quoted parameters within @Filename response files, for which there is no built-in support provided by the default operating system command shell.
Parameter types are determined by looking at the first character of each individual "word". Options begin with a plus (+) or minus (-), and file names begin with any other legal file name character (as dictated by the operating system). A special case is a word beginning with the at sign (@) character, which signifies the beginning of the @Filename (read from a response file) directive.
Options
Options appear on the command line as mnemonic identifiers prefixed by either of the plus (+) or minus (-) characters, and must be separated from other command line parameters by at least one blank character. Case is not significant in option identifiers.
A single option may be specified more than once on the command line within a given scope; the last occurrence overrides all previous definitions within that scope unless the effect of the option is to collect information in a cumulative fashion. Options are not cumulative unless documented otherwise on an individual basis.
There are two forms of options:
- Switch Option
- Parameterized Option
Some options may actually combine both functions of the switched and parameterized variations; for instance, the +Fl switch option "turns on" the creation of a listing file, while a parameterized option of the same name (for example, +Fl:george.lst) has the same effect, but also treats the argument field as the name of the listing file to create.
Switch Option
Switch Options represent a Boolean value (on or off, yes or no, true or false) for the identifier specified in the option. The plus (+) or minus (-) character introducing the option specifies the value of the switch; "+" is equivalent to on, yes, or true; and "-" is equivalent to off, no, or false.
Because plus (+) is not a character traditionally used to introduce a command line option, ALP provides an alternate method of specifying a switch option that resembles a more commonly used syntax. The character that affects the actual value of the "switch" (that is, the (+) or (-) character) may also be specified directly after the option identifier; in this case the option must still be introduced by either the (+) or (-) character, but the trailing "switch value" takes precedence.
The following are examples of Switch Options:
+ML -ml+ +Fl -Fl-
Parameterized Option
Parameterized Options are introduced in the same manner as switch options, but are instead followed by a colon (:) or an equals sign (=) (with no intervening blank space) to indicate that the option takes one or more arguments. The format of the argument field is option specific.
Using the plus (+) character versus the minus (-) character to introduce a parameterized option may or may not have an effect upon how the option is interpreted. Refer to the description of each individual option for details.
The following are examples of Parameterized Options:
-Fl=Zappa.lst -Sv:M510 +fo="\obj\dd\driver.obj" -m:127-
File Names
A file name may be used as an argument to certain command line options or as a stand-alone command line parameter. The file name character set and naming conventions are operating system dependent, and are treated as transparently as possible by ALP. The use of operating system metacharacters in file names should be avoided, and file names should not begin with the plus (+) or minus (-) characters.
Any file name may be "qualified" with drive or path information as appropriate for the host operating system. ALP accepts both the forward slash (/) and the backward slash (\) as legal path name characters, as well as the colon (:) character. Care must be exercised however, because the underlying operating system may reject the usage of some of these characters.
Command Line Syntax
┌──────────────────────┐
│ │
>>──ALP──┬────────────────┬──┬───────────────┬────FileName File Options─┴──><
└─Global Options─┘ └─Group Options─┘
The assembler accepts one or more file names for processing. Each file name is taken to be the name of a source file to assemble; file names are not interpreted according to their file "type" or extension to determine if they are valid input files.
The OS/2 version of the assembler is enabled to accept wild-card characters (? and *) in file names, which emulates the UNIX ability to expand a single file name specification into a list of all files that match the wild -card pattern. The ? character matches any single file name character in the given position, and the * character matches any number of file name characters.
Global Options
Command line options fall into this category only if they apply to the assembler executable itself and not to any specified files. Options that request the display of assembler help messages fall into this category, as well as the option that controls display of the assembler banner.
Group Options
Command line options fall into this category if the settings they control can be applied to a list of multiple files within a given scope without causing ambiguities. Group options are useful for such operations as:
- Requesting a listing file be generated for all files within the group
- Specifying the target directory for all generated object files
- Controlling the display of warning and informational messages for all files within the group
Within a given scope (see #Command Line Scope Operator ()) the command line parser assigns the group classification to each option until the first source file name is encountered; group option settings are applied to all file names that follow within a given scope. After encountering the first source file name, options are assigned the file classification.
File Options
All options appearing to the right of a file name within a given scope (see #Command Line Scope Operator ()) are applied to that file only. File options take precedence over any settings inherited from previously encountered group options.
It should be noted that file names specified using wild-card characters and used in combination with file options may not yield the expected result; the file options will be applied only to the last file in the resulting wild-card expansion file name list.
Command Line Scope Operator ()
At any point on the command line, a new scope may be opened using the scope operator (). The scope operator effectively creates a new logical command line whose contents are enclosed in parentheses and is parsed in isolation from other scopes. Any group options in effect at the time the new scope is opened are inherited and applied to all files named within.
Command Line Options
This section describes all the ALP command line options. For each option, a table appears in the description section with the following format:
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
The values appearing in this table are defined as follows:
- Type
- This field specifies the type of the option described in that row, and can be one of:
- S - #Switch Option
- P - #Parameterized Option
- Global
- Specifies whether or not the option is valid only in a global context; that is, in the outermost scope on the command line. These options typically have meaning only for the assembler executable itself, and not for any files to be processed.
- Group
- Specifies whether or not the option is valid in a group context; that is, if the option may be applied to multiple files within a given scope without causing ambiguities.
- File
- Specifies whether or not the option is valid only in a file context; that is, if the option may only be applied to a single file within a given scope.
- Default
- This field shows the default value for the option being described.
Base Options
This section describes the standalone base options that are defined by a single unique mnemonic identifier character.
D - Define Text Macro
This option allows the definition of a symbolic identifier that becomes visible during the assembly of the input file. A single parameter must be specified using one of the following forms:
Name[=Value] Name[:Value]
The Name entry must have the same lexical syntax as a normal assembler Identifier. The Nameentry is converted to a Text-EquateName before assembly begins. If no explicit value is specified for the name, then it is assigned the empty string. This is equivalent to specifying the following assembler statement:
Name EQU < >
If an explicit value is to be assigned, the Name entry must be immediately followed by a colon (:) or equals sign (=) delimiter with no intervening spaces. Blank characters may be specified between the delimiter and the value field. The Valuefield may contain any text data, but it must be enclosed in double quotes (";") if it contains blanks, tabs, or operating system metacharacters (such as & or |).
- Note
- If quotes are used to specify a value containing embedded blanks or tabs, then at least one blank is required between the delimiter (colon or equals sign) and the opening quote of the value field. For example:
-D:NAME= "This string will be correctly interpreted" -D:NAME="This will not; no blank after the equals sign"
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | (no default value) |
I - Specify Include File Search Path
See Fdi - Specify Include File Search Path.
File Control Options
All options that perform file or file name manipulation are described in this section. File Control Options begin with the letter "F", and the last letter of the option identifier specifies the type of file or file name to which the option applies as follows:
- i Include File
- l Listing File
- m Messages File
- o Object File
- s Source File
Fl - Produce Listing File
Turn this flag on to produce an assembler listing file. Using the parameterized version of the option allows the listing file to be explicitly named.
Only this option controls the actual creation of a listing file; Listing Control Options have no effect if this option has not been turned on.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Fl (no listing file is generated) |
| P | No | No | Yes | -Fl:<LstDIR><LstNAME>[<LstEXT>] (A listing file name is generated using the values of the referenced internal variables. The LstEXT extension is appended if this feature is turned on. |
Fm - Produce Messages File
Turn this flag on to produce a messages file. Using the parameterized version of the option allows the messages file to be explicitly named.
Within the context of a given assembly, by default all error, warning, and informational messages are printed to the standard output device. Use of the Fm option allows these messages to be redirected to a separate file; this can be useful when dissecting the output from multiple assemblies. Messages with a severity greater than Error are printed to the standard error device, and do not appear in the messages file.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Fm (no messages file is generated; all messages are printed on the standard output) |
| P | No | No | Yes | -Fm:<MsgDIR><MsgNAME>[<MsgEXT>] (A messages file name is generated using the values of the referenced internal variables. The MsgEXT extension is appended if this feature is turned on. |
Fo - Produce Object File
An object file name is generated using the values of the referenced internal variables. The #ObjEXT extension is appended if this feature is turned on.
By default, this switch is turned on and thus an object file is produced (provided the assembly completes without errors); this switch may be turned off if an object file is not desired. Using the parameterized version of the option allows the object file to be explicitly named.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Fo (an object file is generated) |
| P | No | No | Yes | -Fo:<ObjDIR><ObjNAME>[<ObjEXT>] |
Fdi - Specify Include File Search Path
This option accepts a path (or list of paths separated by semicolons) that are searched by the assembler while attempting to locate an INCLUDE file. When multiple occurrences of this option are specified within a given scope, the effect is cumulative rather than destructive; successive occurrences add to the existing list rather than overwriting previous definitions. The more conventional spelling "I" can be used as an alias for the Fdi option.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Fdi:<IncDIR> |
Fdl - Directory to Store Listing File (LstDIR)
This option affects the LstDIR variable and allows the user to specify a target directory where the listing file(s) will be stored; by default this variable is empty and listing file(s) are created in the current working directory. This value is ignored if the Fl option was used to explicitly name the listing file, and the name included absolute or relative path information.
If the value specified in this option is anything other than an unadorned drive letter (for example, D:) or a string ending with a path separator character (/ or \), then the path separator character appropriate for the underlying operating system is appended to the string.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Fdl:<LstDIR> |
Fdm - Directory to Store Messages File (MsgDIR)
This option affects the #MsgDIR variable and allows the user to specify a target directory where the messages file(s) will be stored; by default this variable is empty and messages file(s) are created in the current working directory. This value is ignored if the Fm option was used to explicitly name the message file, and the name included absolute or relative path information.
If the value specified in this option is anything other than an unadorned drive letter (for example, D:) or a string ending with a path separator character (/or \), then the path separator character appropriate for the underlying operating system is appended to the string.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Fdm:<MsgDIR> |
Fdo - Directory to Store Object File (ObjDIR)
This option affects the #ObjDIR variable and allows the user to specify a target directory where the object file(s) will be stored; by default this variable is empty and object file(s) are created in the current working directory. This value is ignored if the Fo option was used to explicitly name the object file, and the name included absolute or relative path information.
If the value specified in this option is anything other than an unadorned drive letter (for example, D:) or a string ending with a path separator character (/or \), then the path separator character appropriate for the underlying operating system is appended to the string.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Fdo:<ObjDIR> |
Fds - Directory to Locate Source File (SrcDIR)
This option affects the #SrcDIR variable and allows the user to specify a source directory from which source file(s) will be loaded; by default this variable is empty and source file(s) are searched for in the current working directory. This value is ignored if the source file name included absolute or relative path information.
If the value specified in this option is anything other than an unadorned drive letter (for example, D:) or a string ending with a path separator character (/or \), then the path separator character appropriate for the underlying operating system is appended to the string.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Fds:<SrcDIR> |
Fei - Control Include File Extension (IncEXT)
This option determines whether or not the value of the #IncEXT variable is appended to file names generated by the preprocessor when processing the INCLUDE directive. The parameterized version of this option affects the actual value of the #IncEXT variable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Fei (the value of IncEXT is not appended to include file names) |
| P | Yes | Yes | Yes | -Fei:<IncEXT> |
Fel - Control Listing File Extension (LstEXT)
This option determines whether or not the value of the #LstEXT variable is appended to listing file names. The parameterized version of this option affects the actual value of the LstEXT variable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Fel (the value of LstEXT is appended to listing file names) |
| P | Yes | Yes | Yes | +Fel:<LstEXT> |
Fem - Control Messages File Extension (MsgEXT)
This option determines whether or not the value of the #MsgEXT variable is appended to messages file names. The parameterized version of this option affects the actual value of the MsgEXT variable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Fem (the value of MsgEXT is appended to messages file names) |
| P | Yes | Yes | Yes | +Fem:<MsgEXT> |
Feo - Control Object File Extension (ObjEXT)
This option determines whether or not the value of the #ObjEXT variable is appended to object file names. The parameterized version of this option affects the actual value of the ObjEXT variable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Feo (the value of ObjEXT is appended to object file names) |
| P | Yes | Yes | Yes | +Feo:<ObjEXT> |
Fes - Control Source File Extension (SrcEXT)
This option determines whether or not the value of the #SrcEXT variable is appended to source file names. The parameterized version of this option affects the actual value of the SrcEXT variable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Fes (the value of SrcEXT is appended to source file names) |
| P | Yes | Yes | Yes | +Fes:<SrcEXT> |
Listing Control Options
This section describes all options related to controlling the content of the assembler listing file. All listing control options begin with the letter "L".
Options that manipulate the characteristics of individual listing file columns reference a particular column by having a single character mnemonic identifier as part of the option identifier. Listing column mnemonics are as follows:
- C Conditional assembly nesting level
- is a numeric value that appears during processing of a conditional assembly directive and is incremented for each level of nesting that occurs.
- D Macro definition line number
- tracks line numbers for each new MACRO definition introduced into the assembly.
- F True or false conditional flag
- appears during processing of a conditional assembly directive and is either a plus (+) character to denote that the conditional expression was TRUE and tokens appearing within the block are being interpreted, or a minus (-) character to denote that the conditional expression was FALSE and tokens appearing within the block are being ignored.
- G Generated machine code data
- column shows the hexadecimal values for data generated by machine instructions or data allocation statements.
- I Include file nesting level
- is a numeric value that appears during processing of INCLUDE files and is incremented for each level of nesting that occurs.
- L Macro expansion indentation level
- is a text field whose width reflects the current nesting level of expanded macros, and whose value contains a simulated "arrow"; using the "--->" characters.
- M Macro expansion nesting level
- is a numeric value that appears during macro expansions and is incremented for each level of nesting that occurs.
- O Location counter offset value
- is a numeric value displayed in hexadecimal notation and indicates the current offset of the location counter within the current segment or structure.
- S Source line data
- column contains the text data of the current line in the input source file.
- X Cumulative listing line number
- is incremented for every new line that appears in the listing file.
- Y Individual source file line number
- tracks line numbers for the top-level source file and for each separate INCLUDE file.
- Z Macro expansion line number
- tracks the current line number for each MACRO expanded during the assembly.
Lc* - Control Display of Individual Columns
This family of options controls whether or not an individual column physically appears in the listing file. The display of each column may be controlled with a switch option by using the standard ON (+) or OFF (-) switch values (see #Switch Option) or by using the parameterized option syntax (see #Parameterized Option) with one of the following keyword values in the argument field:
- B
- Abbreviation for BLANK.
- BLANK
- The column will appear as a place-holder in the listing file, but the column data will not be displayed.
- OFF
- The column will not be displayed.
- ON
- The column will be displayed.
- Z
- Abbreviation for ZBLANK.
- ZBLANK
- The column data will only display if its value is nonzero (valid only for numeric fields).
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +LcX (display Cumulative Listing Line Number) |
| S | Yes | Yes | Yes | +LcY (display Individual Source File Line Number) |
| S | Yes | Yes | Yes | -LcZ:Z (display Macro Expansion Line Number if not zero) |
| S | Yes | Yes | Yes | -LcD:Z (display Macro Definition Line Number if not zero) |
| S | Yes | Yes | Yes | +LcL (display Macro Expansion Indentation Level) |
| S | Yes | Yes | Yes | -LcM:Z (display Macro Expansion Nesting Level if not zero) |
| S | Yes | Yes | Yes | -LcI:Z (display Include File Nesting Level if not zero) |
| S | Yes | Yes | Yes | +LcC (display Conditional Assembly Nesting Level) |
| S | Yes | Yes | Yes | +LcF (display True or False Conditional Flag) |
| S | Yes | Yes | Yes | +LcO (display Location Counter Offset Value) |
| S | Yes | Yes | Yes | +LcG (display Generated Machine Code Data) |
| S | Yes | Yes | Yes | +LcS (display Source Line Data) |
Lcm* - Specify Left Margin for Individual Columns
This family of options specifies the left margin value for each individual column, which determines the number of blank spaces that will appear to the left of the column data.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -LcmX:0 (Cumulative Listing Line Number) |
| P | Yes | Yes | Yes | -LcmY:1 (Individual Source File Line Number) |
| P | Yes | Yes | Yes | -LcmZ:1 (Macro Expansion Line Number) |
| P | Yes | Yes | Yes | -LcmD:1 (Macro Definition Line Number) |
| P | Yes | Yes | Yes | -LcmL:0 (Macro Expansion Indentation Level) |
| P | Yes | Yes | Yes | -LcmM:1 (Macro Expansion Nesting Level) |
| P | Yes | Yes | Yes | -LcmI:1 (Include File Nesting Level) |
| P | Yes | Yes | Yes | -LcmC:1 (Conditional Assembly Nesting Level) |
| P | Yes | Yes | Yes | -LcmF:1 (True or False Conditional Flag) |
| P | Yes | Yes | Yes | -LcmO:2 (Location Counter Offset Value) |
| P | Yes | Yes | Yes | -LcmG:2 (Generated Machine Code Data) |
| P | Yes | Yes | Yes | -LcmS:2 (Source Line Data) |
Lct* - Specify Truncation of Individual Columns
This family of options specifies whether or not the data contained within an individual column will be truncated if it exceeds the column width, or whether it will overflow onto additional lines until the entire column contents have been printed.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +LcmX (truncate Cumulative Listing Line Number) |
| S | Yes | Yes | Yes | +LcmY (truncate Individual Source File Line Number) |
| S | Yes | Yes | Yes | +LcmZ (truncate Macro Expansion Line Number) |
| S | Yes | Yes | Yes | -LcmD (do not truncate Macro Definition Line Number) |
| S | Yes | Yes | Yes | -LcmL (do not truncate Macro Expansion Indentation Level) |
| S | Yes | Yes | Yes | +LcmM (truncate Macro Expansion Nesting Level) |
| S | Yes | Yes | Yes | +LcmI (truncate Include File Nesting Level) |
| S | Yes | Yes | Yes | +LcmC (truncate Conditional Assembly Nesting Level) |
| S | Yes | Yes | Yes | +LcmF (truncate True or False Conditional Flag) |
| S | Yes | Yes | Yes | -LcmO (do not truncate Location Counter Offset Value) |
| S | Yes | Yes | Yes | -LcmG (do not truncate Generated Machine Code Data) |
| S | Yes | Yes | Yes | +LcmS (truncate Source Line Data) |
Lcw* - Specify Width of Individual Columns
This family of options specifies the width of each individual listing column in single character positions. Note that the width of column L (Macro Expansion Indentation Level) will vary according to the macro expansion nesting level (which is also displayed as a numeric value in column M) if the nesting level value exceeds the column width. This behavior may be avoided by setting the width of column L such that its width never exceeds the value of column M, or by turning off the display of column L altogether.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -LcmX:4 (Cumulative Listing Line Number) |
| P | Yes | Yes | Yes | -LcmY:4 (Individual Source File Line Number) |
| P | Yes | Yes | Yes | -LcmZ:3 (Macro Expansion Line Number) |
| P | Yes | Yes | Yes | -LcmD:3 (Macro Definition Line Number) |
| P | Yes | Yes | Yes | -LcmL:0 (Macro Expansion Indentation Level) |
| P | Yes | Yes | Yes | -LcmM:2 (Macro Expansion Nesting Level) |
| P | Yes | Yes | Yes | -LcmI:2 (Include File Nesting Level) |
| P | Yes | Yes | Yes | -LcmC:2 (Conditional Assembly Nesting Level) |
| P | Yes | Yes | Yes | -LcmF:1 (True or False Conditional Flag) |
| P | Yes | Yes | Yes | -LcmO:4 (Location Counter Offset Value) |
| P | Yes | Yes | Yes | -LcmG:24 (Generated Machine Code Data) |
| P | Yes | Yes | Yes | -LcmS:90 (Source Line Data) |
Lc - Control display of false Conditional blocks
This switch determines whether or not sections of source code appear in the listing file when they are rendered inactive by a false conditional expression. By default, the assembler does not show source code in the listing file if it is skipped during conditional processing; turn this switch on if listing of all source code is desired.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Lc (do not list false conditional blocks) |
Ld - Control Display of Listing Directives
This switch controls whether or not assembler listing directives appear in the listing output. Listing directives are shown by default; turn this switch off to hide them.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Lc (show all listing directives) |
Le - Control Display of Error/Warning/Info Messages
By default, any time the assembler prints an Error, Warning, or Info message during the assembly, the message also appears in the listing file following the source line to which it refers. Turn this switch off if such messages are not desired in the listing output.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Le (show messages in listing file) |
Lf - Control Use of FormFeed Characters
When the assembler is generating formatted listing output and it needs to advance to the next page, it inserts the ASCII FormFeed character (0x0C) into the listing output stream. If this causes problems, turning this switch off will instead cause the assembler to generate the appropriate number of newline character sequences to perform the page eject operation.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Lf (the FormFeed character is used) |
Li - Control Display of INCLUDE Files
When the assembler processes source code stored in an INCLUDE file, by default the contents of the file are expanded in the listing output; depending on the types of files that are included, this behavior can result in large volumes of listing output. Turn this switch off if the expansion is not desired.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Li (INCLUDE files are expanded in listing output) |
Llp - Specify Length of Page
To correctly format the listing file for subsequent hardcopy output, the assembler must know how many physical lines of output will fit vertically on the printed page. This setting is especially important if the use of FormFeed characters has been turned off with the Lf option. The default value for this option is 66 lines per page.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Llp:66 (the default page length is 66 lines) |
Related Information:
Lm - Control Display of Macro Expansions
This switch controls whether or not the text body of an expanded macro appears in the listing output. While turning this switch on can be very useful when debugging macros, it can also result in large volumes of listing output if many macros are utilized. By default, macro expansions do not appear in the listing output; turn this switch on if this behavior is desired.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Lm (macro expansions do not appear in listing output) |
Lmb - Specify Bottom Margin
This option determines how many blank lines will appear at the bottom of the page in the listing output; by default this value is 4. The correct behavior of this option depends on the setting of the Llp and Lf options, and that they match the settings of the physical output device. If there are problems with these settings, then the actual bottom margin may not appear to correctly reflect the value of this option.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lmb:4 (4 blank lines at bottom of page) |
Related Information:
- #Lf - Control Use of FormFeed Characters
- #Llp - Specify Length of Page
- #Lmb - Specify Middle Margin after Title
- #Lmt - Specify Top Margin before Title
Lml - Specify Left Margin
This option specifies the number of blank characters that are printed to the left of every line of listing output. The default value for this option is 4.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lml:4 (left margin is 4 blank characters wide) |
Related Information:
- #Lmr - Specify Right Margin
- #Lwp - Specify Width of Page
- #Lcm* - Specify Left Margin for Individual Columns
Lmb - Specify Middle Margin after Title
This option specifies the number of blank lines that separate the assembler heading, the title and subtitle (if there are any), from both the column ruler (if there is one) and the body of the generated listing text. The default value for this option is 2 blank lines.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lmm:2 (2 blank lines after title and subtitle, and before ruler line) |
Related Information:
- #Llp - Specify Length of Page
- #Lmb - Specify Bottom Margin
- #Lmt - Specify Top Margin before Title
- #Lr - Control Display of Column Ruler
Lmr - Specify Right Margin
This option specifies the number of blank characters that are reserved (but not actually printed) to the right of every line of listing output. The default value for this option is 4.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lmr:4 (right margin is 4 blank characters wide) |
Related Information:
- #Lml - Specify Left Margin
- #Lwp - Specify Width of Page
- #Lcm* - Specify Left Margin for Individual Columns
Lmt - Specify Top Margin before Title
This option specifies the number of blank lines that appear at the top of the page before any other listing output is generated. The default value for this option is 2 blank lines.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lmt:2 (2 blank lines at the top of the page) |
Related Information:
Lp - Generate Listing on Specific Pass
This option allows the user to control whether or not listing information is generated on a specific pass of the assembler. By default, the assembler only generates listing information on pass two. If the user is encountering "phase errors" or other unusual situations, it may be helpful to request a listing for the first pass as well.
The arguments to this option are either a series of numeric digits (without intervening white space) or the ALL or NONE keywords. In the default assembler configuration, use of the -Lp:ALL form is equivalent to specifying -Lp:12, because the assembler makes two passes through the source file by default. The NONE keyword prevents generation of any pass-related information in the listing file; however, symbol table information will still appear if selected.
When using numeric digits to specify the desired pass numbers, a listing will only be generated for the numbers given in the argument field; the default setting (or settings given by previous occurrences of the option) will be discarded.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lp:2 (listing on pass 2 only) |
Lr - Control Display of Column Ruler
This switch to determines whether or not the column ruler appears at the top of each page in the listing output. This ruler is simply a line of information containing a string of alphabetic characters corresponding to each vertical column of listing information. The ruler reflects the current width, margins, and placement of the various listing columns at the time each page is printed, and helps the user to determine which column they are looking at. Turn this switch off if display of the column ruler is not desired.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Lr (show the column ruler in listing output) |
Ls - Control Display of Symbol Table
This switch determines whether or not a summary of the symbol table contents is included at the end of the listing file. The default behavior is to omit the symbol table summary; turn this switch on to include it.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Ls (do not include symbol table in listing output) |
Lt1 - Specify Title
This option allows the user to specify the text of a default title to be printed at the top of each listing page; there is no default title. Title information must be enclosed in double quotes "" if it contains white space characters.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lt1:<empty> (no default title information) |
Lt2 - Specify Subtitle
This option allows the user to specify the text of a default subtitle to be printed at the top of each listing page; there is no default subtitle. Subtitle information must be enclosed in double quotes "" if it contains white space characters.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lt2:<empty> (no default subtitle information) |
Lwp - Specify Width of Page
To correctly format the listing file for subsequent hardcopy output, the assembler must know how many physical characters of output will fit horizontally on the printed page. The default value for this option is 132 character positions.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lwp:132 (the default page width is 132 character positions) |
Related Information: #Lcm* - Specify Left Margin for Individual Columns #Lcw* - Specify Width of Individual Columns
Lwt - Specify Tab Expansion Width
This option specifies the width of a tab character in blank spaces. Tab characters appearing in the source file are always expanded into blank spaces when output to the listing file; the default behavior is to expand tab characters to every eighth character position.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Lwt:8 (tab characters are 8 character positions wide) |
Message Control Options
This section describes all options related to the output and control of assembler messages. All Message Control Options begin with the letter "M".
M - Control Individual Messages or Groups
This option controls the types of messages that are displayed by manipulating message group identifier flags or individual message numbers. Only messages with a severity of Warning or Info are controllable with this option. Messages with a severity of Error, System, Fatal, Internal, or Usage cannot be suppressed.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -M:W+ (all warning messages are enabled) |
All assembler messages are assigned a unique message number, and Warning or Info messages may belong to one or more message groups. The message group identifier flags are defined as follows:
- ALL All warning and informational messages
- BLK Messages regarding block structure violations
- COD Messages regarding code generation
- FIL File manipulation messages
- I All informational messages
- PP Preprocessor messages
- SRC Source file lexical analyzer messages
- STA Assembly statistics
- W All warning messages
Any sequence of message groups or message numbers may be specified in the argument field of the M option; each argument must be followed by a plus (+) or minus (-) character to turn the value on or off, and no intervening white space characters may appear between arguments.
See #Assembler Messages for more information on message number values and the messages groups to which they belong.
Mb - Control Printing of the Assembler Banner
This switch controls whether or not the assembler start-up banner is printed. This switch is on by default; turn it off to suppress display of the banner.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | No | No | +Mb (Print the assembler banner) |
Me - Set Number of Errors Before Assembler Aborts
This option specifies the maximum number of errors that the assembler will tolerate before ending the assembly. The default value is 50.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | -Me:50 (abort the assembly after 50 errors are encountered) |
Mwe - Treat Warnings as Errors
This switch tells the assembler that any Warning messages are to be treated as though they were errors; this causes the assembler to end with a non-zero exit code, and helps prevent any warning conditions from "passing by" unnoticed.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Mwe (warnings are not considered to be errors) |
Object Control Options
This section describes all options related to the output and control of object file information. All Object Control Options begin with the letter "O".
Od - Line Number and Symbolic Debug Information in Object File
This switch controls whether or not all forms of debug information are included in the object file, and is a shorthand method of specifying the options to control line numbering and symbolic debug information.
The parameterized version of this option may be used to specify the format of the debugging information. The setting of this value may be necessary depending on which linker is used to link the object file output, or on the debugger used to debug the executable. The argument must be one of the following keywords:
- IBM32 Generate debugging information in the 32-bit IBM (HLL) format. Executable code that is to be debugged with the IBM family of debuggers should use this setting. This is the default value if no parameter is specified.
- MS16 Generate debugging information in the 16-bit Microsoft (CodeView) format. You may need to use this setting if the object file output will be processed by a 16-bit linker, or if non-IBM debuggers will be utilized on the executable.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | (see default values for Ods and Odl) |
| P | Yes | Yes | Yes | -Od:IBM32 (use the IBM debug format) |
Related Information:
Odl - Line Numbering Information in Object File
This switch controls whether or not line numbering debug information is included in the object file, thus allowing the assembler source file to be viewed from within a source-level debugger.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Odl (line numbering debug information is not included in object file) |
Ods - Symbolic Debug Information in Object File
This switch controls whether or not symbolic debug information is included in the object file, thus allowing variables, labels, and expressions appearing in the assembler source file to be viewed from within a source-level debugger.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Ods (symbolic debug information is not included in object file) |
Oug - Convert Global Identifiers to Uppercase
This switch controls whether external identifiers (declared with the EXTERN directive) and public identifiers (declared with the PUBLIC directive) are converted to uppercase before writing them to the object file. By default, no conversion is performed and the symbols are written to the object file exactly as they were entered into the symbol table during assembly.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Oug (do not convert global identifiers to uppercase in object file) |
Related Information:
- #Scs - Control Case Sensitivity for Symbol Names
- #Ous - Convert Group and Segment Names to Uppercase
Ous - Convert Group and Segment Names to Uppercase
This switch controls whether external group names (declared with the GROUP directive) and segment names (declared with the SEGMENT directive) are converted to uppercase before writing them to the object file. By default, no conversion is performed and the names are written to the object file exactly as they were entered into the symbol table during assembly.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Ous (do not convert group or segment names to uppercase in object file) |
Related Information:
Source Control Options
All options related to parsing or processing the input source stream are described in this section. All Source Control Options begin with the letter "S".
Sc - Control Case Sensitivity for All Identifiers
This switch controls whether or not all identifiers are case sensitive, and is a shorthand method of specifying the options for user identifiers and keywords.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | (see default values for Sck and Scs) |
Related Information:
Sck - Control Case Sensitivity for Keywords
This switch controls whether or not language keywords are case sensitive. By default, this flag is turned off; thus the spellings SEGMENT, Segment, and segment all refer to the same keyword. Turning this switch on would render the three spellings separate and distinct, and only the uppercase variant would be recognized as a keyword.
This option has no effect on user identifiers (see #Scs - Control Case Sensitivity for Symbol Names) or processor mnemonics.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Sck (All language keywords are case insensitive) |
Scs - Control Case Sensitivity for Symbol Names
This switch controls whether or not user identifiers are case sensitive. By default, this flag is turned on; thus the identifiers GEORGE, George, and george are separate and distinct. Turning this switch off would cause the three spellings to refer to the same identifier.
If a case-insensitive assembly is being performed (-Scs), the actual spelling of the identifier is not altered (e.g., converted to uppercase) when it is entered into the symbol table. The actual symbol definition controls the spelling of the identifier regardless of whether or not a case-insensitive assembly was performed. The only exception to this rule is when processing a PUBLIC directive under MASM 5.10 emulation; the identifier spelling, which appears in the PUBLIC directive is honored over the one appearing in the actual identifier definition.
This option has no effect on language keywords (see #Sck - Control Case Sensitivity for Keywords), processor mnemonics, or register names.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | +Scs (All user identifiers are case sensitive) |
Related Information:
Sk - Control Use of Reserved Words as Labels
This switch controls whether or not certain assembler keywords (reserved words) may be used in the context of a code label (for example, TEST:). By default, this switch is off, and keywords may not be used as labels.
Even when this switch is turned on, there are severe restrictions on this capability. Processor mnemonics classify as the only "keywords" allowed in this situation, and only in the context of a code label (a label followed by a colon); using any reserved word as a directive name or data label is illegal.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Sk (Reserved words may not be used as labels) |
Sfs - SHORT is Default Distance for Forward-Referenced Jumps
By default, when the assembler encounters an unqualified forward reference as the operand to a jump instruction, it makes a worst-case assumption that the target will not be close enough to allow generating the SHORT variation of the instruction. Enough space is reserved to generate the NEAR version, and if it is determined later that the target is close enough, the SHORT variation is generated and extra space is padded with NOP instructions. This helps insure that source files will assemble without "out of range" errors, but wastes space when the NOP instructions are generated.
Turning this switch on causes the assembler to assume that unqualified forward referenced jumps will always be reachable with the SHORT instruction variation; should this not be the case, an error is generated and the user may recode the instruction using the NEAR override.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Sfs (default distance is NEAR) |
Sme - Control Visibility of MASM 6.00 Extended Mnemonics
This option controls whether or not the following processor mnemonics are recognized as keywords:
FLDENVD FLDENVW FNSAVED FNSAVEW FNSTENVD FNSTENVW FRSTORD FRSTORW FSAVED FSAVEW FSTENVD FSTENVW IRETF IRETDF LOOPD LOOPW LOOPED LOOPEW LOOPNED LOOPNEW LOOPNZD LOOPNZW LOOPZD LOOPZW POPD POPW PUSHD PUSHW
These mnemonics were introduced in MASM 6.00 to allow explicit word (16-bit) or double-word (32-bit) operations on 80386 or newer processors. Although MASM 5.10 supports the 80386 processor, it does not recognize these keywords. To avoid conflicts with preexisting macro libraries, ALP will also refuse to recognize these keywords when operating under MASM 5.10 compatibility mode (-Sv:M510) unless this option is turned on. This option is turned on automatically when the -Sv:M600 option is used.
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| S | Yes | Yes | Yes | -Sme (extended mnemonics are not enabled) |
Related Information:
Sv - Set Version Behavior
This option controls the various modes of compatibility that the assembler is designed to emulate. The argument to the Svoption must be one of the following keywords:
- ALP Native operating mode; don't emulate other assemblers
- M510 Emulate Microsoft MASM Version 5.10
- M600 Emulate Microsoft MASM Version 6.00
| Type | Global | Group | File | Default |
|---|---|---|---|---|
| P | Yes | Yes | Yes | +Sv:ALP (do not emulate other assemblers) |
Related Information:
The MASM2ALP Utility
MASM2ALP is a utility that accepts a MASM 5.10-compatible command line, transforms the command line parameters to the appropriate ALP syntax, and invokes alp.exeto perform the assembly. This allows the use of ALP instead of MASM in existing build environments without requiring major changes to makefiles or build scripts. You simply replace your existing MASM executable with MASM2ALP and resume operations.
MASM2ALP accepts the following MASM 5.10-style command line syntax:
masm2alp [Options] SourceFile [,[ObjectFile][,[ListingFile][,[CrossRefFile]]]] [;]
- Notes
- Options are normally specified first on the command line, but may appear anywhere before the optional semicolon (;) terminator. Options may begin with either a slash (/) or a dash (-), but once the first option is encountered, no further mixing of introductory characters is allowed. Options are not case sensitive. Individual command line options are discussed below.
- Filename arguments are position-dependent. Commas (,) must be used to separate each argument and to maintain argument position, both when arguments are explicitly specified or when they are skipped (left unspecified). The filename argument descriptions are as follows:
- SourceFile This argument is mandatory, and specifies the name of the assembly language source file to be processed. If no filename suffix is supplied, a default value of ".asm" is assumed.
- ObjectFile The optional name of the object-code output file to be produced. If no filename suffix is supplied, a default value of ".obj" is assumed. If no ObjectFile argument is given, the root portion of the SourceFileargument is used as the name of the object file.
- ListingFile The optional name of the listing output file to be produced. If no filename suffix is supplied, a default value of ".lst" is assumed. If no ListingFile argument or -L option is given, then no listing file is produced; otherwise the root portion of the SourceFile argument is used as the name of the listing file.
- CrossRefFile The optional name of the cross-reference output file. Since ALP does not support the creation of a cross-reference file, MASM2ALP ignores this argument.
- The trailing semicolon (;) operator may be used when no more filename arguments are to be specified and the default values are to be utilized for the remaining arguments. Any arguments or command line options that follow the semicolon will be ignored.
- MASM2ALP does not support the "prompting" behavior of Microsoft MASM when insufficient command line arguments are supplied. A syntax error is issued in this event.
Options:
MASM2ALP accepts the following command line options:
-A Forces MASM to write segments to the object file in alphabetical order. MASM normally writes segments in source code order. MASM2ALP ignores this option.
-B number Sets the size of the source file read buffer in 1K increments. MASM2ALP ignores this option.
-C Tells MASM to create a cross-reference file. MASM2ALP ignores this option.
-d Causes the assembler to generate listing file information during both pass 1 and 2. By default, the assembler only generates listing file information during pass 2.
-D symbol[=value] Defines a symbol visible during assembly. An optional text value may also be specified for the symbol.
-E Tells MASM to generate code compatible with floating-point emulation libraries. MASM2ALP ignores this option.
-H Prints the help information panel for the command line syntax.
-I path Specifies an INCLUDE file search path.
-L[A] Forces the creation of a listing output file. The -LAoption is an abbreviation for "list all", which forces macro expansions and false conditionals to also be included in the listing output.
- ML Directs the assembler to perform a case-sensitive assembly, and to preserve the case of external identifiers when writing them to the object file.
-MU Directs the assembler to perform a case-insensitive assembly, and to convert the names of external identifiers to uppercase when writing them to the object file. This is the default mode of operation for Microsoft MASM.
-MX Directs the assembler to perform a case-insensitive assembly, yet preserve the case of external identifiers when writing them to the object file.
-N Prevents the symbol table summary from being printed in the listing file .
-P Causes MASM to check for inpure code operations when assembling for a privileged mode processor. This feature is not supported by ALP, thus MASM2ALP ignores this option.
-S Forces MASM to write segments to the object file in source code order, nullifying the effects of any previously encountered -Aoption. MASM2ALP ignores this option.
-X Forces false conditionals to be included in the listing file output.
-Z Causes MASM to print the source line of any statement causing an assembly error to the standard output device. MASM2ALP ignores this option .
-ZD vCauses line number debugging information to be included in the object file output.
-ZI vCauses both line number and symbolic debugging information to be included in the object file output.