A listing file is useful if you want to see exactly what Paradigm Assembler generates when each instruction or directive is assembled. The file is basically the source file annotated with a variety of information about the results of the assembly. Paradigm Assembler lists the actual machine code for each instruction, along with the offset in the current segment of the machine code for each line. What's more, Paradigm Assembler provides tables of information about the labels and segments used in the program, including the value and type of each label, and the attributes of each segment. For additional information on creating listings, refer to the /l and /la command-line switches documented in Chapter 2.
Paradigm Assembler can also, on demand, generate a cross-reference table for all labels used in a source file, showing you where each label was defined and where it was referenced. See the /c command-line option in Chapter 2 for more information on generating cross-reference tables.
Listing format
The top of each page of the listing file displays a header consisting of the version of Paradigm Assembler that assembled the file, the date and time of assembly, and the page number within the listing.
There are two parts to the listing file: the annotated source code listing and the symbol tables. The original assembly code is displayed first, with a header containing the name of the file where the source code resides. The assembler source code is annotated with information about the machine code Paradigm Assembler assembled from it. Any errors or warnings encountered during assembly are inserted immediately following the line they occurred on.
The code lines in the listing file follow this format:
<depth> <line number> <offset> <machine code> <source>
<depth> indicates the level of nesting of Include files and macros within your listing file.
<line number> is the number of the line in the listing file (not including header and title lines). Line numbers are particularly useful when the cross-reference feature of
Paradigm Assembler, which refers to lines by fine number, is used. Be aware that the line numbers in <line number> are not the source module line numbers. For example, if a macro is expanded or a file is included, the line-number field will continue to
advance, even though the current line in the source module stays the same. To translate a line number (for example, one that the cross-referencer produced) back to the source file, you must look up the line number in the listing file, and then find that same line (by eye, not by number) in the source file.
<offset> is the offset in the current segment of the start of the machine code generated by the associated assembler source line.
<machine code> is the actual sequence of hexadecimal byte and word values that is assembled from the associated assembler source line.
<source> is simply the original assembler line, comments and all. Some assembler lines, such as those that contain only comments, don't generate any machine code; these lines have no <offset> or <machine code> fields, but do have a line number.
General list directives
There are a variety of list directives that let you control what you want in your listing file. The general list directives follow:
l .LIST ;MASM mode only
l .XLIST ;MASM mode only
l %LIST
l %NOLIST
l %CTLS
l %NOCTLS
l %SYMS
l %NOSYMS
The %LIST directive shows all of the source lines in your listing. This is the default condition when you create a listing file. To turn off the display of all the source lines, use the %NOLIST directive. Here's an example:
%NOLIST ;turn off listing INCLUDE MORE .INC
%LIST ;turn on listing
The .LIST and .XLIST directives function the same way as %LIST and %NOLIST.
Here's an example:
.LIST
jmp xyz ;this line always listed .XLIST
add dx,ByteVar ;not in listing
You can use the %CTLS and %NOCTLS directives to control the listing directives.
%CTLS causes listing control directives (such as %LIST, %INCL, and so on) to be placed in the listing file; normally, they are not listed. It takes effect on all subsequent lines, so the %CTLS directive itself will not appear in the listing file. %NOCTLS reverses the effect of a previous %CTLS directive. After issuing %NOCTLS, all subsequent listing-control directives will not appear in the listing file. (%NOCTLS is the default listing-control mode that Paradigm Assembler uses when it starts assembling a source file.); for example,
%CTLS
%NOLIST ;this will be in listing file
%NOCTLS
%LIST ;this will not appear in listing
You can use the %SYMS and %NOSYMS directives to cause the symbol table to either appear or not to appear in your listing file (the default is for it to appear). The symbol table will appear at the end of the listing file.
Here's the syntax for %SYMS:
%SYMS
Here's the syntax for %NOSYMS:
%NOSYMS
Include file list directives
In the event that you might want to list the include files in your listing file, you can turn this capability on and off using the %INCL and %NOINCL directives. By default, INCLUDE files are normally contained in the listing file. %NOINCL stops all
subsequent INCLUDE files source lines from appearing in the listing until a %INCL is enabled. This is useful if you have a large INCLUDE file that contains things such as a lot of EQU definitions that never change.
Here's an example:
%INCL
INCLUDE DEFS.INC ;contents appear in listing
%NOINCL
INCLUDE DEF1.INC ;contents don't appear
Conditional list directives
When you have conditional blocks of code in your source files, you might not want all of that information to appear in the listing file. Showing conditional blocks can be very helpful in some instances when you want to see exactly how your code is behaving.
Paradigm Assembler provides the following conditional list directives:
l .LFCOND ;MASM mode only
l .SFCOND ;MASM mode only
l .TFCOND ;MASM mode only
l %CONDS
l %NOCONDS
Paradigm Assembler does not usually list conditional blocks.
The %CONDS directive displays all statements in conditional blocks in the listing file.
This includes the listing of false conditional blocks in assembly listings. The .LFCOND directive functions the same as %CONDS. %NOCONDS prevents statements in false conditional blocks from appearing in the listing file. The .SFCONDS directive
functions exactly the same as %NOCOND. If you want to toggle conditional block-listing mode, use the .TFCOND directive.
The first .TFCOND that Paradigm Assembler encounters enables a listing of
conditional blocks. If you use the /X command-line option, conditional blocks start off being listed, and the first .TFCOND encountered disables listing them. Each time .TFCOND appears in the source file, the state of false conditional listings is reversed.
To invoke any of these directives, place it by itself on a line in your code. They will affect the conditional blocks that immediately follow them.
Macro list directives
Macro expansions are not normally included in listing files. Having this information in listing files can be very helpful when you want to see what your code is doing.
Paradigm Assembler provides several directives that let turn this feature on and off.
They are: