TOPIC: XREF36 FROM: LUCIEN L. PAN DATE: 1983/10/18 INTRODUCTION: ------------ XREF is a cross-reference utility designed to generate a listing file which contains valuable information that can be of help to the assembly language programmer. It uses for input the '.PRN' file created by an assembler and writes out a modified file which is identical to the input except for an identifying number and some cosmetic formatting, for each source line encountered. At the end of input, XREF will output a report, listing each symbol and the line number(s) where the symbol was referenced. This report can be used as an important diagnostic tool facilitating the task of debugging an assembly program. FEATURES: -------- Due to the (relatively) simple objectives of this program, such as numbering each individual line and building a table of symbols with references to where they are being used, most of the 'polishing' is aimed toward getting a nice-looking listing as output. Following is a short description of some of the features offered in this utility: - Provides a filename banner on the first page of the listing, which when folded in half (on the proper page parity) doubles as an excellent program listing separator, allowing easy indexing through a pile of printouts when they are held together in a binder. - The line identification number appears between the object code expansion and the actual source code. This in my opinion, gives the the final listing a more attractive look by making it less crowded. It definitively improves the appearance of a '.PRN' file from MAC (tm), as there is no blank space between the object and source field (when defining a string greater than 5 characters in a labeled source line for example). - Sadly, most assemblers that I've seen do not report a summary of errors, they just flag them. MAC (tm) reports them to the console as they are encountered and fortunately, CP/M allows you to send it to the hard copy device. However that still doesn't tell you where the errors are located in the listing causing much time being wasted 'eyeballing' the printout. XREF will automatically execute a second pass when error(s) were detected in the first pass, this time listing only the lines containing the error(s) along with their line id. numbers. You also have the option to list only error lines, fast! - A listing to disk is implemented and is useful to those who use disk spooling before printing. To conserve disk space, a tab compression/expansion driver is included. It is a desirable feature since MAC (tm) only uses spaces in the object field, or even worse, MACROII (tm) expands tabs throughout the entire file! I've typically seen some space reduction in the order of 40%. INSTALLATION: ------------ XREF36 is supplied in source code and compiled object. The contents of the library are: XREF36.DOC XREF36.AQM XREFM.COM (for MAC) XREFT.COM (for MACROII) Due to the incompatibility between MAC (tm) and MACROII (tm), the compiled object can only handle one format at a time and is specified at assembly time by setting the TDL symbol equate to either true or false. You can also specify the number of lines per page by changing the symbol PGLEN. For those using MAC (or ASM), re-assembly of XREF is straightfoward, requiring only that the TDL symbol be set to false. For those using MACROII, a slight modification to the macro- assembler object module (.COM) itself is required. Full explanations are given in the source file. Obviously, the TDL symbol must be set to true. OPERATION: --------- The operation of XREF is very simple as it will be illustrated in the following examples: A help display is available by entering: A0>XREF It will also appear if an error option is detected. To cross-reference a file to the printer, just type: A0>XREF MYFILE XREF will assume an extension of '.PRN' if no file type is specified. To enter a null filetype, just type a '.' (dot) as the only extension. To send the output to a disk file, just append the option: B0>XREF MYFILE /D The listing file will be created on the current drive and will bear the same filename but will have a '.LST' filetype. In the disk mode, tabs are always substitued for blanks whenever possible (tab compression). The drive designators syntax follows the one defined by CP/M: A0>b:xref c:myfile d:/d Would get XREF from drive B, the PRN file from drive C and send the LST file to disk D. The rest of the available options are self-explanatory. LIMITATIONS: ----------- For the TDL version of XREF (written in MAC mnemonics), there are some non standard factors: XREF cannot detect that text between a .REMARK should be interpreted as a 'multi-line' comment so here is a way to get around it; just insert '*' at the beginning of each source line that is bracketed in a .REMARK pseudo-op. Actually, a whole frame of '*' can be put around the text and looks quite nice. It is also difficult to accept '.' as a legal global symbol although TDL's syntax allows it (but '.' doesn't show up in the symbol table generated by MACROII). This is due to the fact that '.' is also used as the base 10 specifier and also as the current program address counter key. * MAC and CP/M are trademarks of DIGITAL RESEARCH INC. * MACROII and TDL are trademarks of COMPUTER DESIGN LABS INC.