UTIL.DOC file accompanying version 3.1 of Borland

Written by Embarcadero USA on Posted in PROGRAMMING

 Technical Notes Database

TN2539C.txt   UTIL.DOC file accompanying version 3.1 of Borland 
Category   :OTHER
Platform    :All
Product    :BC  3.10


Online document
                                                            Other utilities
                    This file has a table of contents and an index that
                    refer to "pages" in this file. If your editor has a
                    search facility, you can use it to search for the page
                    numbers listed in either the table of contents or in
                    the index. The phrase "Page n" (where n represents the
                    actual page number) appears at the bottom left of the
                    "page" it refers to. Thus, at the bottom of page 1,
                    you'll find "Page 1" as the last item on that "page."
           Other utilities                 Report by external references
                                           (/RX) . . . . . . . . . . . . 27
BGIOBJ: Converting graphics drivers        Report of module sizes
and fonts  . . . . . . . . . . . . 2       (/RS) . . . . . . . . . . . . 27
  Adding the new .OBJ files to             Report by class type (/RC)  . 27
  GRAPHICS.LIB . . . . . . . . . . 3       Report of unreferenced symbol
  Registering the drivers and              names (/RU) . . . . . . . . . 28
  fonts  . . . . . . . . . . . . . 3       Verbose reporting (/RV) . . . 29
    An example . . . . . . . . . . 4     Examples of how to use
  The /F option  . . . . . . . . . 5     OBJXREF . . . . . . . . . . . . 29
  Advanced features  . . . . . . . 5       Example 1 . . . . . . . . . . 29
CPP: The preprocessor  . . . . . . 9       Example 2 . . . . . . . . . . 29
  CPP as a macro preprocessor  .  10       Example 3 . . . . . . . . . . 29
  An example . . . . . . . . . .  10       Example 4 . . . . . . . . . . 30
GREP: A text-search utility  . .  11     OBJXREF error messages and
  Command-line syntax  . . . . .  11     warnings  . . . . . . . . . . . 30
  GREP options . . . . . . . . .  12       Error messages  . . . . . . . 30
    Order of precedence  . . . .  14       Warnings  . . . . . . . . . . 30
  The search string  . . . . . .  14   PRJCFG: Configuration file
    Operators in regular               utility . . . . . . . . . . . . . 31
    expressions  . . . . . . . .  15   PRJCNVT: Old projects for new . . 31
  File specifications  . . . . .  16   PRJ2MAK: From project file to MAKE
  Some GREP examples . . . . . .  16   file  . . . . . . . . . . . . . . 32
    Example 1  . . . . . . . . .  16   THELP: The Turbo Help utility . . 33
    Example 2  . . . . . . . . .  17     Loading and invoking THELP  . . 33
    Example 3  . . . . . . . . .  17     Navigating THELP  . . . . . . . 34
    Example 4  . . . . . . . . .  17     THELP options . . . . . . . . . 35
    Example 5  . . . . . . . . .  18       /C#xx (select color)  . . . . 35
    Example 6  . . . . . . . . .  18       /Fname (full path and name for
    Example 7  . . . . . . . . .  19       help file)  . . . . . . . . . 36
    Example 8  . . . . . . . . .  19       /H, /?, and ? (display help
OBJXREF: The object module cross-          screen) . . . . . . . . . . . 37
reference utility  . . . . . . .  20       /Kxxyy (reassign hot key) . . 37
  The OBJXREF command line . . .  20       /U (remove THELP from
    The OBJXREF command-line               memory) . . . . . . . . . . . 38
    options  . . . . . . . . . .  21       /Wx,y,w,h (set the window size
      Control options  . . . . .  21       and location) . . . . . . . . 38
      Report options . . . . . .  23   TOUCH . . . . . . . . . . . . . . 38
  Response files . . . . . . . .  24   TRANCOPY: A project transfer item
    Free-form response files . .  24   utility . . . . . . . . . . . . . 39
    Project files  . . . . . . .  24   TRIGRAPH: A character-conversion
    Linker response files  . . .  25   utility . . . . . . . . . . . . . 39
  Sample OBJXREF reports . . . .  25   Transfer macros . . . . . . . . . 40
    Report by public names                   State macros  . . . . . . . 40
    (/RP)  . . . . . . . . . . .  26         File name macros  . . . . . 41
    Report by module (/RM) . . .  26         Instruction macros  . . . . 41
    Report by reference (/RR)  .  26     Running DOS commands  . . . . . 46
  Transfer memory settings . . .  47     Named keys  . . . . . . . . . . 50
