═══ 1. Version Notice ═══ First Edition (May 1995) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM authorized reseller or IBM marketing representative. (C) Copyright International Business Machines Corporation 1995. All rights reserved. Note to U.S. Government Users -- Documenation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 2. Notices ═══ References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 2.1. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries: C Set/2 IBM Operating System/2 OS/2 Presentation Manager The following terms are trademarks of other companies: Microsoft - Microsoft Corporation Pentium - Intel Corporation UNIX - UNIX System Laboratories, Inc. ═══ 3. Assembly Language Processor Overview ═══ Assembly Language Processor (ALP) is an assembler that runs under the 32-bit OS/2 operating system. In its intial form, ALP is designed as a functional replacement for the Microsoft Macro Assembler (MASM), and accepts the full syntax of the Intel 80X86 architecture, and a subset of MASM's high-level directive language. It generates standard Object Module Format (OMF) files that can be linked to produce DOS or OS/2 executables, and can generate line number debug information compatible with IBM's Presentation Manager Debugger. In addition, ALP offers a rich set of command line options, as well as a comprehensive listing file with user-tailored formatting, allowing a visual perspective not possible with other assemblers. ═══ 4. Installation ═══ This section describes how to install the assembler on a given host operating system. Since various methods may be used to distribute the assembler executable, refer to the documentation or README file accompanying the package for details on how to extract the files into the formats described in this section. ═══ 4.1. OS/2-Hosted Version of ALP ═══ The OS/2-hosted version of ALP consists of two files: alp.exe and alp.msg. The "root" portions of the two filenames may be renamed if so desired. In most cases, it does not matter whether the filenames are stored using uppercase or lowercase letters, since the default OS/2 file systems can reference the files irrespective of case. It is possible, however, that the use of an OS/2 Installable File System (IFS) might require that filenames be referenced exactly as they are stored with respect to uppercase and lowercase letters. If this is true, then the "root" portion of the alp.exe and alp.msg filenames (see BaseEXE) must be spelled identically and the .msg extension on the messages filename must be specified using lowercase letters, or the assembler will be unable to find the messages file at run time. The following steps are required to install the assembler executables on an OS/2 host operating system: 1. Copy alp.exe into a directory of your choice. If the assembler will be invoked from the command line (rather than by absolute reference from a makefile or command file), then (for ease of use) the selected directory should be among those referenced by the PATH environment variable. 2. For best performance, the alp.msg file should be copied into the same directory used to store alp.exe or in a directory referenced by the _PATH environment variable. It is not necessary to set any additional environment variables if the first method is used. Alternatively, a directory referenced by the DPATH environment variable may also be used, but performance may be degraded during initialization, since the assembler must search all of the listed directories for the alp.msg file. See The ALP Messages File for more information. 3. Optionally, default values for command line options may be established. See _OPTIONS for more information. ═══ 4.2. AIX-Hosted Version of ALP ═══ The AIX-hosted version of ALP consists of two files: alp and alp.msg. The "root" portions of the two filenames may be renamed if so desired, but they must be spelled identically and the .msg extension on the messages filename must be specified using lowercase letters, or the assembler will be unable to find the messages file at run time. The following steps are required to install the assembler executables on an AIX host operating system: 1. Copy alp into a directory of your choice, and use the chmod command to ensure that the executable attribute of the file has been set. If the assembler will be invoked from the command line (rather than by absolute reference from a makefile or command file), then (for ease of use) the selected directory should be among those referenced by the PATH environment variable. 2. For best performance, the alp.msg file should be copied into the same directory used to store alp or in a directory referenced by the _PATH environment variable. It is not necessary to set any additional environment variables if the first method is used. Alternatively, a directory referenced by the DPATH environment variable may also be used, but performance may be degraded during initialization, since the assembler must search all of the listed directories for the alp.msg file. See The ALP Messages File for more information. 3. Optionally, default values for command line options may be established. See _OPTIONS for more information. ═══ 5. Running ALP ═══ This section describes how to invoke ALP, how it behaves with respect to its environment, and how to pass information to ALP through command line parameters and environment variables. ═══ 5.1. The ALP Messages File ═══ One of the first tasks performed by ALP is a search for its own messages file. Nearly every message displayed by ALP at run time (including the program logo) is stored in a separate message file; the only exception to this rule is a short selection of messages that are displayed if the message file cannot be opened; ALP will abort if one of these messages is displayed. When ALP starts, it first determines the name of the message file; it does this by creating a name of the form BaseEXE.msg, where BaseEXE is the value of the BaseEXE internal variable (see BaseEXE for details). Once the name of the message file is established, the following method is used to locate it: 1. A search is made in the current directory. 2. The directory contained in the BasePATH internal variable is searched (if it is not undefined). 3. A search is made through each of the directories specified in the BaseEXE internal variable (if it is not undefined). 4. A search is made through each of the directories specified in the PATH environment variable (if it is not undefined). 5. A search is made through each of the directories specified in the DPATH environment variable (if it is not undefined). ═══ 5.2. Environment Variables ═══ This section describes the environment variables that are utilized by ALP. ═══ 5.2.1. _INCLUDE ═══ During the processing of an INCLUDE directive, the value of the BaseEXE internal variable is translated to uppercase and is used to construct the name of a ALP-specific environment variable having the form "_INCLUDE". For example, If the value of BaseEXE is "alp", then an environment variable called ALP_INCLUDE 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 INCLUDE environment variable. ═══ 5.2.2. _OPTIONS ═══ During assembler command line processing, the value of the BaseEXE internal variable is translated to uppercase and is used to construct the name of a ALP-specific environment variable having the form "_OPTIONS". For example, If the value of BaseEXE is "alp", then an environment variable called ALP_OPTIONS would be constructed and an attempt would be made to locate it in the environment. If found, its contents are logically prepended to the assembler command line. This variable may be used as a method of setting 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. ═══ 5.2.3. _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 a ALP specific environment variable having the form "_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. ═══ 5.2.4. DPATH ═══ The DPATH environment variable may be utilized for the same purposes as the _PATH internal variable if so desired. ═══ 5.2.5. INCLUDE ═══ The INCLUDE environment variable may be utilized for the same purposes as the _INCLUDE internal variable if so desired. ═══ 5.2.6. PATH ═══ The PATH environment variable may be utilized for the same purposes as the _PATH internal variable if so desired. ═══ 5.3. Internal Variables ═══ ALP maintains a set of internal variables that are used for various special purposes. In general, these variables are reflective of the ALP environment, and are not designed for direct manipulation by the ALP programmer. Their values may be indirectly affected by the user of ALP (for instance, through the use of various command line options), but there is no architected method for directly manipulating the values of internal variables. ═══ 5.3.1. BaseEXE ═══ When ALP is invoked, if the full pathname of the ALP executable was provided by the operating system, then the "base" portion is isolated and used to construct the value of the BaseEXE internal variable. For instance, if the user invoked ALP and the name of the executable was made available as "C:\TOOLS\ALP.EXE", then the BaseEXE internal variable would contain the value "ALP". The value of BaseEXE is used to differentiate ALP-specific components in the environment (such as data files or environment variables) from those that are globally accessible to all programs. Even multiple versions of ALP can coexist without environmental "collisions" simply by copying and renaming the ALP executable and its associated message file. If the filename of the ALP executable is not available at run time, then the value of BaseEXE defaults to "ALP". ═══ 5.3.2. BasePATH ═══ When ALP is invoked, if the full pathname of the ALP executable was provided by the operating system, then the "path" portion is isolated and used to construct the value of the BasePATH internal variable. For instance, if the user invoked ALP and the name of the executable was made available as "C:\TOOLS\ALP.EXE", then the BasePATH internal variable would contain the value "C:\TOOLS\". The value of BasePATH can be used to locate ALP-specific components in the environment (such as the ALP messages file) without the need to store this information in an alternate environment variable such as DPATH. Check your operating system documentation to see if it feasible to use the BasePATH method of locating ALP components. If the filename of the ALP executable is not available at run time, then the value of BasePATH is NULL. ═══ 5.3.3. IncDIR ═══ This variable contains the empty string unless explicitly initialized with the Fdi parameterized command line option; it contains the cumulative value of all the specified include paths. Related Information: o Options o Filenames o Fdi - Specify Include File Search Path ═══ 5.3.4. IncEXT ═══ The value of this variable contains the default include filename extension that is conditionally appended to unadorned filenames generated by the INCLUDE preprocessor directive. The default value for IncEXT is ".inc", unless altered by use of the Fei parameterized command line option. Related Information: o Options o Filenames o Fei - Control Include File Extension (IncEXT) ═══ 5.3.5. LstDIR ═══ This variable contains the empty string unless explicitly initialized with the Fdl parameterized command line option; it is only used if the value specified by the Fl command line option did not contain any path information. Related Information: o Options o Filenames o Fl - Produce Listing File o Fdl - Directory to Store Listing File (LstDIR) ═══ 5.3.6. LstEXT ═══ The value of this variable contains the default listing filename extension that is conditionally appended to the concatenated values of LstDIR and LstNAME; the assembler treats the resulting string as the fully qualified listing filename. The default value for LstEXT is ".lst", unless altered by use of the Fel parameterized command line option. Related Information: o Options o Filenames o Fel - Control Listing File Extension (LstEXT) ═══ 5.3.7. LstNAME ═══ This variable contains the same value as the contents of SrcNAME, unless initialized with the Fl parameterized command line option. Related Information: o Options o Filenames o Fl - Produce Listing File ═══ 5.3.8. MsgDIR ═══ This variable contains the empty string unless explicitly initialized with the Fdm parameterized command line option; it is only used if the value specified by the Fm command line option did not contain any path information. Related Information: o Options o Filenames o Fm - Produce Messages File o Fdm - Directory to Store Messages File (MsgDIR) ═══ 5.3.9. MsgEXT ═══ The value of this variable contains the default messages filename extension that is conditionally appended to the concatenated values of MsgDIR and MsgNAME; the assembler treats the resulting string as the fully qualified messages filename. The default value for MsgEXT is ".msg", unless altered by use of the Fem parameterized command line option. Related Information: o Options o Filenames o Fem - Control Messages File Extension (MsgEXT) ═══ 5.3.10. MsgNAME ═══ This variable contains the same value as the contents of SrcNAME, unless initialized with the Fm parameterized command line option. Related Information: o Options o Filenames o Fm - Produce Messages File ═══ 5.3.11. ObjDIR ═══ This variable contains the empty string unless explicitly initialized with the Fdo parameterized command line option; it is only used if the value specified by the Fo command line option did not contain any path information. Related Information: o Options o Filenames o Fo - Produce Object File o Fdo - Directory to Store Object File (ObjDIR) ═══ 5.3.12. ObjEXT ═══ This variable contains the default object filename extension that is conditionally appended to the concatenated values of ObjDIR and ObjNAME; the assembler treats the resulting string as the fully qualified object filename. The default value for ObjEXT is ".obj", unless altered by use of the Feo parameterized command line option. Related Information: o Options o Filenames o Feo - Control Object File Extension (ObjEXT) ═══ 5.3.13. ObjNAME ═══ This variable contains the same value as the contents of SrcNAME, unless initialized with the Fo parameterized command line option. Related Information: o Options o Filenames o Fo - Produce Object File ═══ 5.3.14. SourceNAME ═══ This internal variable contains the name of the top-level source file currently being processed by the assembler; its contents appear exactly as the user typed it on the command line. Other internal variables derive their contents from this value. Related Information: o Filenames ═══ 5.3.15. SrcDIR ═══ This variable is derived from SourceNAME and reflects any drive or path information contained therein. For instance, if the value of SourceNAME is "D:\Source\Dump\DumpMain.asm", then the value of SrcDIR would be "D:\Source\Dump\". If no drive or path information was specified in the filename, then SrcDIR will contain the empty string. Related Information: o Filenames ═══ 5.3.16. SrcEXT ═══ This variable contains the default source filename extension that is conditionally appended to the concatenated values of SrcDIR and SrcNAME; the assembler treats the resulting string as the fully qualified input filename. The default value for SrcEXT is ".asm", unless altered by use of the Fes parameterized command line option. Related Information: o Options o Filenames o Fes - Control Source File Extension (SrcEXT) ═══ 5.3.17. SrcNAME ═══ This variable contains the "root filename" portion of the source filename, which is extracted from the contents of the SourceNAME variable. For instance, if the value of SourceNAME is "D:\Source\Dump\DumpMain.asm", then the value of SrcNAME would be "DumpMain". SrcNAME should never contain the empty string unless the input filename was incorrectly specified; in which case the assembler will generate an error when it tries to access the file. Related Information: o Filenames ═══ 5.4. 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 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 filenames begin with any other legal filename 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. ═══ 5.4.1. 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. There are two forms of options: o Switch Option o 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. ═══ 5.4.1.1. 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. Since 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- ═══ 5.4.1.2. 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:MASM51 +fo="\obj\dd\driver.obj" -m:127- ═══ 5.4.2. Filenames ═══ A filename may be used as an argument to certain command line options or as a standalone command line parameter. The filename 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 filenames should be avoided, and filenames should not begin with the plus (+) or minus (-) characters. Any filename 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 pathname characters, as well as the colon (:) character. Care must be exercised however, since the underlying operating system may reject the usage of some of these characters. ═══ 5.5. Command Line Syntax ═══ ALP has the following command line invocation syntax: ┌───────────────────────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────────────────┐ │ │ │ │ │ │ >>──ALP──┬────────────────┬──┬───────────────┬────FileName File Options─┴──>< │ │ └─Global Options─┘ └─Group Options─┘ │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ The assembler accepts one or more filenames for processing. Each filename is taken to be the name of a source file to assemble; filenames 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 wildcard characters (? and *) in filenames, which emulates the UNIX ability to expand a single filename specification into a list of all files that match the wildcard pattern. The ? character matches any single filename character in the given position, and the * character matches any number of filename characters. ═══ 5.5.1. 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. ═══ 5.5.2. 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: o Requesting a listing file be generated for all files within the group o Specifying the target directory for all generated object files. o 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. ═══ 5.5.3. File Options ═══ All options appearing to the right of a filename 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 filenames specified using wildcard 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 wildcard expansion filename list. ═══ 5.5.4. Command Line Scope Operator () ═══ At any 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. ═══ 5.6. Command Line Options ═══ This section describes all the 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. ═══ 5.6.1. File Control Options ═══ All options that perform file or filename 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 filename to which the option applies as follows: i Include File l Listing File m Messages File o Object File s Source File ═══ 5.6.1.1. Fl - Produce Listing File ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Fl (no listing file is generated) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │No │No │Yes │-Fl:[] │ │ │ │ │ │(A listing filename is generated using the values │ │ │ │ │ │of the referenced internal variables. The LstEXT │ │ │ │ │ │extension is appended if this feature is turned │ │ │ │ │ │on.) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.1.2. Fm - Produce 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:[] │ │ │ │ │ │(A messages filename is generated using the values│ │ │ │ │ │of the referenced internal variables. The MsgEXT │ │ │ │ │ │extension is appended if this feature is turned │ │ │ │ │ │on.) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.1.3. Fo - Produce Object File ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Fo (an object file is generated) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │No │No │Yes │-Fo:[] │ │ │ │ │ │(An object filename 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. ═══ 5.6.1.4. Fdi - Specify Include File Search Path ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fdi: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option accepts a path (or list of paths separated by semicolons) that are searched by the assembler when it is unable to find an include file in the current directory. 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. ═══ 5.6.1.5. Fdl - Directory to Store Listing File (LstDIR) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fdl: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.1.6. Fdm - Directory to Store Messages File (MsgDIR) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fdm: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.1.7. Fdo - Directory to Store Object File (ObjDIR) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fdo: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.1.8. Fds - Directory to Locate Source File (SrcDIR) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fds: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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 filename 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. ═══ 5.6.1.9. Fei - Control Include File Extension (IncEXT) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Fei │ │ │ │ │ │(the value of IncEXT is not appended to include │ │ │ │ │ │filenames) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Fei: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option determines whether or not the value of the IncEXT variable is appended to filenames generated by the preprocessor when processing the INCLUDE directive. The parameterized version of this option affects the actual value of the IncEXT variable. ═══ 5.6.1.10. Fel - Control Listing File Extension (LstEXT) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Fel │ │ │ │ │ │(the value of LstEXT is appended to listing │ │ │ │ │ │filenames) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │+Fel: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option determines whether or not the value of the LstEXT variable is appended to listing filenames. The parameterized version of this option affects the actual value of the LstEXT variable. ═══ 5.6.1.11. Fem - Control Messages File Extension (MsgEXT) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Fem │ │ │ │ │ │(the value of MsgEXT is appended to messages │ │ │ │ │ │filenames) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │+Fem: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option determines whether or not the value of the MsgEXT variable is appended to messages filenames. The parameterized version of this option affects the actual value of the MsgEXT variable. ═══ 5.6.1.12. Feo - Control Object File Extension (ObjEXT) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Feo │ │ │ │ │ │(the value of ObjEXT is appended to object │ │ │ │ │ │filenames) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │+Feo: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option determines whether or not the value of the ObjEXT variable is appended to object filenames. The parameterized version of this option affects the actual value of the ObjEXT variable. ═══ 5.6.1.13. Fes - Control Source File Extension (SrcEXT) ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Fes │ │ │ │ │ │(the value of SrcEXT is appended to source │ │ │ │ │ │filenames) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │+Fes: │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option determines whether or not the value of the SrcEXT variable is appended to source filenames. The parameterized version of this option affects the actual value of the SrcEXT variable. ═══ 5.6.2. 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: X Cumulative Listing Line Number. This value is incremented for every new line that appears in the listing file. Y Individual Source File Line Number. This value tracks line numbers for the top-level source file and for each separate INCLUDE file. Z Macro Expansion Line Number. This value tracks the current line number for each MACRO expanded during the assembly. D Macro Definition Line Number. This value tracks line numbers for each new MACRO definition introduced into the assembly. L Macro Expansion Indentation Level. This 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. This is a numeric value that appears during macro expansions and is incremented for each level of nesting that occurs. I Include File Nesting Level. This is a numeric value that appears during processing of INCLUDE files and is incremented for each level of nesting that occurs. C Conditional Assembly Nesting Level. This is a numeric value that appears during processing of a conditional assembly directive and is incremented for each level of nesting that occurs. F True or False Conditional Flag. This value 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 withing the block are being ignored. O Location Counter Offset Value. This is a numeric value displayed in hexadecimal notation and indicates the current offset of the location counter within the current segment or structure. G Generated Machine Code Data. This column shows the hexadecimal values for data generated by machine instructions or data allocation statements. S Source Line Data. This column contains the text data of the current line in the input source file. ═══ 5.6.2.1. Lc* - Control Display of Individual Columns ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │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) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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: ON The column will be displayed OFF The column will not be displayed BLANK The column will appear as a placeholder in the listing file, but the column data will not be displayed B Abbreviation for BLANK ZBLANK The column data will only display if its value is non-zero (valid only for numeric fields) Z Abbreviation for ZBLANK ═══ 5.6.2.2. Lcm* - Specify Left Margin for Individual Columns ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmX:0 (Cumulative Listing Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmY:1 (Individual Source File Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmZ:1 (Macro Expansion Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmD:1 (Macro Definition Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmL:0 (Macro Expansion Indentation Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmM:1 (Macro Expansion Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmI:1 (Include File Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmC:1 (Conditional Assembly Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmF:1 (True or False Conditional Flag) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmO:2 (Location Counter Offset Value) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmG:2 (Generated Machine Code Data) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmS:2 (Source Line Data) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.3. Lct* - Specify Truncation of Individual Columns ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │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) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.4. Lcw* - Specify Width of Individual Columns ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmX:4 (Cumulative Listing Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmY:4 (Individual Source File Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmZ:3 (Macro Expansion Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmD:3 (Macro Definition Line Number) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmL:0 (Macro Expansion Indentation Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmM:2 (Macro Expansion Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmI:2 (Include File Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmC:2 (Conditional Assembly Nesting Level) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmF:1 (True or False Conditional Flag) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmO:4 (Location Counter Offset Value) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmG:20 (Generated Machine Code Data) │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-LcmS:90 (Source Line Data) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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 behaviour 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. ═══ 5.6.2.5. Lc - Control display of false Conditional blocks ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Lc (do not list 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. ═══ 5.6.2.6. Ld - Control Display of Listing Directives ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Lc (show all 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. ═══ 5.6.2.7. Le - Control Display of Error/Warning/Info Messages ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Le (show messages in listing file) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.8. Lf - Control use of FormFeed Characters ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Lf (the FormFeed character is used) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.9. Li - Control Display of INCLUDE Files ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Li (INCLUDE files are expanded in listing output)│ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.10. Llp - Specify Length of Page ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Llp:66 (the default page length is 66 lines) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ In order 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. Related Information: o Lf - Control use of FormFeed Characters o Lwp - Specify Width of Page ═══ 5.6.2.11. Lm - Control Display of Macro Expansions ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Lm (macro expansions do not appear in listing │ │ │ │ │ │output) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.12. Lmb - Specify Bottom Margin ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lmb:4 (4 blank lines at bottom of page) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Related Information: o Lf - Control use of FormFeed Characters o Llp - Specify Length of Page o Lmm - Specify Middle Margin Following Title o Lmt - Specify Top Margin Before Title ═══ 5.6.2.13. Lml - Specify Left Margin ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lml:4 (left margin is 4 blank characters wide) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Related Information: o Lmr - Specify Right Margin o Lwp - Specify Width of Page o Lcm* - Specify Left Margin for Individual Columns ═══ 5.6.2.14. Lmm - Specify Middle Margin Following Title ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lmm:2 (2 blank lines after title and subtitle, │ │ │ │ │ │and before ruler line) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Related Information: o Llp - Specify Length of Page o Lmb - Specify Bottom Margin o Lmt - Specify Top Margin Before Title o Lr - Control Display of Column Ruler ═══ 5.6.2.15. Lmr - Specify Right Margin ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lmr:4 (right margin is 4 blank characters wide) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Related Information: o Lml - Specify Left Margin o Lwp - Specify Width of Page o Lcm* - Specify Left Margin for Individual Columns ═══ 5.6.2.16. Lmt - Specify Top Margin Before Title ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lmt:2 (2 blank lines at the top of the page) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Related Information: o Llp - Specify Length of Page o Lmb - Specify Bottom Margin o Lmm - Specify Middle Margin Following Title ═══ 5.6.2.17. Lp - Generate Listing on Specific Pass ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lp:2 (listing on pass 2 only) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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, since 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. ═══ 5.6.2.18. Lr - Control Display of Column Ruler ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Lr (show the column ruler in listing output) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.19. Ls - Control Display of Symbol Table ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Ls (do not include symbol table in listing │ │ │ │ │ │output) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.20. Lt1 - Specify Title ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lt1: (no default title information) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.21. Lt2 - Specify Subtitle ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lt2: (no default subtitle information) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.2.22. Lwp - Specify Width of Page ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lwp:132 (the default page width is 132 character │ │ │ │ │ │positions) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ In order 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. Note: Since ALP uses the total width of the individual active columns to generate a line of listing output, this value would conceivably be used to do range checking of the total width and to verify that it would fit on the printed page; ALP does not do such range checking at this time, thus this value is not used. Related Information: o Lcm* - Specify Left Margin for Individual Columns o Lcw* - Specify Width of Individual Columns ═══ 5.6.2.23. Lwt - Specify Tab Expansion Width ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Lwt:8 (tab characters are 8 character positions │ │ │ │ │ │wide) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.3. 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". ═══ 5.6.3.1. M - Control Individual Messages or Groups ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-M:W+ (all warning messages are enabled) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. 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 I - All Informational messages W - All Warning messages BLK - Messages regarding block structure violations COD - Messages regarding code generation FIL - File manipulation messages PP - Preprocessor messages SRC - Source file lexical analyzer messages STA - Assembly statistics 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. ═══ 5.6.3.2. Mb - Control Printing of the Assembler Banner ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │No │No │+Mb (Print the assembler banner) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This switch controls whether or not the assembler startup banner is printed. This switch is on by default; turn it off to suppress display of the banner. ═══ 5.6.3.3. Me - Set Number of Errors Before Assembly Aborts ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │-Me:50 (abort the assembly after 50 errors are │ │ │ │ │ │encountered) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option specifies the maximum number of errors that the assembler will tolerate before terminating the assembly. The default value is 50. ═══ 5.6.3.4. Mwe - Treat Warnings as Errors ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Mwe (warnings are not considered to be errors) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This switch tells the assembler that any Warning messages are to be treated as though they were errors; this causes the assembler to terminate with a non-zero exit code, and helps prevent any warning conditions from "passing by" unnoticed. ═══ 5.6.4. 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". ═══ 5.6.4.1. Od - Line Number and Symbolic Debug Information in Object File ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │(see default values for Ods and Odl) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Note: ALP does not currently support the creation of symbolic debug information. Related Information: o Odl - Line Numbering Information in Object File o Ods - Symbolic Debug Information in Object File ═══ 5.6.4.2. Odl - Line Numbering Information in Object File ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Odl (line numbering debug information is not │ │ │ │ │ │included 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. ═══ 5.6.4.3. Ods - Symbolic Debug Information in Object File ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Ods (symbolic debug information is not included │ │ │ │ │ │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. Note: ALP does not currently support the creation of symbolic debug information. ═══ 5.6.5. 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". ═══ 5.6.5.1. Sc - Control Case Sensitivity for All Identifiers ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │(see default values for Sck and Scs) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. Note: ALP does not currently support case sensitivity for processor mnemonics. Related Information: o Sck - Control Case Sensitivity for Keywords o Scs - Control Case Sensitivity for Symbol Names ═══ 5.6.5.2. Sck - Control Case Sensitivity for Keywords ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Sck (All language keywords are case insensitive) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This switch controls whether or not language keywords are case sensitive. By default, this flag is turned off; thus the keywords 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 lowercase 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. Note: ALP does not currently support case sensitivity for processor mnemonics. ═══ 5.6.5.3. Scs - Control Case Sensitivity for Symbol Names ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │+Scs (All user identifiers are case sensitive) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. This option has no effect on language keywords (see Sck - Control Case Sensitivity for Keywords), processor mnemonics, or register names. ═══ 5.6.5.4. Sk - Control Use of Reserved Words as Labels ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Sk (Reserved words may not be used 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. ═══ 5.6.5.5. Sfs - SHORT is Default Distance for Forward-Referenced Jumps ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │S │Yes │Yes │Yes │-Sfs (default distance is NEAR) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ 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. ═══ 5.6.5.6. Sv - Set Version Behavior ═══ ┌────┬──────┬─────┬────┬──────────────────────────────────────────────────┐ │Type│Global│Group│File│Default │ ├────┼──────┼─────┼────┼──────────────────────────────────────────────────┤ │P │Yes │Yes │Yes │+Sv:MASM51 (assume MASM 5.1 compatibility) │ └────┴──────┴─────┴────┴──────────────────────────────────────────────────┘ This option controls the various modes of compatibility that the assembler is designed to emulate. The argument to the Sv option must be one of the following keywords: ALP - Not currently specified MASM51 - Emulate Microsoft MASM(TM) Version 5.1 MASM60 - Emulate Microsoft MASM(TM) Version 6.0 Note: ALP does not currently take any action when this option is used. ═══ 5.7. ALP Return Codes ═══ When ALP finishes execution, it passes a return code back to the program that invoked it. This return code may be examined to determine if ALP completed successfully, or if errors were encountered. The return codes issued by ALP are as follows: 0 Normal program completion. 1 User-specified file not found. 2 Unexpected system error. 3 Terminated by user or operating system. 4 Syntax errors in input file. 5 Command-line usage error. 6 Internal sanity check failure. 7 Error accessing ALP messages file. ═══ 6. Assembler Messages ═══ This section describes all the messages produced by ALP at run time. Messages issued by the assembler have the following format: [Coordinates] [Severity Type] [Message Number] [Message Content] The following sections describe the various fields common to all assembler messages, and a complete description of each individual message is included. ═══ 6.1. Message Coordinates ═══ Message coordinates (if present) appear as the first field within a message, and have one of two forms: [Path]Filename(LLLL:CCCC): [Path]Filename(LLLL,Macroname(LLLL,CCCC)): Coordinates are displayed as part of a message if ALP is parsing an input stream and the event which caused the message to be diplayed is directly related to a specific location in the input. The coordinates show the user exactly where to look if action is required. The fact the ALP is parsing an input stream does not mean that coordinates will appear in a message; some messages may occur during parsing that are not a reference to the input stream. o Filename This is the name of the file containing the input token which caused the message to be generated. If this is the root source file whose name was passed on the assembler command line, the filename will be displayed exactly as specified by the user. If this is an INCLUDE file, it will be displayed exactly as specified in the INCLUDE directive, and the pathname where the file was searched for and found (if any) will be prepended to the beginning. ALP does not query the operating system in an attempt to derive the full pathname of a partially qualified file. o Macroname If the assembler is currently parsing tokens within a macro expansion, the name of the macro currently being expanded will appear in the coordinates. o Line Number (LLLL) The first number in parentheses is the line number within the source file where the referenced token is located; this refers to the outer-most point of invocation if a macro name is also given in the message coordinates. A line number value appearing within parentheses following a macro name refers to the innermost point of expansion (since macro expansions may be nested) and references the original definition of the macro. o Column Number (CCCC) The second number in parentheses is the column number of the first character of the referenced token within the source file or macro definition. ═══ 6.2. Message Severity Types ═══ Every message displayed by ALP is assigned a specific type, and the type of message dictates the severity level. The following is a list of message types produced by ALP showing the type name (as it appears in the actual message), followed by a description of what caused the message, how severe it is, and the action taken by ALP after the message is generated. Info Informational message only; processing continues normally. Warning Questionable syntax or semantics; input file may be incorrect, but processing continues. Error Syntax or semantic error in input; continue processing, object output file is discarded. Fatal Unrecoverable user or environment error; terminate assembly prematurely after releasing resources and closing files. Internal Internal program logic error, abort immediately. Usage Incorrect command line syntax, abort. When the assembler begins processing, the display of all warning messages is enabled; informational messages do not display unless they are requested. The display of both warning and informational messages may be controlled with the command line option M - Control Individual Messages or Groups See Message Control Options for more information on the behaviour of assembler messages. ═══ 6.3. Message Numbers and Message Content ═══ Messages numbers displayed by ALP have the following format: ALPnnnn: Message numbers always have a three-letter prefix that designates the component issuing the message (ALP), followed by a four digit decimal number given by nnnn. All messages issued by the assembler are uniquely numbered; however, not all messages displayed by the assembler will be accompanied by a formatted message number (for instance, the assembler banner). Messages issued during assembler initialization, command line processing, or exception handling are numbered from 0 to 999. Other messages occur during input stream processing and are grouped according to their severity type: 1000 through 1999 for fatal errors, 3000 through 3999 for regular errors, 4000 through 4999 for warnings, and 5000 through 5999 for informational messages. It should be noted that messages are numbered for reference only; it is not guaranteed that messages will be numbered identically for each subsequent assembler release, or that individual messages will be retained or remain unmodified in future releases. ═══ 6.3.1. Message Numbers 0-999: Internal, Usage, and Special-Case Messages ═══ Messages in this section normally occur during assembler initialization, when errors are encountered during command line processing, or when exceptional conditions occur that prevent the assembler from completing initialization or execution. ═══ 6.3.1.1. ALP0004: received, is shutting down ═══ ALP has handled a request from the operating system to abort execution. The type of abort request is noted in the text of the message. All open files will be closed and any incomplete output files will be deleted. Recovery: If termination was requested by the user, no further action is necessary. Otherwise, the operating system may have sent an abort signal because of insufficient system resources. ═══ 6.3.1.2. ALP0005: Assertion failure, ═══ This message is displayed when an internal self-check condition has been violated, and indicates an error in the internal programming logic of the assembler. This message should never occur. Recovery: Note the conditions under which the error occurred, and if possible isolate a minimal test case that will reproduce the problem. Contact the program author. ═══ 6.3.1.3. ALP0942: -Lo:xxxxxxxxxxxx must be one each of "XYZLMICFOGDS" ═══ This option specifies the sort order for the individual vertical listing file columns. Not all single character tags the uniquely identify each individual column were specified. Recovery: All column tags must be specified in the argument field of this option, even when the display of one or more columns has been disabled. ═══ 6.3.1.4. ALP0981: Invalid or missing include path ═══ The list of INCLUDE file directories was incorrectly specified. ═══ 6.3.1.5. ALP0991: Invalid option "