Jason Aller Floppy Collection

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

/ Jason Aller Floppy Collection / 240.img / TASM20-1.ZIP / MANUAL.ZIP / UTIL.DOC < prev

Wrap

Text File | 1990-05-07 | 37.3 KB | 1,111 lines

Turbo Assembler utilities Turbo Assembler provides six powerful stand-alone utilities. You can use these stand-alone utilities with your Turbo Assembler files, as well as with your other modules. MAKE, TLINK, and TLIB are documented in the Turbo Assembler Reference Guide; some additional information about TLINK is included at the beginning of this file. GREP (a file-search utility), OBJXREF (an object module cross-referencer), and TCREF (a cross-reference utility) are documented here. TLINK: Turbo Link When a detailed map is requested through use of the /s switch, the list of public symbols (if it appears) has public symbols flagged with "idle" if there are no references to that symbol. For example, this fragment from the public symbol section of a map file indicates that symbols Symbol1 and Symbol3 are not referenced by the image being linked: 0C7F:031E idle Symbol1 0000:3EA2 Symbol2 0C7F:0320 idle Symbol3 /o switch (overlays) The /o option causes the code in all modules or libraries specified after the option to be overlaid. It remains in effect until the next comma (explicit or implicit) or /o- in the command stream. /o- turns off overlaying. The /o option can be optionally followed by a segment class name; this will cause all segments of that class to be overlayed. When no such name is specified, all segments of classes ending with CODE will be overlayed. Multiple /o options can be given, thus overlaying segments of several classes; all /o options remain in effect until the next comma or /o- is encountered. The syntax /o#xx, where xx is a two-digit hexadecimal number, overrides the overlay interrupt number, which by default is 3FH. Here are some examples of /o options: /o Overlay all code segments until next comma or /o-. /o- Stop overlaying. /oOVY Overlay segments of class OVY until the next comma or /o-. /oCODE /oOVLY Overlay segments of class CODE or class OVLY until next comma or /o-. /o#F0 Use interrupt vector 0F0H for overlays. You can use the /o option in response files. If you use the /o option in a response file, it will be turned off automatically before the libraries are processed. If you want to overlay a library, you must use another /o right before all the libraries or right before the library you want to overlay. /y (expanded or extended memory) This switch controls TLINK's use of expanded or extended memory for I/O buffering. If, while reading object files or while writing the executable file, TLINK needs more memory for active data structures, it will either purge buffers or swap them to expanded or extended meory. In the case of input file buffering, purging simply means throwing away the input buffer so that its space can be used for other data structures. In the case of output file buffering, purging means writing the buffer to its correct place in the executable file. In either case, you can substantially increase the speed of a link by allowing these buffers to be swapped to expanded or extended memory. TLINK's capacity is not increased by swapping; only its performance is improved. By default, swapping to expanded memory is enabled, while swapping to extended memory is disabled. If swapping is enabled and no appropriate memory exists in which to swap, then swapping does not occur. This switch has several forms, shown below /ye enable expanded memory swapping (default) /ye disable expanded memory swapping /yx enable extended memory swapping /yx- disable extended memory swapping (default) GREP: A file-search utility GREP is a powerful search utility that can search for text in several files at once. The general command-line syntax for GREP follows: grep [options] searchstring filespec [filespec filespec ... filespec] For example, if you want to see in which source files you call the setupmodem function, you could use GREP to search the contents of all the .ASM files in your directory to look for the string setupmodem, like this: grep setupmodem *.asm The GREP options In the command line, options are one or more single characters preceded by a hyphen symbol (-). Each individual character is a switch that you can turn on or off: type the plus (+) after a character to turn the option on, or type a hyphen (-) after the character to turn the option off. The default is on (the + is implied): for example, -r means the same thing as -r+. You can list multiple options individually (like this: -i -d -l), or you can combine them (like this: -ild or -il - d, and so forth); they're all the same to GREP. Here is a list of the option characters used with GREP and their meanings: -c Count only: Only a count of matching lines is printed. For each file that contains at least one matching line, GREP prints the file name and a count of the number of matching lines. Matching lines are not printed. -d Directories: For each filespec specified on the command line, GREP searches for all files that match the file specification, both in the directory specified and in all subdirectories below the specified directory. If you give a filespec without a path, GREP assumes the files are in the current directory. -i Ignore case: GREP ignores uppercase/lowercase differences (case-folding). GREP treats all letters a-z as being identical to the corresponding letters A-Z in all situations. -l List match files: Only the name of each file containing a match is printed. After GREP finds a match, it prints the file name and processing immediately moves on to the next file. -n Numbers: Each matching line that GREP prints is preceded by its line number. -o UNIX output format: Changes the output format of matching lines to support more easily the UNIX style of command-line piping. All lines of output are preceded by the name of the file that contained the matching line. -r Regular expression search: The text defined by searchstring is treated as a regular expression instead of as a literal string. -u Update options: GREP will combine the options given on the command line with its default options and write these to the GREP.COM file as the new defaults. (In other words, GREP is self-configuring.) This option allows you to tailor the default option settings to your own taste. -v Non-match: Only non-matching lines are printed. Only lines that do not contain the search string are considered to be non-matching lines. -w Word search: Text found that matches the regular expression will be considered a match only if the character immediately preceding and following cannot be part of a word. The default word character set includes A-Z, 9-0, and the underscore (_). An alternate form of this option allows you to specify the set of legal word characters. Its form is -w[set], where set is any valid regular expression set definition. If alphabetic characters are used to define the set, the set will automatically be defined to contain both the uppercase and lowercase values for each letter in the set, regardless of how it is typed, even if the search is case-sensitive. If the -w option is used in combination with the -u option, the new set of legal characters is saved as the default set. -z Verbose: GREP prints the file name of every file searched. Each matching line is preceded by its line number. A count of matching lines in each file is given, even if the count is zero. Order of precedence Remember that each of GREP's options is a switch: Its state reflects the way you last "flipped" it. At any given time, each option can only be on or off. Each occurrence of a given option on the command line overrides its previous definition. For example, grep -r -i- -d -i -r- main( my*.asm Given this command line, GREP will run with the -d option on, the -i option on, and the -r option off. You can install your preferred default setting for each option in GREP.COM with the -u option. For example, if you want GREP to always do a verbose search (-z on), you can install it with the following command: grep -u -z The search string The value of searchstring defines the pattern GREP will search for. A search string can be either a regular expression or a literal string. In a regular expression, certain characters have special meanings: They are operators that govern the search. In a literal string, there are no operators; each character is treated literally. You can enclose the search string in quotation marks to prevent spaces and tabs from being treated as delimiters. Matches will not cross line boundaries (a match must be contained in a single line). An expression is either a single character or a set of characters enclosed in brackets. A concatenation of regular expressions is a regular expression. Operators in regular expressions When you use the -r option, the search string is treated as a regular expression (not a literal expression) and the following characters take on special meanings: ^ A circumflex at the start of the expression matches the start of a line. $ A dollar sign at the end of the expression matches the end of a line. . A period matches any character. * An expression followed by an asterisk wildcard matches zero or more occurrences of that expression. For example, in fo*, the * operates on the expression o; it matches f, fo, foo, and so on. (f followed by zero or more os), but doesn't match fa. + An expression followed by a plus sign matches one or more occurrences of that expression: fo+ matches fo, foo, and so on, but not f. [] A string enclosed in brackets matches any character in that string, but no others. If the first character in the string is a circumflex (^), the expression matches any character except the characters in the string. For example, [xyz] matches x, y, or z, while [^xyz} matches a and b, but not x, y, or z. You can specify a range of characters with two characters separated by a hyphen (-). These can be combined to form expressions (like [a-bd-z?] to match ? and any lowercase letter except c). \ The backslash escape character tells GREP to seach for the literal character that follows it. For example, \. matches a period instead of "any character." Note: Four of the previously described characters ($, ., *, and +) do not have any special meaning when used within a bracketed set. In addition, the character ^ is only treated specially if it immediately follows the beginning of the set definition (that is, immediately after the [). Any ordinary character not mentioned in the preceding list matches that character. (> matches >, # matches #, and so on.) The file specification The third item in the GREP command line is filespec, the file specification; it tells GREP which files (or groups of files) to search. filespec can be an explicit file name, or a generic file name incorporating the DOS ? and * wildcards. In addition, you can enter a path (drive and directory infor- mation) as part of filespec. If you give filespec without a path, GREP only searches the current directory. Examples with notes The following examples assume that all of GREP's options default to off: Example 1 Command line: grep start: *.asm Matches: start: restart: Does not match: restarted: ClockStart: Files Searched: *.ASM in current directory. Note: By default, the search is case-sensitive. Example 2 Command line: grep -r [^a-z]main\ *( *.asm Matches: main(i:integer) main(i,j:integer) if (main ()) halt; Does not match: mymain() MAIN(i:integer); Files Searched: *.ASM in current directory. Note: GREP searches for the word main with no preceding lowercase letters ([^a-z]), followed by zero or more occurrences of blank spaces (\ *), then a left parenthesis. Since spaces and tabs are normally considered to be command-line delimiters, you must quote them if you want to include them as part of a regular expression. In this case, the space after main is quoted with the backslash escape character. You could also accomplish this by placing the space in double quotes [^a-z]main" "* Example 3 Command line: grep -ri [a-c]:\\data\.fil *.asm *.inc Matches: A:\data.fil c:\Data.Fil B:\DATA.FIL Does not match: d:\data.fil a:data.fil Files Searched: *.ASM and *.INC in current directory. Note:Because the backslash and period characters (\ and .) usually have special meaning, if you want to search for them, you must quote them by placing the backslash escape character immediately in front of them. Example 4 Command line: grep -ri [^a-z]word[^a-z] *.doc Matches: every new word must be on a new line. MY WORD! word--smallest unit of speech. In the beginning there was the WORD, and the WORD Does not match: Each file has at least 2000 words. He misspells toward as toword. Files Searched: *.DOC in the current directory. Note: This format basically defines how to search for a given word. Example 5 Command line: grep -iw word *.doc Matches: every new word must be on a new line However, MY WORD! word: smallest unit of speech that conveys meaning. In the beginning there was the WORD, and the WORD Does not match: each document contains at least 2000 words! He seems to continually misspell "toward" as "toword." Files searched: *.doc in the current directory. Note: This format defines a basic "word" search. Example 6 Command line: grep "search string with spaces" *.doc *.asm a:\work\myfile.* Matches: This is a search string with spaces in it. Does not match: THIS IS A SEARCH STRING WITH SPACES IN IT. This is a search string with many spaces in it. Files Searched: *.DOC and *.ASM in the current directory, and MYFILE.* in a directory called \WORK on drive A:. Note: This is an example of how to search for a string with embedded spaces. Example 7 Command line: grep -rd "[ ,.:?'\"]"$ \*.doc Matches: He said hi to me. Where are you going? Happening in anticipation of a unique situation, Examples include the following: "Many men smoke, but fu man chu." Does not match: He said "Hi" to me Where are you going? I'm headed to the beach this Files Searched: *.DOC in the root directory and all its subdirectories on the current drive. Note: This example searches for the characters ,.:?' and " at the end of a line. Notice that the double quote within the range is preceded by an escape character so it is treated as a normal character instead of as the ending quote for the string. Also, notice how the $ character appears outside of the quoted string. This demonstrates how regular expressions can be concatenated to form a longer expression. Example 8 Command line: grep -ild " the " \*.doc or grep -i -l -d " the " \*.doc or grep -il -d " the " \*.doc Matches: Anyway, this is the time we have do you think? The main reason we are Does not match: He said "Hi" to me just when I Where are you going? I'll bet you're headed to Files Searched: *.DOC in the root directory and all its subdirectories on the current drive. Note: This example ignores case and just prints the names of any files that contain at least one match. The three examples show different ways of specifying multiple options. OBJXREF: The object module cross-reference utility 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 in the section "Sample OBJXREF Reports" on page 48 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. The OBJXREF command line 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 in the next section "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. Command-line 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. (See example 4 in the section "OBJXREF Examples.") /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. Freeform response files 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 a 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. Linker response files 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, "Examples using OBJXREF." 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. Sample 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. Such a symbol is either 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). 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. Examples using OBJXREF 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. Error messages and warnings 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. TCREF: The source module cross-reference utility TCREF is designed to produce two reports: a cross-reference list of where all global symbols are used and defined, and a list of individual modules and the symbols used within them. TCREF accepts as input a group of .XRF files produced by TASM. These files contain cross-reference information for individual modules. From these input files, a single .REF file is produced that contains one or more reports in ASCII text. The command format follows: TCREF <XRF files separated by '+' characters> ',' <REF filename> <switches> For example, the following would take the FOO1.XRF, FOO2.XRF, and FOO3.XRF as input files and produce FOO.REF: TCREF foo1+foo2+foo3,foo Response files TCREF also accepts ASCII files as command strings. Simply precede the file name with an @ sign to include a file in the command string. For example, TCREF @dofoo where DOFOO contains foo1+foo2+foo3,foo will do the same thing as the previous example. Compatibility with TLINK TCREF accepts command strings that TLINK accepts. TCREF ignores any irrelevant switches and fields, such as any libraries or MAP files, or switches that pertain only to the linker function. Similarly, if an .XRF file cannot be located, TCREF will simply ignore it. Beware! When using a TLINK response file, don't explicitly specify file extensions, since doing so will override TCREF's internal defaults and possibly result in disaster. For example, if the response file reads a foo1+foo2+foo3,foo.exe you should not use this file without modification with TCREF because the .REF file it creates will be named FOO.EXE, presumably overwriting your program. Switches TCREF accepts all the switches present in TLINK, but most of them are discarded. TCREF only uses these switches: /c makes GLOBAL report case-sensitive. /r generates LOCAL reports for all the specified modules. /p# sets report page length to # lines. /w# sets report page width to # columns. Output TCREF takes great care to make semantic sense of symbols.Cross-reference information is useless when symbols with the same name but different meanings are lumped together. TCREF therefore takes into account the SCOPE of a symbol when producing its reports. Cross-reference information is always listed for the source file and source line number. The global (or linker-scope) report TCREF's global report lists cross-reference information for global symbols as they appear to the linker. Use the /c switch if you want to produce case-sensitive reports. In this report, global symbols appear alphabetically in the left column. References, organized by source file, are listed in the right column. Wherever #'s appear indicates that definition occurs at that line. Here's an example symbol printout: Global Symbols Cref # = definition BAR TEST.ASM: 1 3 6 9 12 15 18 + 21 23 29 # TEST2.ASM: 2 4 6 #8 What does this tell you? The leading # sign before the TEST2.ASM indicates that BAR was defined somewhere in that module. For each source file, the source line at which the reference occurred is listed. This list can occupy more than one line, as in the case of the lines for TEST.ASM. The + character indicates that wrap has occurred. Finally, the # sign before the 8 indicates that a definition of BAR occurred in TEST2.ASM on line 8. The local (or module-scope) report If you specify /r on the command line, a local report will be made for each module. It will contain all the symbols used in that module, listed in alphabetical order. The /c switch will have no effect on these reports, since the appropriate case-sensitivity has already been determined at assembly time. Like global reports, references are organized by source file in the right column. A sample printout looks like this: Module TEST.ASM Symbols Cref # = definition UGH TEST.ASM: 1 3 6 9 12 15 18 + 21 23 29 # UGH.INC: #2