Liren Large Software Subsidy 9

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 9 / 09.iso / l / l224 / 1.img / MANUAL.ZIP / OBJXREF.DOC < prev next >

Wrap

Text File | 1990-10-29 | 18.0 KB | 535 lines

OBJXREF: THE OBJECT MODULE CROSS-REFERENCE UTILITY --------------------------------------------------- TABLE OF CONTENTS ----------------- 1. What is OBJXREF? 2. How to Use OBJXREF 3. OBJXREF Options 4. OBJXREF Reports 5. OBJXREF Examples 6. OBJXREF Diagnostic Messages 1. WHAT IS OBJXREF? ------------------- OBJXREF is a utility that examines a list of object files and library files and produces reports on their contents. One type of report lists definitions of public names and references to them. The other type lists the segment sizes defined by object modules. There are two categories of public names: global variables and function names. The TEST1.ASM and TEST2.ASM files shown later in this file illustrate definitions of public names and external references to them. Object modules are object (.OBJ) files produced by TC, TCC, or TASM. A library (.LIB) file contains multiple object modules. An object module generated by TASM is given the same name as the .ASM source file it was compiled from, unless a different output file name is specifically indicated on the command line. 2. HOW TO USE OBJXREF --------------------- The OBJXREF command line consists of the word OBJXREF, followed by a series of command line options and a list of object and library file names, separated by a space or tab character. The syntax is as follows: OBJXREF < options > filename < filename ... > The command line options determine the kind of reports OBJXREF will generate and the amount of detail that OBJXREF will provide. They are discussed in more detail under Control Options and Report Options, two types of command line options. Each option begins with a forward slash (/) followed by a one- or two-character option name. Object files and library files may be specified either on the command line or in a response file. On the command line, file names are separated by a space or a tab. All object modules specified as .OBJ files are included in reports. Like TLINK, however, OBJXREF includes only those modules from .LIB files which contain a public name referenced by an .OBJ file or by a previously included module from a.LIB file. As a general rule, you should list all the .OBJ and .LIB files that are needed if the program is to link correctly, including the libraries. File names may include a drive and directory path. The DOS ? and * wildcard characters may be used to identify more than one file. File names may refer to .OBJ object files or to .LIB library files. (If no file extension is given, the .OBJ extension is assumed.) Options and file names may occur in any order in the command line. OBJXREF reports are written to the DOS standard output. The default is the screen. The reports may be sent to a printer (as with >LPT1:) or to a file (as with >lstfile) with the DOS redirection character (>). Entering OBJXREF with no file names or options produces a summary of available options. 3. OBJXREF OPTIONS ------------------ OBJXREF command line options fall into two categories: control options and report options. Control options --------------- Control options modify the default behavior of OBJXREF (the default is that none of these options are enabled). /I Ignore case differences in public names: Use this option if you use TLINK without the /c option (which makes case differences significant). /F Include Full library: All object modules in specified .LIB files are included even if no public names they contain are referenced by an object module being processed by OBJXREF. This provides information on the entire contents of a library file. /V Verbose output: Lists names of files read and displays totals of public names, modules, segments, and classes. /Z Include Zero length segment definitions: Object modules may define a segment without allocating any space in it. Listing these zero length segment definitions normally makes the module size reports harder to use but it can be valuable if you are trying to remove all definitions of a segment. Report Options -------------- Report options govern what sort of report is generated, and the amount of detail OBJXREF provides. /RC Report by Class Type: Module sizes ordered by class type of segment. /RM Report by Module: Public names ordered by defining module. /RP Report by Public Names: Public names in order with defining module name. /RR Report by Reference: Public name definitions and references ordered by name. (This is the default if no report option is specified.) /RS Report of Module Sizes: Module sizes ordered by segment name. /RU Report of Unreferenced Symbol Names: Unreferenced public names ordered by defining module. /RV Verbose Reporting: OBJXREF produces a report of every type. /RX Report by External Reference: External references ordered by referencing module name. Response Files -------------- The command line is limited by DOS to a maximum of 128 characters. If your list of options and file names will exceed this limit, you must place your file names in a response file. A response file is a text file that you make with an text editor. Since you may already have prepared a list of the files that make up your program for other Turbo Assembler programs, OBJXREF recognizes several response file types. Response files are called from the command line using one of the following options. The response file name must follow the option without an intervening space (/Lresp not /L resp). More than one response file can be specified on the command line, and additional .OBJ and .LIB file names may precede or follow them. You can create a freeform response file with a text editor. Just list the names of all .OBJ and .LIB files needed to make your .EXE file. To use freeform files with OBJXREF, type in each file name on the command line, preceded by an at-sign (@), and separate it from other command line entries with a space or tab: @filename @filename ... Note: Any file name that is listed in the response file without an extension is assumed to be a .OBJ file. Files in TLINK response file format can also be used by OBJXREF. A linker response file called from the command line is preceded by /L: /Lfilename To see how to use one of these files, refer to Example 2 in the section "OBJXREF Examples" later in this file. Other OBJXREF Options --------------------- The /D command If you want OBJXREF to look for .OBJ files in a directory other than the current one, include the directory name on the command line, prefixed with /D: C:>OBJXREF/Ddir1[;dir2[;dir3]] or C:>OBJXREF/Ddir1[/Ddir2][/Ddir3] OBJXREF will search each of the directories in the specified order for all object and library files. If you don't use the /D option, only the current directory will be searched. However, if you use a /D option, the current directory will not be searched unless it is included in the directory list. For example, to first search the BORLAND directory for files and then search the current directory, you would type C:>OBJXREF/Dborland; If multiple search directories are specified, and a file matching the file specification is found, OBJXREF will include the file as part of the cross-reference. OBJXREF will only continue to search the other directories for the same file specification if the file specification contains wildcards. The /O command The /O option allows you to specify an output file where OBJXREF will send any reports generated. It has the following syntax: C:>OBJXREF myfile.obj /RU /Ofilename.ext By default, all output is sent to the console. The /N command You can limit the modules, segments, classes, or public names that OBJXREF reports on by entering the appropriate name on the command line, prefixed with the /N command. For example, OBJXREF <filelist> /RM /NTest tells OBJXREF to generate a report listing information only for the module named Test. 4. OBJXREF REPORTS ------------------ Suppose you have two source files in your Turbo Assembler directory, and wish to generate OBJXREF reports on the object files compiled from them. The source files are called TEST1.ASM and TEST2.ASM, and they look like this: ; TEST1.ASM .MODEL small STACK 200h EXTRN GOODBYE:BYTE ;refers to Goodbye EXTRN SAYHELLO:NEAR ;refers to SayHello PUBLIC HELLO ;makes Hello public PUBLIC NOTUSED ;makes NotUsed public .DATA HELLO DB 'Hello',10, 13, '$' ;defines Hello NOTUSED DW ? HIDDEN DW ? .CODE SAYBYE PROC NEAR ;defines SayBye mov dx,OFFSET GOODBYE mov ah,9 int 21h ret SAYBYE ENDP START PROC NEAR ;defines Start mov ax,@data mov ds,ax call SAYHELLO ;refers to SayHello call SAYBYE ;refers to SayBye EXIT: mov ax,04C00h int 21h START ENDP END START ; TEST2.ASM .MODEL small EXTRN HELLO:BYTE ;refers to Hello PUBLIC GOODBYE ;makes Goodbye public PUBLIC SAYHELLO ;makes SayHello public .DATA GOODBYE DB 'Goodbye',10, 13, '$' ;defines Goodbye .CODE SAYHELLO PROC NEAR ;defines SayHello mov dx,OFFSET HELLO ;refers to Hello mov ah,9 int 21h ret SAYHELLO ENDP END The object modules compiled from them are TEST1.OBJ and TEST2.OBJ. You can tell OBJXREF what kind of report to generate about these .OBJ files by entering the file names on the command line, followed by a /R and a second letter denoting report type. Note: The examples that follow show only fragments of the output. Report by public names (/RP) ---------------------------- A report by public names lists each of the public names defined in the object modules being reported on, followed by the name of the module in which it is defined. If you enter the following on the command line, OBJXREF /RP test1 test2 OBJXREF will generate a report that looks like this: Symbol Defined in GOODBYE TEST2 HELLO TEST1 NOTUSED TEST1 SAYHELLO TEST2 Report by module (/RM) ---------------------- A report by module lists each object module being reported on, followed by a list of the public names defined in it. If you enter the following on the command line, OBJXREF /RM test1 test2 OBJXREF will generate a report that looks like this: Module: TEST1 defines the following symbols: HELLO NOTUSED Module: TEST2 defines the following symbols: GOODBYE SAYHELLO Report by reference (/RR) (default) ----------------------------------- A report by reference lists each public name with the defining module in parentheses on the same line. Modules that refer to this public name are listed on following lines indented from the left margin. If you enter the following on the command line, OBJXREF /RR test1 test2 OBJXREF will generate a report that looks like this: GOODBYE (TEST2) TEST1 HELLO (TEST1) TEST2 NOTUSED (TEST1) SAYHELLO (TEST2) TEST1 Report by external references (/RX) ----------------------------------- A report by external references lists each module followed by a list of external references it contains. If you enter the following on the command line, OBJXREF /RX test1 test2 CS.LIB OBJXREF will generate a report that looks like this: Module: TEST1 references the following symbols: GOODBYE SAYHELLO Module: TEST2 references the following: HELLO Report of module sizes (/RS) ---------------------------- A report by sizes lists segment names followed by a list of modules that define the segment. Sizes in bytes are given in decimal and hexadecimal notation. The word uninitialized appears where no initial values are assigned to any of the symbols defined in the segment. Segments defined at absolute addresses in a .ASM file are flagged Abs to the left of the segment size. If you enter the following on the command line, OBJXREF /RS test1 test2 OBJXREF will generate a report that looks like this: ;Module sizes by segment STACK 512 (00200h) TEST1, uninitialized 512 (00200h) total _DATA 12 (0000Ch) TEST1 10 (0000Ah) TEST2 22 (00016h) total _TEXT 24 (00018h) TEST1 8 (00008h) TEST2 32 (00020h) total Report by class type (/RC) -------------------------- A report by class type lists segment size definitions by segment class. The CODE class contains instructions, DATA class contains initialized data and BSS class contains unitialized data. Segments that don't have a class type will be listed under the notation "No class type." If you enter the following on the command line, OBJXREF /RC test1 test2 OBJXREF will generate a report that looks like this: ;Module sizes by class CODE 24 (00018h) TEST1 8 (00008h) TEST2 32 (00020h) total DATA 12 (0000Ch) TEST1 10 (0000Ah) TEST2 22 (00016h) total STACK 512 (00200h) TEST1, uninitialized 512 (00200h) total Report of unreferenced symbol names (/RU) ----------------------------------------- A report of unreferenced symbol names lists modules that define public names not referenced in other modules. Either such a symbol is referenced only from within the defining module and doesn't need to be defined as a public symbol (in that case, if the module is in C, the keyword static should be added to the definition; if the module is in TASM, just remove the public definition), or the symbol is never used (therefore, it can be deleted to save code or data space). If you enter the following on the command line, OBJXREF /RU test1 test2 OBJXREF will generate a report that looks like this: Module: TEST1 defines the following unreferenced symbols: NOTUSED Verbose reporting (/RV) ----------------------- If you enter /RV on the command line, one report of each type will be generated. 5. OBJXREF EXAMPLES ------------------- These examples assume that the application files are in the current directory of the default drive and that library files are in the \LIB directory. Example 1 C>OBJXREF test1 test2 \lib\io.lib --------------------------------------------- In addition to the TEST1.OBJ and TEST2.OBJ files, the library file \ LIB\IO.LIB is specified. Since no report type is specified, the resulting report is the default report by reference, listing public names and the modules that reference them. Example 2 C>OBJXREF /RV /Ltest1.arf ------------------------------------- The TLINK response file TEST1.ARF contains the same list of files as the command line in Example 1. The /RV option is specified so that a report of every type will be generated. TEST1.ARF contains test1 test2 test1.exe test1.map \lib\io Example 3 C>OBJXREF /F /RV \lib\IO.lib ---------------------------------------- This example reports on all the modules in the library file IO.LIB; OBJXREF can produce useful reports even when the files specified don't make a complete program. The /F causes all modules in IO.LIB file to be included in the report. 6. OBJXREF DIAGNOSTIC MESSAGES ------------------------------ OBJXREF generates two sorts of diagnostic messages: error messages and warnings. Error messages -------------- Out of memory OBJXREF performs its cross-referencing in RAM memory and may run out of memory even if TLINK is able to link the same list of files successfully. When this happens, OBJXREF aborts. Remove memory-resident programs to get more space or add more RAM. Warnings --------- WARNING: Unable to open input file rrrr The input file rrrr could not be located or opened. OBJXREF proceeds to the next file. WARNING: Unknown option - oooo The option name oooo is not recognized by OBJXREF. OBJXREF ignores the option. WARNING: Unresolved symbol nnnn in module mmmm The public name nnnn referenced in module mmmm is not defined in any of the .OBJ or .LIB files specified. OBJXREF flags the symbol in any reports it generates as being referenced but not defined. WARNING: Invalid file specification ffff Some part of the file name ffff is invalid. OBJXREF proceeds to the next file. WARNING: No files matching ffff The file named ffff listed on the command line or in a response file could not be located or opened. OBJXREF skips to the next file. WARNING: Symbol nnnn defined in mmmm1 duplicated in mmmm2 Public name nnnn is defined in modules mmmm1 and mmmm2. OBJXREF ignores the second definition.