Turbo Editor macros  . . . . . .  47   Predefined editor commands  . . . 51
TEMC command line  . . . . . . .  47
Syntax . . . . . . . . . . . . .  48   Index                             61
Key codes  . . . . . . . . . . .  49
                    Borland C++ comes with a host of standalone utilities
                    that you can use with your Borland C++ files or other
                    modules. Several are documented in the Tools and
                    Utilities Guide; others are documented here.
                    Name       Description
                    Documented in the Tools and Utilities Guide
                    IMPDEF     Creates a module definition file
                    IMPLIB     Generates an import library
                    IMPLIBW    Windows application that generates an import
                    MAKE       Standalone program manager
                    TLIB       Turbo Librarian
                    TLINK      Turbo Linker
                    WinSight   Windows message monitor
                    Documented in this file
                    BGIOBJ     Conversion utility for graphics drivers and
                    CPP        Preprocessor
                                   - 1 -
                    GREP       File-search utility
                    OBJXREF    Object module cross-referencer
                    PRJCFG     Updates options in a project file from a
                               configuration file, or converts a project
                               file to a configuration file
                    PRJCNVT    Converts Turbo C project files to the
                               Borland C++ format
                    PRJ2MAK    Converts Borland C++ project files to MAKE
                    THELP      Turbo Help utility
                    TOUCH      Updates file date and time
                    TRANCOPY   Copies transfer items from one project to
                    TRIGRAPH   Character-conversion utility
                    TEML/TEMC  Turbo Editor Macro Language and Compiler
                    This file explains what each utility is and
                    illustrates, with code and command-line examples, how
                    to use them.
BGIOBJ: Converting graphics drivers and fonts
                    You can use BGIOBJ to convert graphics driver files and
                    character sets (stroked font files) to object (.OBJ)
                    files. Once they're converted, you can link them into
                    your program, making them part of the executable file.
                    This is in addition to the graphics package's dynamic
                    loading scheme, in which your program loads graphics
                    drivers and character sets (stroked fonts) from disk at
                    run time.
                    Linking drivers and fonts directly into your program is
                    advantageous because the executable file contains all
                    (or most) of the drivers and/or fonts it might need,
                    and doesn't need to access the driver and font files on
                    disk when running. However, linking the drivers and
                    fonts into your executable file increases its size.
                    To convert a driver or font file to a linkable object
                    file, use the BGIOBJ.EXE utility. This is the
                    simplified syntax:
                      BGIOBJ source_file
                    where source_file is the driver or font file to be
                    converted to an object file. The object file created
                    has the same file name as the source file, with the
                                   - 2 -
                    extension .OBJ; for example, EGAVGA.BGI yields
                    EGAVGA.OBJ, SANS.CHR gives SANS.OBJ, and so on.
    Adding the new  =======================================================
     .OBJ files to
      GRAPHICS.LIB  You should add the driver and font object modules to
                    GRAPHICS.LIB, so the linker can locate them when it
                    links in the graphics routines. If you don't add these
                    new object modules to GRAPHICS.LIB, you'll have to add
                    them to the list of files in the project (.PRJ) file,
                    on the BCC command line, or on the TLINK command line.
                    To add these object modules to GRAPHICS.LIB, invoke
                    TLIB with the following command line:
                      tlib graphics + object_file_name [+ object_file_name
                    where object_file_name is the name of the object file
                    created by BGIOBJ.EXE (such as CGA, EGAVGA, GOTH, and
                    so forth). The .OBJ extension is implied, so you don't
                    need to include it. You can add several files with one
                    command line to save time; see the example in the
                    following section.
   Registering the  =======================================================
 drivers and fonts
                    After adding driver and font object modules to
                    GRAPHICS.LIB, you have to register all the drivers and
                    fonts that you want linked in; you do this by calling
                    registerbgidriver and registerbgifont in your program
                    (before calling initgraph). This informs the graphics
                    system of the presence of those files, and ensures that
                    they will be linked in when the executable file is
                    created by the linker.
                    The registering routines each take one parameter; a
                    symbolic name defined in graphics.h. Each registering
                    routine returns a nonnegative value if the driver or
                    font is successfully registered.
                    The following table shows the names to be used with
                    registerbgidriver and registerbgifont. It is a complete
                    list of drivers and fonts included with Borland C++.
 Driver file     registerbgidriver      Font file   registerbgifont
 (*.BGI)         symbolic name          (*.CHR)     symbolic name
 CGA             CGA_driver             TRIP        triplex_font
 EGAVGA          EGAVGA_driver          LITT        small_font
                                   - 3 -
 HERC            Herc_driver            SANS        sansserif_font
 ATT             ATT_driver             GOTH        gothic_font
 PC3270          PC3270_driver
 IBM8514         IBM8514_driver
------------------  Suppose you want to convert the files for the CGA
        An example  graphics driver, the gothic font, and the triplex font
------------------  to object modules, then link them into your program.
                    Here's what you do:
                    1. Convert the binary files to object files using
                       BGIOBJ.EXE, as shown in the following separate com-
                       mand lines:
                        bgiobj  cga
                        bgiobj  trip
                        bgiobj  goth
                       This creates three files: CGA.OBJ, TRIP.OBJ, and
                    2. You can add these object files to GRAPHICS.LIB with
                       this TLIB command line:
                          tlib  graphics  +cga  +trip  +goth
                    3. If you don't add the object files to GRAPHICS.LIB,
                       you must add the object file names CGA.OBJ,
                       TRIP.OBJ, and GOTH.OBJ to your project list (if you
                       are using Borland C++'s integrated environment), or
                       to the BCC command line. For example, the BCC com-
                       mand line would look like this:
                          BCc  niftgraf graphics.lib  cga.obj  trip.obj
                    4. You register these files in your graphics program
                       like this:
 If you ever get a      /* Header file declares CGA_driver, triplex_font &
      linker error      gothic_font */
   Segment exceeds      #include 
 64K after linking
   in some drivers      /* Register and check for errors (one never
     and/or fonts,      knows...) */
      refer to the
following section.      if (registerbgidriver(CGA_driver) < 0) exit(1);
                        if (registerbgifont(triplex_font) < 0) exit(1);
                        if (registerbgifont(gothic_font)  < 0) exit(1);
                        /* ... */
                                   - 4 -
                        initgraph(....);     /* initgraph should be called
                                                after registering */
                        /* ... */
     The /F option  =======================================================
                    This section explains what steps to take if you get the
                    linker error Segment exceeds 64K (or a similar error)
                    after linking in several driver and/or font files
                    (especially with small- and compact-model programs).
                    By default, the files created by BGIOBJ.EXE all use the
                    same segment (called _TEXT). This can cause problems if
                    your program links in many drivers and/or fonts, or
                    when you're using the small or compact memory model.
                    To solve this problem, you can convert one or more of
                    the drivers or fonts with the BGIOBJ /F option. This
                    option directs BGIOBJ to use a segment name of the form
                    filename_TEXT, so that the default segment is not
                    overburdened by all the linked-in drivers and fonts
                    (and, in small and compact model programs, all the pro-
                    gram code). For example, the following two BGIOBJ com-
                    mand lines direct BGIOBJ to use segment names of the
                    form EGAVGA_TEXT and SANS_TEXT.
                     bgiobj  /F  egavga
                     bgiobj  /F  sans
                    When you select /F, BGIOBJ also appends F to the target
                    object file name (EGAVGAF.OBJ, SANSF.OBJ, and so
                    forth), and appends _far to the name that will be used
                    with registerfarbgidriver and registerfarbgifont. (For
                    example, EGAVGA_driver becomes EGAVGA_driver_far.)
                    For files created with /F, you must use these far
                    registering routines instead of the regular
                    registerbgidriver and registerbgifont. For example,
                     if (registerfarbgidriver(EGAVGA_driver_far) < 0)
                     if (registerfarbgifont(sansserif_font_far)  < 0)
 Advanced features  =======================================================
                    This section explains some of BGIOBJ's advanced
                    features, and the routines registerfarbgidriver and
                    registerfarbgifont. Only experienced users should use
                    these features.
                                   - 5 -
                    This is the full syntax of the BGIOBJ.EXE command line:
                       BGIOBJ  [/F] source destination public-name seg-name
                    This table describes each component of the BGIOBJ com-
                    mand line.
                    Component              Description
                    /F or -F               This option instructs BGIOBJ.EXE
                                           to use a segment name other than
                                           _TEXT (the default), and to
                                           change the public name and
                                           destination file name. (See page
                                           5 for a detailed discussion of
                    source                 This is the driver or font file
                                           to be converted. If the file is
                                           not one of the driver/font files
                                           shipped with Borland C++, you
                                           should specify a full file name
                                           (including extension).
                    destination            This is the name of the object
                                           file to be produced. The default
                                           destination file name is
                                           source.OBJ, or sourceF.OBJ if
                                           you use the /F option.
                    public-name            This is the name that will be
                                           used in the program in a call to
                                           registerbgidriver or
                                           registerbgifont (or their
                                           respective far versions) to link
                                           in the object module.
                                           The public name is the external
                                           name used by the linker, so it
                                           should be the name used in the
                                           program, prefixed with an
                                           underscore. If your program uses
                                           Pascal calling conventions, use
                                           only uppercase letters, and do
                                           not add an underscore.
                    seg-name               This is an optional segment
                                           name; the default is _TEXT (or
                                   - 6 -
                                           filename_TEXT if /F is
                    seg-class              This is an optional segment
                                           class; the default is CODE.
                    All parameters except source are optional. However, if
                    you need to specify an optional parameter, all the
                    parameters preceding it must also be specified.
                    If you choose to use your own public name(s), you have
                    to add declaration(s) to your program, using one of the
                    following forms:
                     void public_name(void);        /* if /F not used, */
                                                    /* default segment name
                     used */
                     extern int far public_name[];  /* if /F used, or */
                                                    /* segment name not
                     _TEXT */
                    In these declarations, public_name matches the public-
                    name you used when converting with BGIOBJ. The
                    graphics.h header file contains declarations of the
                    default driver and font public names; if you use those
                    default public names you don't have to declare them as
                    just described.
                    After these declarations, you have to register all the
                    drivers and fonts in your program. If you don't use the
                    /F option and don't change the default segment name,
                    you should register drivers and fonts through
                    registerbgidriver and registerbgifont; otherwise, use
                    registerfarbgidriver and registerfarbgifont.
                    Here is an example of a program that loads a font file
                    into memory:
                     /* Example of loading a font file into memory */
                                   - 7 -
                        void    *gothic_fontp;    /* points to font buffer
                     in memory */
                        int      handle;          /* file handle used for
                     I/O */
                        unsigned fsize;           /* size of file (and
                     buffer) */
                        int errorcode;
                        int graphdriver;
                        int graphmode;
                     /* open font file */
                        handle = open("GOTH.CHR", O_RDONLY|O_BINARY);
                        if (handle == -1)
                           printf("unable to open font file 'GOTH.CHR'\n");
                     /* find out size of the file */
                        fsize = filelength(handle);
                     /* allocate buffer */
                        gothic_fontp = malloc(fsize);
                        if (gothic_fontp == NULL)
                          printf("unable to allocate memory for font file
                     /* read font into memory */
                        if (read(handle, gothic_fontp, fsize) != fsize)
                           printf("unable to read font file 'GOTH.CHR'\n");
                     /* close font file */
                     /* register font */
                        if (registerfarbgifont(gothic_fontp) !=
                           printf("unable to register font file
                     /* detect and initialize graphix */
                        graphdriver = DETECT;
                        initgraph(&graphdriver, &graphmode, "..");
                        errorcode = graphresult();
                        if (errorcode != grOk)
                           printf("graphics error:
                                   - 8 -
                        settextjustify(CENTER_TEXT, CENTER_TEXT);
                        settextstyle(GOTHIC_FONT, HORIZ_DIR, 4);
                                  "Borland Graphics Interface (BGI)");
                     /* press a key to terminate */
                     /* shut down graphics system */
CPP: The preprocessor
    CPP produces a  Often, when the compiler reports an error inside a
  list (in a file)  macro or an include file, you can get more information
     of a C source  about what the error is if you can see the include
  program in which  files or the results of the macro expansions. In many
 include files and  multi-pass compilers, a separate pass performs this
    #define macros  work, and the results of the pass can be examined.
         have been  Since Borland C++ uses an integrated single-pass com-
   expanded. It is  piler, we provided CPP to supply the first-pass
    not needed for  functionality found in other compilers.
    normal compil-
       ations of C  You use CPP just as you would use BCC, the standalone
         programs.  compiler. CPP reads the same TURBOC.CFG file for
                    default options, and accepts the same command-line
                    options as BCC.
                    The BCC options that don't pertain to CPP are simply
                    ignored by CPP. To see the list of arguments handled by
                    CPP, type cpp at the DOS prompt. To see how those
                    arguments work, see Chapter 5 in the Programmer's
                    With one exception, the file names listed on the CPP
                    command line are treated like they are in BCC, with
                    wildcards allowed. The exception to this is that all
                    files are treated as C source files. There is no
                    special treatment for .OBJ, .LIB, or .ASM files.
                    For each file processed by CPP, the output is written
                    to a file in the current directory (or the output
                    directory named by the -n option) with the same name as
                    the source name but with an extension of .I.
                    This output file is a text file containing each line of
                    the source file and any include files. Any preproces-
                    sing directive lines have been removed, along with any
                    conditional text lines excluded from the compile.
                    Unless you use a command-line option to specify other-
                                   - 9 -
                    wise, text lines are prefixed with the file name and
                    line number of the source or include file the line came
                    from. Within a text line, any macros are replaced with
                    their expansion text.
        Important!  The resulting output of CPP cannot be compiled because
                    of the file name and line number prefix attached to
                    each source line.
    CPP as a macro  =======================================================
                    The -P option to CPP tells it to prefix each line with
                    the source file name and line number. If you give it -
                    P- (turning this option off), CPP omits this line
                    number information. With this option turned off, CPP
                    can be used as a macro preprocessor; the resulting .I
                    file can then be compiled with BC or BCC.
        An example  =======================================================
                    The following simple program illustrates how CPP
                    preprocesses a file, first with -P selected, then with
                    Source file: HELLOAJ.C
                     #define NAME "H.R. Floyd"
                     #define BEGIN {
                     #define END   }
                        printf("%s\n", NAME);
                    Command line used to invoke CPP as a preprocessor:
                       CPP HELLOAJ.C
                     HELLOAJ.c 1:
                     HELLOAJ.c 2:
                     HELLOAJ.c 3:
                     HELLOAJ.c 4:
                     HELLOAJ.c 5: main()
                     HELLOAJ.c 6: {
                     HELLOAJ.c 7:    printf("%s\n","H.R. Floyd");
                     HELLOAJ.c 8: }
                    Command line used to invoke CPP as a macro
                       CPP -P- HELLOAJ.C
                                  - 10 -
                        printf("%s\n","H.R. Floyd");
GREP: A text-search utility
                    GREP (Global Regular Expression Print) is a powerful
                    text-search program derived from the UNIX utility of
                    the same name. GREP searches for a text pattern in one
                    or more files or in its standard input stream.
                    Here's a quick example of a situation where you might
                    want to use GREP. Suppose you wanted to find out which
                    text files in your current directory contained the
                    string "Bob". You would issue the command
                       grep Bob *.txt
                    and GREP would respond with a list of the lines in each
                    file (if any) that contained the string "Bob". Because
                    the default for GREP is to ignore case, the strings
                    "bob" and "BoB" would also be considered matches. You
                    can use options to make your search case sensitive.
                    GREP can do a lot more than match a single, fixed
                    string. In the section that follows, you'll see how to
                    make GREP search for any string that matches a
                    particular pattern.
      Command-line  =======================================================
                    The general command-line syntax for GREP is
                      grep [options] searchstring [file(s) ... ]
                    options consist of one or more letters, preceded by a
                    hyphen (-), that let you change various aspects of
                    GREP's behavior.
                    searchstring gives the pattern to search for.
                    file(s) tells GREP which files to search. (If you don't
                    specify a file, GREP searches its standard input; this
                    lets you use GREP with pipes and redirection.) If you
                    find that the results of your GREP are longer than one
                    screen, you can redirect the output to a file. For
                    example, you could use this command
                                  - 11 -
                       GREP "Bob" *.txt >gfile
                    which searches all files in the current directory that
                    end with .TXT, then places the results in a file called
                    GFILE. (You can name this file anything you like.)
                    Then, use your word processor (or Borland C++'s editor)
                    to access GFILE to read the results of the search.
                    The command
                       GREP ?
                    prints a brief help screen showing GREP's command-line
                    options, special characters, and defaults. (See the
                    description of the -u command-line option for
                    information on how to change GREP's defaults.)
      GREP options  =======================================================
                    In the command line, options are one or more single
                    characters preceded by a hyphen (-). Each individual
                    character is a switch that you can turn on or off: A
                    plus symbol (+) after a character turns the option on;
                    a hyphen (-) after the character turns the option off.
                    The + sign is optional; 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 on); it's all
                    the same to GREP.
                    Here are the GREP option characters and their meanings:
Option Meaning
  -c   Match Count only: Prints only a count of matching lines. 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. This option is off by default.
  -d   Search subdirectories: For each file 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 file without a path, GREP assumes the files
       are in the current directory. This option is off by default.
  -i   Ignore case: GREP ignores upper/lowercase differences (case folding).
       When this option is on, GREP treats all letters a to z as identical to
       the corresponding letters A to Z in all situations. This option is on
       by default.
                                  - 12 -
  -l   List file names only: Prints only the name of each file containing a
       match. After GREP finds a match, it prints the file name and processing
       immediately moves on to the next file. This option is off by default.
  -n   Line Numbers: Each matching line that GREP prints is preceded by its
       line number. This option is off by default.
  -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. This option is off by default.
  -r   Regular expression search: The text defined by searchstring is treated
       as a regular expression instead of as a literal string. This option is
       on by default. This option is on by default.
       A regular expression is one or more occurrences of one or more
       characters optionally enclosed in quotes. The following symbols are
       treated specially:
        ^  start of line       $  end of line
        .  any character       \  quote next character
        *  match zero or more  +  match one or more
        [aeiou0-9]             match a, e, i, o, u, and 0 thru 9
        [^aeiou0-9]            match anything but a, e, i, o, u, and 0 thru 9
  -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. If
       you want to see what the defaults are in a particular copy of GREP.COM,
        GREP ?
       at the DOS prompt. Each option on the help screen will be followed by a
       + or a - depending on its default setting. This option is off by
  -v   Nonmatch: Prints only nonmatching lines. Only lines that do not contain
       the search string are considered to be nonmatching lines. This option
       is off by default.
  -w   Word search: Text found that matches the regular expression is
       considered a match only if the character immediately preceding and
       following cannot be part of a word. The default word character set
       includes A to Z, 0 to 9, and the underscore ( _ ). This option is off
       by default.
       An alternate form of this option lets you specify the set of legal word
       characters. Its form is -w[set], where set is any valid regular
       expression set definition.
                                  - 13 -
       If you define the set with alphabetic characters, it is automatically
       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 you use the -w option 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. This option is off by
------------------  Remember that each of GREP's options is a switch: Its
          Order of  state reflects the way you last set it. At any given time,
        precedence  each option can only be on or off. Each occurrence of a
------------------  given option on the command line overrides its previous
                    definition. Given this command line,
                       grep -r -i - -d -i -r -  main( my*.c
                    GREP runs 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  ==========================================================
                    To use GREP well, you'll need to become proficient at
                    writing search strings. The value of searchstring defines
                    the pattern GREP searches for. A search string can be
                    either a regular expression or a literal string.
                    o In a regular expression, certain characters have special
                      meanings: They are operators that govern the search.
                    o 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.
                    The text matched by the search string cannot cross line
                    boundaries; that is, all the text necessary to match the
                    pattern must be on a single line.
                                  - 14 -
                    A regular expression is either a single character or a set
                    of characters enclosed in brackets. A concatenation of
                    regular expressions is a regular expression.
------------------  When you use the -r option (on by default), the search
      Operators in  string is treated as a regular expression (not a literal
           regular  expression). The following characters take on special
       expressions  meanings:
Option Meaning
  ^    A circumflex at the start of the expression matches the start of a
  $    A dollar sign at the end of the expression matches the end of a
  .    A period matches any character.
  *    An expression followed by an asterisk wildcard matches zero or more
       occurrences of that expression. For example, in to*, the * operates
       on the expression o; it matches t, to, too, etc. (t followed by zero
       or more os), but doesn't match ta.
  +    An expression followed by a plus sign matches one or more
       occurrences of that expression: to+ matches to, too, etc., but not
  [ ]  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?], which matches the ? character and any
       lowercase letter except c).
  \    The backslash escape character tells GREP to search for the literal
       character that follows it. For example, \. matches a period instead
       of "any character." The backslash can be used to quote itself; that
       is, you can use \\ to indicate a literal backslash character in a
       GREP expression.
              Note  Four of the "special" characters ($, ., *, and +) don't
                    have any special meaning when used within a bracketed
                                  - 15 -
                    set. In addition, the character ^ is only treated
                    specially if it immediately follows the beginning of
                    the set definition (immediately after the [ delimiter).
                    Any ordinary character not mentioned in the preceding
                    list matches that character. For example, the greater
                    than sign, >, matches the greater than sign (>), #
                    matches #, and so on.
              File  =======================================================
                    file(s) tells GREP which files (or groups of files) to
                    search. file(s) 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 information) as part of file(s). If you give
                    file(s) without a path, GREP searches the current
                    If you don't specify any files, input to GREP must come
                    from redirection (<) or a vertical bar (|).
Some GREP examples  =======================================================
                    The following examples show how to combine GREP's
                    features to do different kinds of searches. They assume
                    GREP's default settings are unchanged.
------------------  The search string here tells GREP to search for the
         Example 1  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.
                    Command line:
                                grep -r [^a-z]main\ *( *.c
                    Matches:    main(i:integer)
                                if (main  ()) halt;
                                if (MAIN  ()) halt;
                    Does not match:
                                  - 16 -
                    Files searched:
                                *.C in current directory.
------------------  Because the backslash (\) and period (.) characters
         Example 2  usually have special meaning in path and file names,
------------------  you must place the backslash escape character immedi-
                    ately in front of them if you want to search for them.
                    The -i option is used here, so the search is not case
                    Command line:
                                grep -ri [a-c]:\\data\.fil *.c *.inc
                    Matches:    A:\data.fil
                    Does not match:
                    Files searched:
                                *.C and *.INC in current directory.
------------------  This format defines how to search for a given word.
         Example 3
------------------  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.
------------------  This format defines another, even more basic single-
         Example 4  word search.
                    Command line:
                                grep -iw word *.doc
                    Matches:    every new word must be on a new line
                                MY WORD!
                                  - 17 -
                                word: smallest unit of speech which conveys
                                In the beginning there was the WORD, and
                    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.
------------------  This is an example of how to search for a string with
         Example 5  embedded spaces.
                    Command line:
                                grep "search string with spaces" *.doc *.c
                    Matches:    This is a search string with spaces in it.
                    Does not match:
                                This search string has spaces in it.
                    Files searched:
                                *.DOC and *.C in the current directory, and
                                MYFILE.* in a directory called \WORK on
                                drive A.
------------------  This example searches for any one of the characters
         Example 6  " . : ? ' and , at the end of a line.
                    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,
                    the $ character appears outside of the quoted string.
                    This demonstrates how regular expressions can be
                    concatenated to form a longer expression.
                    Command line:
                                grep -rd "[ ,.:?'\"]"$ \*.doc
                    Matches:    He said hi to me.
                                Where are you going?
                                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
                                  - 18 -
                    Files searched:
                                *.DOC in the root directory and all its
                                subdirectories on the current drive.
------------------  This example ignores case and just prints the names of
         Example 7  any files that contain at least one match. The three
------------------  command-line examples show different ways of specifying
                    multiple options.
                    Command line:
                                grep -ild " the " \*.doc
                                grep -i -l -d " the " \*.doc
                                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
                    Files searched:
                                *.DOC in the root directory and all its
                                subdirectories on the current drive.
------------------  This example redefines the current set of legal
         Example 8  characters for a word as the assignment operator (=)
------------------  only, then does a word search. It matches C assignment
                    statements, which use a single equal sign (=), but not
                    equality tests, which use a double equal sign (==).
                    Command line:
                                grep -w[=] = *.c
                    Matches:    i = 5;
                                i += j;
                    Does not match:
                                if (i == t) j++;
                                /* ======================= */
                    Files searched:
                                *.C in the current directory.
                                  - 19 -
OBJXREF: The object module cross-reference utility
                    OBJXREF 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.C and TEST2.C
                    files in the section "Sample OBJXREF reports" (page 25)
                    illustrate definitions of public names and external
                    references to them.
                    Object modules are object (.OBJ) files produced by BC,
                    BCC or TASM. A library (.LIB) file contains multiple
                    object modules. An object module generated by BC is
                    given the same name as the .C source file it was com-
                    piled from. This is also true for BCC, unless a
                    different output file name is specifically indicated
                    with the -o BCC command-line option.
  The OBJXREF com-  =======================================================
         mand 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
                    that OBJXREF will generate and the amount of detail
                    that OBJXREF will provide. They are discussed in more
                    detail in the next section.
                    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 com-
                    mand 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
                                  - 20 -
                    correctly, including the startup .OBJ file and one or
                    more C 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 you don't give a
                    file extension, 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 can 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.
------------------  OBJXREF command-line options fall into two categories:
       The OBJXREF  control options and report options.
------------------  Control options
                    Control options modify the default behavior of OBJXREF
                    (the default is that none of these options are
                    Option Meaning
                      /I   Ignore case differences in public names. Use
                           this option if you use TLINK without the /C
                           option (which makes case differences
                      /D   Look for .OBJ files in another directory. 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:
                              OBJXREF /Ddir1 [; dir2 [; dir3]]
                              OBJXREF /Ddir1 [/Ddir2] [/Ddir3]
                                  - 21 -
                           OBJXREF will search each of the directories in
                           the specified order for all object and library
        Important!         If you don't use a /D option, OBJXREF will
                           search only the current directory. If you do use
                           a /D option, however, the current directory will
                           not be searched unless it is included in the
                           directory list. For example, if you wanted
                           OBJXREF to search first the BORLAND directory
                           and then the current directory for files, you
                           would enter
                              OBJXREF /Dborland;.
                           The period denotes the current directory.
                      /F   Include full library. All object modules in
                           specified .LIB files are included even if they
                           do not contain public names that 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.")
                      /O   Allows you to specify an output file where
                           OBJXREF will send any reports generated. Its
                           syntax is as follows:
                              OBJXREF filename.obj /report option
                           By default all output is sent to the screen.
                      /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 defini-
                           tions of a segment.
                                  - 22 -
                    Report options
                    Report options govern what sort of report is generated,
                    and the amount of detail that OBJXREF provides.
                    Option Report generated
                      /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.
       This is the    /RR  Report by reference: Public name defini-
          default.         tions and references ordered by name.
                      /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
                    Public names defined in .C files appear in reports with
                    a leading underscore in the reports unless the -U-
                    option was specified when the file was compiled (main
                    appears as _main).
                    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 option. For example,
                       OBJXREF filelist /RM /NC0
                    tells OBJXREF to generate a report listing information
                    only for the module named C0.
                                  - 23 -
    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 a
                    text editor. Since you may already have prepared a list
                    of the files that make up your program for other
                    Borland C++ 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
                    (so, for example, you would type /Lresp, not /L resp).
                    You can specify more than one response file on the com-
                    mand line; additional .OBJ and .LIB file names can
                    precede or follow them.
------------------  You can create a free-form response file with a text
Free-form response  editor. Just list the names of all .OBJ and .LIB files
             files  needed to make your .EXE file.
     Any file name  To use free-form files with OBJXREF, type in each
     listed in the  response file name on the command line, preceded by an
     response file  @, and separate it from other command-line entries with
 without an exten-  a space or tab:
sion is assumed to
  be an .OBJ file.     @filename  @filename ...
------------------  You can also use project files of the type generated by
     Project files  Borland C++'s integrated environment as response files.
------------------  In the command line, precede the project file name with
                    /P, like this:
                    If the file name does not include an explicit exten-
                    sion, a .PRJ extension is assumed.
                    File names in the project file with a .C extension or
                    no extension are interpreted as specifying the
                    corresponding .OBJ file. You need not remove file
                    dependencies specified inside parentheses; they are
                    ignored by OBJXREF.
                                  - 24 -
                    By itself, the list of files in a .PRJ file does not
                    specify a complete program--you must also specify a
                    startup file (C0x.OBJ) and one or more Borland C++
                    library files (MATHX.LIB, EMU.LIB, and CX.LIB, for
                    example). In addition, you may need to use the /D
                    option to specify the directory where OBJXREF should
                    look for your .OBJ files.
------------------  Files in TLINK response-file format can also be used by
   Linker response  OBJXREF. A linker response file called from the command
             files  line is preceded by /L, like so:
                    To see how to use one of these files, refer to Example
                    2 in the section "Examples of how to use OBJXREF."
    Sample OBJXREF  =======================================================
                    Suppose you have two source files in your Borland C++
                    directory, and want to generate OBJXREF reports on the
                    object files compiled from them. The source files are
                    called TEST1.C and TEST2.C, and they look like this:
                     /* test1.c */
                     int i1;                       /* defines i1 */
                     extern int i2;                /* refers to i2 */
                     static int i3;                /* not a public name */
                     extern void look(void);       /* refers to look */
                     void main(void)               /* defines main */
                        int i4;                    /* not a public name */
                        look();                    /* refers to look */
                     /* test2.c */
                     extern int i1;                /* refers to i1 */
                     int i2;                       /* defines i2 */
                     void look(void)               /* defines look */
                        exit(i1);                  /* refers to exit... */
                     }                             /* and to i1 */
                    The object modules compiled from these source files 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.
                                  - 25 -
              Note  The following examples show only useful parts of the
------------------  A report by public names lists each of the public names
  Report by public  defined in the object modules being reported on,
       names (/RP)  followed by the name of the module in which it is
------------------  defined.
                    If you enter this on the command line:
                       OBJXREF  /RP  test1  test2
                    OBJXREF generates a report that looks like this:
                     SYMBOL           DEFINED IN
                     _i1              TEST1
                     _i2              TEST2
                     _look            TEST2
                     _main            TEST1
------------------  A report by module lists each object module being
  Report by module  reported on, followed by a list of the public names
             (/RM)  defined in it.
                    If you enter this on the command line:
                       OBJXREF  /RM  test1  test2
                    OBJXREF generates a report that looks like this:
                     MODULE: TEST1 defines the following symbols:
                             public: _i1
                             public: _main
                     MODULE: TEST2 defines the following symbols:
                             public: _i2
                             public: _look
------------------  A report by reference lists each public name with the
         Report by  defining module in parentheses on the same line.
   reference (/RR)  Modules that refer to this public name are listed on
------------------  following lines indented from the left margin.
       This is the  If you enter this on the command line:
     default if no
  report option is     OBJXREF  /RR  C0  test1  test2  CS.LIB
                    OBJXREF generates a report that looks like this:
                     _exit (EXIT)
                                  - 26 -
                     _i1 (TEST1)
                     _i2 (TEST2)
                     _look (TEST2)
                     _main (TEST1)
------------------  A report by external references lists each module
Report by external  followed by a list of external references it contains.
  references (/RX)
------------------  If you enter this on the command line:
                       OBJXREF  /RX  C0  test1  test2  CS.LIB
                    OBJXREF generates a report that looks like this:
                     MODULE: C0 references the following symbols:
                     MODULE: TEST1 references the following symbols:
                     MODULE: TEST2 references the following symbols:
------------------  A report by sizes lists segment names followed by a
  Report of module  list of modules that define the segment. Sizes in bytes
       sizes (/RS)  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 this on the command line:
                       OBJXREF  /RS  test1  test2
                    OBJXREF generates a report that looks like this:
  These files were   TEST1_TEXT
compiled using the           6 (00006h)   TEST1
      large memory           6 (00006h)   total
            model.   TEST2_TEXT
                            10 (0000Ah)   TEST2
                            10 (0000Ah)   total
                             4 (00004h)   TEST1, uninitialized
                             2 (00002h)   TEST2, uninitialized
                             6 (00006h)   total
                                  - 27 -
------------------  A report by class type lists segment size definitions
   Report by class  by segment class. The CODE class contains instructions,
        type (/RC)  DATA class contains initialized data and BSS class
------------------  contains uninitialized data. Segments which do not have
                    a class type will be listed under the notation No class
                    If you enter this on the command line:
                       OBJXREF  /RC  C0  test1  test2  CS.LIB
                    OBJXREF generates a report that looks like this:
                            4  (00004h)   TEST1
                            2  (00002h)   TEST2
                          132  (00084h)   total
                            6  (00006h)   TEST1
                           10  (0000Ah)   TEST2
                           16  (00010h)   total
                          143  (0008Fh)   C0
                          143  (0008Fh)   total
------------------  A report of unreferenced symbol names lists modules
         Report of  that define public names not referenced in other
      unreferenced  modules. Such a symbol is either:
symbol names (/RU)
------------------  o referenced only from within the defining module and
                      does not 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).
                    o never used (therefore, it can be deleted to save code
                      or data space).
                    If you enter this on the command line:
                       OBJXREF  /RU  test1  test2
                    OBJXREF generates a report that looks like this:
                       MODULE: TEST2 defines the unreferenced symbol _i2.
                                  - 28 -
------------------  If you enter /RV on the command line, OBJXREF generates
 Verbose reporting  one report of each type.
Examples of how to  =======================================================
       use OBJXREF
                    These examples assume that the application files are in
                    the current directory of the default drive and that the
                    Borland C++ startup files (C0x.OBJ) and the library
                    files are in the \BORLANDC\LIB directory.
------------------  C>OBJXREF \BORLANDC\lib\c0l test1 test2
         Example 1  \BORLANDC\lib\cl.lib
                    In this example, the TEST1.OBJ and TEST2.OBJ files and
                    the Borland C++ startup file \BORLANDC\LIB\C0L.OBJ and
                    the library file \BORLANDC\LIB\CL.LIB are 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.
------------------  C>OBJXREF /RV /Ltest1.arf
         Example 2
------------------  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 a report of every type will be
                    generated. TEST1.ARF contains
                     test1 test2
------------------  C>OBJXREF /RC B:c0s /Ptest1 @libs
         Example 3
------------------  The Borland C++ project file TEST1.PRJ specifies
                    TEST1.OBJ and TEST2.OBJ. The response file @libs
                    specifies libraries on a disk in the B drive. TEST1.PRJ
                    The file LIBS contains
                       b:maths.lib b:emu.lib b:cs.lib
                                  - 29 -
                    The startup and library files specified depend on the
                    memory model and floating point options used in compil-
                    ation. The /RC causes a report of class type to be
------------------  C>OBJXREF /F /RV \BORLANDC\lib\cs.lib
         Example 4
------------------  This example reports on all the modules in the Borland
                    C++ library file CS.LIB; OBJXREF can produce useful
                    reports even when the files specified do not make a
                    complete program. The /F causes all modules in CS.LIB
                    file to be included in the report.
     OBJXREF error  =======================================================
      messages and
          warnings  OBJXREF generates two sorts of diagnostic messages:
                    error messages and warnings.
------------------  Out of memory
    Error messages  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.
------------------  WARNING: Unable to open input file 
          Warnings  The input file filename could not be located or opened.
------------------  OBJXREF proceeds to the next file.
                    WARNING: Unknown option - 

Check out more tips and tricks in this development video: