Shareware Overload/ShartewareOverload.cdr/progm/examine.zip/EXAMINE.DOC

Text File | 1989-04-22 | 20KB | 542 lines

  EXAMINE          Assembly Level Examination Utility          Version 2.0

                Copyright (c) 1989   Richard W. Prescott
                          All Rights Reserved


 All brand and product names mentioned herein are trademarks or registered
                trademarks of their respective holders.

  ┌─────────────────────────────────────────────────────────────────────┐
  │  This file contains documentation for the program file EXAMINE.EXE  │
  └─────────────────────────────────────────────────────────────────────┘


The following topics are described below:

1. Overview
2. Command line options
3. Producing a Map file
4. Behind EXAMINE.EXE
5. System Requirements
6. DISCLAIMER
7. Purchase Information
8. TP&Asm/TP&Asm-M




1. Overview

EXAMINE.EXE is a utility program which can be used to display the
assembly level implementation for each line of any source files
compiled with Turbo Pascal version 4.0 or 5.0.  You must compile to
disk, and you must instruct the compiler to create a map file with
line number detail, as explained below.

The default presentation is to the screen, however output may be
redirected to the printer (>PRN) or to a file (>filename.ext).

The following presents a section of EXAMINE output:


----
  m := 0;                                          ─── Source Line
                                                   ┐
4FB0:0075 31C0          XOR     AX,AX              ├── Corresponding
4FB0:0077 8946BA        MOV     [BP-46],AX         ┘    disassembly
----
  FOR n := 0 TO SearchLimit DO BEGIN               ─── Source Line
                                                   ┐
4FB0:007A 8B4608        MOV     AX,[BP+08]         │
4FB0:007D 8946B8        MOV     [BP-48],AX         │
4FB0:0080 31C0          XOR     AX,AX              │   Corresponding
4FB0:0082 3B46B8        CMP     AX,[BP-48]         ├──   DEBUG.COM
4FB0:0085 7F5B          JG      00E2               │    disassembly
4FB0:0087 8946BC        MOV     [BP-44],AX         │
4FB0:008A EB03          JMP     008F               │
4FB0:008C FF46BC        INC     WORD PTR [BP-44]   ┘
----
    IF FindArray[n] = FindStr[1] THEN BEGIN        ─── Source Line
                                                   ┐
4FB0:008F 8B46BC        MOV     AX,[BP-44]         │
4FB0:0092 C47E0A        LES     DI,[BP+0A]         │   Corresponding
4FB0:0095 03F8          ADD     DI,AX              ├──   DEBUG.COM
4FB0:0097 26            ES:                        │    disassembly
4FB0:0098 8A05          MOV     AL,[DI]            │
4FB0:009A 3A46BF        CMP     AL,[BP-41]         │
4FB0:009D 753B          JNZ     00DA               ┘
----



EXAMINE.EXE is useful in a number of situations:

To simplify the designing of external PROCs.  (For example, by
writing the PROC shell first in Pascal and using EXAMINE to
determine the parameter offsets, parameter push sequence for
procedure calls, etc).

To verify the assembly code produced by the Integrated Compile-time
Assembler TP&Asm.  (This is the reason why Examine was written).

To simplify converting Pascal code to assembly language for use
within TP&Asm, or with Inline or External.

To determine which of a set of alternative Pascal statements
produces the more efficient code.  For example, consider the three
alternative statements below:

       IF (Ch IN ['N','n']) THEN DummyProc;

       IF (Ch='N') OR (Ch='n') THEN DummyProc;

       CASE Ch OF 'N','n': DummyProc; END;

As determined using EXAMINE, the first statement uses 51 bytes of
code (including the 32 byte set constant), the second statement
uses 17 bytes, and the third, only 14 bytes.  In fact, a CASE
statement will always be smaller than an IN statement unless there
are more than 12 distinct values or range endpoints to be checked.



2. Command line options

Examine may be invoked with just a single file name, or with up to
three file names, a procedure name, and starting and ending line
numbers.  The general format for invoking examine is:

Examine SourceName ExeName MapName [ProcName StartLine EndLine]

Most of the above parameters may be omitted.  The use of brackets
'[..]' is required when specifying a Proc/Function or Line Number
limit.  Omitted parameters will assume default values as specified
below:

   Default Source path = current directory
   Default Source name = 'NONAME'
   Default Source ext  = 'PAS'

   Default Executable path = Source path
   Default Executable name = Source name
   Default Executable ext  = 'EXE'

   Default Map path = Executable path
   Default Map name = Executable name
   Default Map ext  = 'MAP'

   Default Start Line  = 1
   Default Ending Line = End of Source File

   If only one line number is specified, it is taken to be the starting
   line.


EXAMINE can be terminated at any time by pressing:
   <Ctrl>-C              - or -
   <Ctrl>-<Break>


Examples

To Examine all of MYPROG.PAS with MYPROG.PAS, MYPROG.EXE, and
MYPROG.MAP all in the current directory:

  Examine myprog

If all three files are in the directory C:\PASFILES:

  Examine c:\pasfiles\myprog

To limit Examine to the procedure FIRSTPROC:

  Examine myprog [firstproc]

To limit Examine to a specific range of lines

  Examine myprog [56 185]

To limit Examine to a range of lines within FIRSTPROC:

  Examine myprog [firstproc 56 185]


Examine was designed to handle Units.  Do not attempt to Examine a
TPU file, however.  Rather, a Unit may be specified as the source
file when examining an executable file which Uses that Unit:

If MyProg uses a unit MyUnit,

  Examine myunit myprog


Units which are overlaid ( eg, {$O OvrUnit} ) in the main program
cannot be processed by EXAMINE.  The executable code for such Units
is stored separately and loaded by the overlay manager during program
execution, and not loaded by DOS or DEBUG at program startup.  As a
result, the overlay unit code is simply not present during execution
of EXAMINE.

The simplest way to EXAMINE an overlayable Unit is to create a short
program file which uses the unit in a non-overlaid fashion:

 Program NotOvr;
 Uses OvrUnit;
 (** OvrUnit was compiled {O+} but will not be overlaid here **)

 VAR DummyPtr: POINTER;
 BEGIN
   DummyPtr := @Function1;  {- Force Link Function1  of OvrUnit -}
   DummyPtr := @Procedure1; {- Force Link Procedure1 of OvrUnit -}
   DummyPtr := @Procedure2; {- Force Link Procedure2 of OvrUnit -}
    : <etc>
 END.


 Then Compile:   TPC NotOvr /gd          <-- using TPC version 5.0
  And Examine:   EXAMINE OvrUnit NotOvr

Since "{$O OvrUnit}" is not specified, the OvrUnit Unit code will be
contained in the EXE file NOTOVR.EXE and will then be available to
EXAMINE.



Examine was not intended to handle include files, however the
only real limitation is the following:  If a source file contains
executable code both before and after an include directive, then
the line number table for that source file will be split into two
pieces, and only the first piece can be examined.  The included file
(eg INCLUDE.PAS) may be examined by specifying it as the source
file:

  Examine include myprog



Using Output Redirection:

The LAST parameter specified on the command line may be a "greater
than" symbol > , followed by "PRN" or the name of a file.  This
instructs the operating system to redirect standard output from the
screen to the printer (PRN) or the named file.  EXAMINE.EXE fully
supports output redirection.

To Examine MYPROG.PAS with output sent to the printer:

  Examine myprog >PRN

To Examine a range of lines within the Unit MyUnit, with output
saved in the file MYUNIT.XMN:

  Examine myunit myprog [56 185] >myunit.xmn


EXAMINE detects output redirection and provides an on-screen status
report of progress through the executable file.

The short batch file XM.BAT is provided to simplify the process of
redirecting output to a disk file.  Command line parameters for XM
are the same as for EXAMINE, with the exception that the SourceName
parameter for XM must omit the extension ".PAS".  The last example
above can be accomplished more simply using XM:

  XM myunit myprog [56 185]


Please refer to your MS-DOS/PC-DOS Manual for further information on
the use of Output Redirection.




3. Producing a Map file

To produce a map file using the Turbo Version 5.0 Integrated
Development Environment:

Be sure all units you may wish to examine are compiled in the
(default) {$D+} state.  Then set
           Options/Linker/Map file/Detailed
and compile the program file to disk.


To produce a map file using TPC Version 5.0:

Be sure all units you may wish to examine are compiled in the
(default) {$D+} state.  Then compile with the command line option
"/gd":

  tpc myprog /gd


To produce a map file using the Turbo Version 4.0 Integrated
Development Environment:

Be sure all units you may wish to examine are compiled in the
(default) {$D+} state.  Then set
   Options/Compiler/Turbo pascal map file generation ... On
and compile the program file to disk.  This will produce an EXE and
a TPM file.  Then use TPMAP to produce the final Map file from
myprog.tpm:

  tpmap myprog


To produce a map file using TPC Version 4.0:

Be sure all units you may wish to examine are compiled in the
(default) {$D+} state.  Compile with the command line option "/$T+",
and then use TPMAP to produce the final Map file:

  tpc myprog /$T+
  tpmap myprog




4. Behind EXAMINE.EXE

EXAMINE produces its disassembly by running DEBUG.COM from your DOS
disk as a "child process" and requesting disassembly of the required
sections via the DEBUG unassemble command "-u".  The advantage of
using DEBUG.COM rather than an internally written disassembler is
that the disassembly generated is then essentially guaranteed to be
reliable.  Users who feel comfortable with the reliability of
DEBUG.COM can be equally confident in the disassembly produced by
EXAMINE.

In addition, this technique illustrates how to create a useful
utility from an existing program without having to "reinvent the
wheel" (or rewrite the disassembler).

The following description provides an overview of how EXAMINE
operates:

  1. EXAMINE first verifies that it can find the Source, MAP,
     and Executable files and checks the dates of these files.
     If the Source date is later than the Executable file date,
     or if the MAP and Executable file dates differ by more than
     8 seconds, the user is asked to confirm before continuing.

  2. The MAP file is then read and processed.  The Line Number
     Table for the specified source file is stored in compressed
     form, 4 bytes per Line Number entry.

  3. The Source file is then read and stored immediately following
     the compressed Line Number Table.

     EXAMINE uses DOS Memory Allocation techniques rather than
     using the Turbo heap to allocate space for the MAP and Source
     files.  This permits memory not required by these files to be
     reclaimed for use by DEBUG.COM and the Executable file.  (In
     contrast, the full amount "heapmax" as specified in the {$M }
     compiler directive is reserved by the Turbo program and is not
     available for use by a program under "Exec").

  4. EXAMINE installs a new interrupt $21 handler which replaces
     the DOS Buffered Input Function 0Ah.  EXAMINE also monitors
     Function $30 (Get DOS Version) and the undocumented Function
     $50 (Set PSP) used by DEBUG.COM.  All other function requests
     are passed directly to the original interrupt $21 handler.

  5. EXAMINE Executes DEBUG.COM with the Executable file specified
     as a command line parameter.  DEBUG loads into memory, loads
     the Executable file, and then waits for input via the DOS
     Buffered Input Function 0Ah.

  6. Each time EXAMINE's Function 0Ah handler receives a request
     for input, it
      1) Writes a source line or series of source lines (as
         indicated by the MAP file Line Number Table) to the
         standard output device.
      2) Returns to DEBUG.COM with an unassemble command which
         instructs DEBUG to display (to the standard output device)
         the disassembly of the source line(s) just displayed.

  7. The process in (6.) repeats until EXAMINE instructs DEBUG to
     display the disassembly of the final source line requested.
     On the NEXT Function 0Ah input request, EXAMINE instructs
     DEBUG.COM to exit with a quit "-q" request, and the EXEC
     process terminates.

  8. On return from the EXEC process, EXAMINE restores the original
     interrupt $21 handler, and exits to DOS.




5. System Requirements

Examine Version 2.0 requires: DEBUG.COM running on an IBM PC or
Compatible, with Version 2.0 or above of MS-DOS or PC-DOS.
Minimum memory requirements are 128K plus memory required by the
executable program being examined.


Limitations and other notes:

Source and Map files are limited to 64K bytes.  Executable file size
is not limited, but must be small enough to load into memory after
Examine's minimum memory requirement of 128K.

If Examine cannot find one of the files you specify, it will report
the full path specification it was using for the file it failed to
find.

If Examine encounters an error with the Map file, it will tell you.
Make sure the file you specify is an UNMODIFIED Map file, with full
line number detail, produced by Turbo/TPC Version 5.0 or by TPMAP
Version 4.0.

Examine attempts to recognize string, set, and range constants and
display them in a readable DB format, for example:
                       DB 11,'Hello World'
If Examine fails to recognize a group of such constants, the fallback
presentation uses the standard DEBUG.COM disassembly.

Examine will attempt to exit gracefully when it detects the output
disk becoming full (under output redirection).  If it detects fewer
than 5 free "clusters" (approximately 4K free on a floppy), it will
exit with the message "Insufficient space on output disk".  Replace
or otherwise correct the disk problem, and re-execute Examine.




6. DISCLAIMER OF WARRANTY

This software and accompanying documentation are sold "as is" and
without warranties as to performance or merchantability.

This program is sold without any express or implied warranties
whatsoever.  Because of the diversity of conditions and hardware
under which this program may be used, no warranty of fitness for a
particular purpose is offered.  The user is advised to test the
program thoroughly before relying on it.  THE USER MUST ASSUME THE
ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE AUTHOR WILL
BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF THE
PURCHASE PRICE.




7. Purchase Information.

Note: Registered users of TP&Asm (described below) are automatically
registered users of EXAMINE.  The EXAMINE.EXE program file and source
code is included on registration and update disks for TP&Asm Version
2.0.

The EXAMINE package is distributed as shareware.  After you have
reviewed the package for a reasonable period of time (say, 30 days),
please register it or purchase TP&Asm if you plan to continue using
it.  As a benefit of registration, you can receive full source code
for the program file EXAMINE.EXE, as indicated below.

Even if you choose not to register, I encourage you to retain a copy
of EXAMINE and distribute it to others via BBS or on diskette.
Please include all files in the distribution package.

The following price list applies to registration of EXAMINE and
purchase of TP&Asm.  Users who choose to register EXAMINE with the
"registration + disk" option will receive the most recent version,
including source code.  Users who register EXAMINE with the
"registration only" option do not receive source code but may elect
to do so at a later date by sending the additional $3 P&H.


EXAMINE Registration   ... $15 + $3 P&H for registration + disk
                           $15  (total) for registration only

TP&Asm Version 2.0     ... $49 + $3 P&H


(Wisconsin residents, please add 5% sales tax).

All prices listed are for standard 5 1/4 inch floppy disks.  Add
$2 for distribution on 3 1/2 inch disks.


Please send a check or money order payable to:

                      Richard W. Prescott
                      724 Sauk Ridge Trail
                      Madison, WI  53705


When purchasing TP&Asm, please include the following information:

  1. Full Version number of the Turbo Pascal compiler you now use.

  2. Your registration number for that compiler.

  3. If you obtained TP&Asm-M from a bulletin board:
     3a. Name, area code and phone number of that bulletin board
     3b. Full Version number of the TP&Asm-M version you have
     3c. Directory Date of the README file




8. TP&Asm/TP&Asm-M

TP&Asm is a small assembler which runs Turbo 4.0/5.0 (Integrated
Environment or TPC) as a subprocess and permits you to place
assembly language statements directly into your Pascal source code
in blocks beginning with the keywords "Assemble" and/or "Internal".

TP&Asm provides the convenience and flexibility of having "live"
assembly language in your programs which can be modified and
immediately recompiled with no need to exit and reassemble.  You
have complete freedom to place assembly language anywhere in your
program, freely mix Pascal and assembly blocks, freely transfer
between Pascal and assembly blocks via Call/Jump/Loop/Goto to any
Pascal or assembly label, make direct Call, Jmp and Offset
references to Pascal Proc/Functions, and make simplified Pascal
style references to your Pascal and assembly variables and
parameters.  Units compiled with TP&Asm can be distributed and
Used independent of TP&Asm.

The resulting ASSEMBLY Development Environment is identical to your
PASCAL Development Environment.  It provides fast assembly with no
additional disk access, and reports assembly syntax errors on the
standard Turbo error line with cursor placed on the error.  It
accepts the standard syntax of both MASM and A86, but also provides
certain enhancements such as the placement of named data in the
Code Segment.

With Turbo Version 5.0, you can trace your assembly code line by
line in the IDE.  Using the record variable CPU defined in the unit
ASMWATCH (included), you can Watch, Evaluate, and Modify the CPU
registers and flags during the trace.

TP&Asm can be purchased as described in the preceding section.

A shareable Memory Mode version called TP&Asm-M is also available.
The distinction between TP&Asm and TP&Asm-M is that TP&Asm-M is
intended for developing and debugging assembly language in the IDE,
but not for final compilation.  You can compile to Memory (with the
standard Turbo style interactive syntax error detection) and Trace
your assembly code in the IDE with full capability to Watch,
Evaluate, and Modify the CPU registers and Flags - then convert to
INLINE or EXTERNAL after the code is fully developed.  TP&Asm-M's
INTERNAL statement and its support of the standard syntax of MASM,
A86, and INLINE.COM simplifies this conversion.

The TP&Asm-M distribution disk can be ordered from me for $5 plus
$3 P&H, with the $5 being credited toward subsequent registration
of TP&Asm or TP&Asm-M.  It can also be downloaded from the IBMPRO
or BPROGA forums on CompUServe.  Look for the archives TP-ASM and
TPA2-R ( May be ".ARC" or ".ZIP" ).  Registration for TP&Asm-M is
$19.





EXAMINE.EXE was compiled and assembled using TP&Asm Version 2.0
running Turbo Pascal Version 5.0.