                         DGrpScan Version 1.06
                         =====================

                            By Dave Pearson
                            ===============

==========
What it is
==========

        DGrpScan is a simple little command line utility that will scan your
        Clipper 5.x oriented OBJ and LIB files and produce a report of their
        usage of Clipper's DGROUP.

        DGrpScan will work with and has been tested on C, ASM and Clipper OBJ
        and LIB files.

=============
How to use it
=============

        The syntax is as follows:

                DGrpScan <FileSpec> | @<ScriptFile>

        where <FileSpec> is the name of a single OBJ or LIB file or a wildcard
        file spec for a number of OBJ or LIB files. Example usage:

                DGrpScan main.obj       // Scan a single OBJ file.
                DGrpScan *.obj          // Scan all OBJ files.
                DGrpScan clipper.lib    // Scan a library file.
                DGrpScan *.lib          // Scan all library files.

        etc.

        As an alternative you can use a "script" file. This file should
        contain the names of files that you want to scan, each file
        on it's own line. The name of the file should start on the
        first column, any lines that start with either a space or
        a ';' are considered to be comments. Blank lines are allowed.

        Example usage of a script file is:

                DGrpScan @CCode.Lst

================
Format of output
================

        DGrpScan writes a simple report to the screen, this can be redirected
        to a file using standard DOS redirection. The format of the report
        is:

        File-------- Module------------------------ Segment-------- Bytes-----
        <FileName>  <ModuleName>                    <SegmentName>   <Usage>

        where:    <FileName> is the name of the OBJ or LIB file.
                <ModuleName> is the name of the module in the OBJ or LIB file.
               <SegmentName> is the name of the segment that us using DGROUP.
                     <Usage> is the number of bytes of DGROUP in use.

        An example report is:

        File-------- Module------------------------ Segment-------- Bytes-----
        FLOPNAME.OBJ flopname.c                     _DATA                    4
        FLOPNAME.OBJ *** Total ***                                           4

        If more than one file is scanned then a grand total will also be
        displayed.

================
What to look for
================

        The first and most obvious thing to look for is the segment name
        STATICS$ for Clipper compiled code. If the byte figure is high
        you may want to consider reducing the number of statics in a
        file. The number of bytes is calculated based on the fact that
        a single Clipper static variable will have a 14 byte impact on
        DGROUP.

        If you have, for example, ten file wide static variables in a
        PRG file you may consider storing the ten items in an array
        held in a single static. With such an example the DGROUP impact
        would be reduced from 140 bytes to just 14 bytes.

        With C code you will probably know yourself what the "problem" areas
        are. Obvious things to watch out for are hard coded strings in a
        C function, for example:

                _retc( "" );

        will have a one byte impact on DGROUP (the segment will probably show
        up as _DATA), you could get rid of this with a simple:

                char *p = { 0 };

                _retc( p );

        Other things to look out for are static variables (the segment
        will probably be _BSS), but I would assume that you have placed
        them there for a reason.

        To a large extent when it comes to C and ASM code you are kind of
        on your own because the segment names etc. may differ from
        compiler to compiler or you mave have given then your own names.

===========
ErrorLevels
===========

        Just in case you ever wanted to have DGROUP detection in your
        Compile batch file/make file DGrpScan will return an ErrorLevel
        of 1 if any DGROUP impact is found in a scan and 0 if none is
        found.

        I doubt that this will be of any use but its there if you need it.

===========
The History
===========

   Release  Date      Reason
   ======== ========  ====================================================
   1.00.0   23/11/94  First version, release to DBSL for testing. Had no
                      library file support and had trouble with unknown
                      record IDs.
   1.00.1   24/11/94  Added support for library files by ignoring unknown
                      record IDs.
                      Changed the memory model to large. Without this the
                      utility would die when reading large library files.
                      Added support for Clipper Static variables.
                      Re-wrote the output so that it is now a proper
                      report of sorts.
   1.00.2   25/11/94  Added code to ignore _SYMP segment entries. Because
                      of this DGrpScan will now show you DGROUP usage that
                      you can affect in your own code (you can do nothing
                      about the usage of the _SYMP segment).
                      Changed the way we calculate the impact of C and
                      ASM code. We can now detect static variables in
                      C and ASM files whereas before they were not
                      included in the calculation.
   1.01.0   02/12/94  Added a verbose mode switch to the command line that
                      causes all segments to be displayed in the report.
   1.02.0   05/12/94  Fixed a stupid bug that caused DGrpScan to ignore
                      DGROUP usage from time to time. This was a side
                      effect of the Verbose switch of all things! Thanks
                      for finding that one Ian.
   1.03.0   06/12/94  Fixed a stupid memory allocation bug that caused
                      strange results on Ian Day's machine. <g>
                      Also added errorlevel support. If DGROUP usage is
                      found in a scan then an errorlevel of 1 is returned,
                      otherwise an errorlevel of 0 is returned,
                      Also added support for "Script" files.
   1.04.0   08/12/94  Fixed a strange bug found by Ian Day.
                      Also removed the verbose switch because of incorrect
                      user expectations. There was little need for it in
                      the first place.
   1.05.0   13/12/94  Far better library scanning. This should have correctly
                      fixed a couple of the previous bugs found by Ian and
                      should also make the scanning of some library files
                      a bit faster.
   1.06.0   15/12/94  Long module and segment names will no-longer screw up
                      the format of the report.

==========
Many Thanx
==========

        Many thanx must go to Ian Day who showed me how to calculate the number
        of Clipper static variables from information found in a Clipper OBJ
        file and also managed to find that one extra library that would break
        the scanner each time I was happy that it was working fine. Thanx also
        to Darren Lancaster who let me pester Ian when he had better things to
        be doing with his time and Brian Dukes and Stu Beesley for
        testing this utility.

        Thanx must also go to Kip Davidson and Dave Cortesi, two guys I've
        never met or spoken to but who wrote a utility called READOBJ, the
        code for this utility helped me understand the format of OBJ files.

        __DavePearson()

==========================================
Are You Serious About Clipper Development?
==========================================

        If you are then you probably will want to get hold of MrDebug, *THE*
        CA-Clipper debugger. Can I suggest that you read the enclosed text
        file MRDEBUG.INF which lists some of the many features in MrDebug
        v1.10. If you would like more information about MrDebug then why
        not contact Dark Black Software for full details, you can reach
        them at:

                               tel: +44 (0) 480 403104
                               fax: +44 (0) 480 471465
                               BBS: +44 (0) 480 471465
                          InterNet: Darren@darkblak.demon.co.uk
                        Compuserve: 72537,31

        Don't forget to tell them that __Dave() sent you!


        In Germany you can get MrDebug at:
        

          Ŀ
           Adress:                    Tel.:+49-40-7661290 
           SOFTSOL GmbH               Fax :+49-40-7665664 
           Neue Str.35a               BBS :+49-40-7665527 
           21073 Hamburg              CIS : 100112,3401   
           Germany                    Fido: 2:240/5300    
          
