View source for ALP Programming Guide and Reference/Understanding ALP

== Understanding ALP ==
This chapter describes:
*The ALP message file
*ALP internal variables
Though you do not need to understand this information to be able to use ALP, you may need this information for troubleshooting purposes.

=== The ALP Messages File ===
Nearly every message displayed by ALP at run time is stored in a separate message file. The exception to this rule are messages that are displayed if the message file cannot be opened: ALP ends if one of these messages is displayed.

When ALP starts, it determines the name of the message file by creating a name of the form <BaseEXE>'''.msg''' (see [[#BaseEXE]]). Once ALP knows the name of the message file, ALP searches the following directories in the following order for the file:
# Current directory
# The directory contained in the BasePATH internal variable
# Each of the directories specified in the BaseEXE internal variable
# Each of the directories specified in the PATH environment variable
# Each of the directories specified in the DPATH environment variable

=== Internal Variables ===
ALP maintains a set of '''internal variables''' that it uses for various purposes. These variables reflect the ALP environment; programmers do not use these variables. Their values may be indirectly affected by the user of ALP, for instance, through the use of various command line options.

;BaseEXE:When ALP is invoked, if the full path name 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 file name of the ALP executable is '''not''' available at run time, then the value of '''BaseEXE''' defaults to "ALP".
;BasePATH:When ALP is invoked, if the full path name 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 file name of the ALP executable is '''not''' available at run time, then the value of '''BasePATH''' is NULL.
;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.
;IncEXT:This variable contains the default include file name extension that is conditionally appended to unadorned file names generated by the '''INCLUDE''' preprocessor directive. The default value for '''IncEXT''' is ".inc"; unless altered by use of the '''Fei''' parameterized command line option.
;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.
;LstEXT:This variable contains the default listing file name extension that is conditionally appended to the concatenated values of "LstDIR" and "LstNAME"; the assembler treats the resulting string as the fully qualified listing file name. The default value for '''LstEXT''' is ".lst"; unless altered by use of the '''Fel''' parameterized command line option.
;LstNAME:This variable contains the same value as the contents of "SrcNAME", unless initialized with the '''Fl''' parameterized command line option.
;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.
;MsgEXT:This variable contains the default messages file name extension that is conditionally appended to the concatenated values of '''MsgDIR''' and '''MsgNAME'''; the assembler treats the resulting string as the fully qualified messages file name. The default value for '''MsgEXT''' is ".msg"; unless altered by use of the '''Fem''' parameterized command line option.
;MsgNAME:This variable contains the same value as the contents of '''SrcNAME''', unless initialized with the '''Fm''' parameterized command line option.
;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.
;ObjEXT:This variable contains the default object file name extension that is conditionally appended to the concatenated values of '''ObjDIR''' and '''ObjNAME'''; the assembler treats the resulting string as the fully qualified object file name. The default value for '''ObjEXT''' is ".obj"; unless altered by use of the '''Feo''' parameterized command line option.
;ObjNAME:This variable contains the same value as the contents of '''SrcNAME''', unless initialized with the '''Fo''' parameterized command line option.
;SourceNAME:This 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.
;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 file name, then '''SrcDIR''' will contain the empty string.
;SrcEXT:This variable contains the default source file name extension that is conditionally appended to the concatenated values of '''SrcDIR''' and '''SrcNAME'''; the assembler treats the resulting string as the fully qualified input file name. The default value for '''SrcEXT''' is ".asm"; unless altered by use of the '''Fes''' parameterized command line option.
;SrcNAME:This variable contains the "root file name" portion of the source file name , 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 file name was incorrectly specified; in which case the assembler will generate an error when it tries to access the file.

[[Category:ALP Programming Guide and Reference]]