   DST SCANNER   L Chris Chiesa (lvt-cfc@servtech.com) (formerly Chris_F_Chiesa@cup.portal.com)  D     The collection of files accompanying this text, make up the "DSTH Scanner" utility: when built, they produce three executable images whoseG function is to scan an executable image and display, if the information I is available, the names of the source files which were compiled/assembled G and linked to form the image being scanned.  The baseline utility scans J a VAX or Alpha AXP VMS image and displays source file specifications only;L a modified, "details" version scans a VAX image (no corresponding Alpha AXP K "details" version currently exists) and displays source file specifications N PLUS some RMS information (record/file organization, EOF position) associated  with the source files.  G     This utility does its job by reading the "target" executable image  E (.EXE) file, following the image's internal structure (Image Header,  K Debugger Symbol Table (DST), etc.), and extracting the desired information  E from one particular small subset of the information contained in the  K image's Debugger Symbol Table, or "DST," records.  Note that an image will  J contain DST records _only_ for those contributing source files which were I compiled (or assembled) with the /DEBUG qualifier, and only if the image  . itself was linked with the /DEBUG qualifier.    K     Note that other software utilities exist which may interfere, or which  I you might worry MIGHT interfere, with the operation of the DST Scanner.   J The STABACCOP program used in creation of Standalone Backup sets on those J systems which still support them, can be used to copy an executable image H WITHOUT its Debug Symbol Table records; therefore, the DST Scanner will H produce NO output upon scanning an image that was copied with STABACCOP.I On the other hand, numerous public-domain utilities exist which clear the K IHD$V_LNKDEBUG bit, and/or modify the transfer-vector array, in an image's  L header, in order to "disable" invocation of the VMS Debugger when executing K an image which was compiled and linked with /DEBUG.  Use of such utilities  I will NOT prevent the DST Scanner from finding, and emitting, the desired  B information if it was present in the "original" form of the image.  I    The format of DST records is "undocumented" by Digital, in addition to H being intricate and subject to change.  It is, however, explained fairlyI thoroughly in the comments in the relevant section (DSTRECRDS.REQ) of the J VMS Source Listing, allowing the intrepid programmer to write DST ScannersK and such.  Just don't expect Digital to help you fix it if it breaks at the  next release of VMS!    L     This particular DST Scanner is actually quite minimal, compared to what J it could be "in theory."  DST records embed a huge amount of information: O routine names, other symbol names, sufficient information (file specification,  I RMS attributes, creation date, exact EOF position, and ODS-2 File ID) to  L uniquely identify each source file, and the complete source-line-to-instruc-I tion-address table necessary for the VMS Debugger to support source-level J Debugging -- just to name a few.  There are at least a dozen (maybe more) M types of DST record, and several subrecord types within most of those!  From  L this wealth of information, this particular DST Scanner extracts *ONLY* the G "source-file-specification strings" and, in the "details" version, RMS  N file-and-record type and EOF-position values.  It should be pretty clear from M the source code for the "details" version, how to extend it to emit what YOU  K want it to emit -- at least from the "source-file correlation" type of DST  0 record this code is designed to find-and-process     I    There are a couple of other "limitations" -- if you want to call them   that -- to this utility.    L    First, the DST Scanner outputs to SYS$OUTPUT -only-.  It would be fairly N simple to add an /OUTPUT qualifier, but I've never gotten around to doing it; H sorry again!  Fortunately, you can easily get around this limitation by N defining logical name SYS$OUTPUT to a file _before_ invoking the DST Scanner. ' This comes in very handy as you'll see.   E    Second, my experience shows that an image contains a "source-file  C correllation" DST record for EVERY instance of a source file which  I contributed to a /DEBUG compilation at some point in the building of the  K image.  For example, if you compiled several C source files, each of which  K included "hoohah.h," or included something else which included "hoohah.h,"  K and then linked the resulting objects into a single executable image, then  L the DST Scanner would find, and display, "HOOHAH.H" several times, not just M once.  HOOHAH.H would appear at least once for each object whose compilation  F involved "hoohah.h" at ANY point.  This can be a little annoying when K trying to cross-reference the "raw" DST Scanner output stream to a minimal  J list of source files.  On the plus side, the multiple-occurrence behavior H makes it easy to notice, for instance, that two different C modules usedK two DIFFERENT versions of "hoohah.h" -- perhaps as a result of having been  L compiled at different times, across modifications of "hoohah.h" -- alerting K you to a potential run-time problem without having to actually execute the   image!    K    Third, the DST Scanner emits source file specifications in the order it  L encounters source-file-correlation DST records in the image, which seems to K be a combination of the order in which the compiler encountered the source  M files, and the order in which the linker encountered the objects.  It is NOT  K alphabetical, and multiple appearances of a particular source file do NOT,  L as a rule, occur "in a row" but, rather, "scattered" throughout the image.  M This can make it tricky to find a particular source file you're looking for,  F but can be useful in determining the order in which the compilers and J linker "put the image together," if you have reason to be concerned about  it.   L    Fourth -- and there's nothing I can do about this -- the DST Scanner can L *only* find source file specifications if they're actually present, i.e. if L DST records were generated at compilation/assembly time, and were preserved L at link time.  It is not necessary that all objects linked into an image be O compiled with the same /DEBUG (or /NODEBUG) state.  If any object contributing  L to the image was compiled without /DEBUG, no DST records were generated for D that object, and thus the DST Scanner will NOT find any source-file L information for that object.  And of course if the image was LINKED without L /DEBUG, you won't see ANY source file specifications AT ALL because all DST ) records have been omitted from the image!   L    The second and third limitations can both be overcome by first directing J SYS$OUTPUT to a file, then invoking the DST Scanner, and then sorting the F output file with SORT /NODUPLICATES.  That will give you a nice, tidy,J listing, in alphabetical order with each unique source file specification  appearing exactly ONCE.   K    But enough about that.  How do you build it, and then how do you USE it?   I    To build the DST Scanner, first make sure all the files supplied with  J this package reside in the same directory.  Set your default directory to L that directory and invoke the command procedure file BUILD_DST_SCANNERS.COM:      $ @BUILD_DST_SCANNERS  7 This procedure will perform three essential operations:   I    1) Define the logical name DSTDIR to point to the directory where the  )       DST Scanner package's files reside;   J    2) Build a Macro library containing assembly-time macros necessary for        step 3, below;  L    3) Assemble the Macro-32 source code for the DST Scanner, and link it to -       form the DST Scanner executable images;   @    4) Add a new DCL command, "DST", to the then-current process.   Note several things.  G    First, the logical name DSTDIR must point, at assembly time, to the  L directory where the Macro LIBRARY (created in step 2) resides.  At run-time G it must point to the directory where the DST Scanner executable images  J reside.  These NEED NOT be the SAME directory, but things will probably go more smoothly if they ARE.  J    Second, you'll note that I keep saying "DST Scanner executable IMAGES,"K plural.  The DST Scanner package "as shipped" consists of three executable   images:   G    VAX_DST_SCANNER.EXE - reads a VAX image, emits source filespecs ONLY   J    VAX_DST_SCANNER_DETAILS - reads a VAX image, emits source filespecs ANDJ        "other details" -- RMS attributes and EOF position, as shipped, butD        is easily modified to emit, say, source-file creation date...  J    AXP_DST_SCANNER - reads an Alpha AXP image, emits source filespecs ONLY  H Which program gets run, depends on how you invoke the DST Scanner, whichI depends on how you issue the DST command.  We'll get to that momentarily. G Note that ALL THREE of these programs can be built, and will run and do G what they're supposed to, under VAX/VMS (built/tested under V5.4-3) and J OpenVMS AXP (built/tested under (cringe) V1.5-1H1).  I -expect- them to beK buildable, executable, and usable under "all" versions of VMS, but like any " sane person I DON'T GUARANTEE it.   K    Third, logical name DSTDIR gets defined, and the DST command verb added  ? to your DCL environment, automatically, _only_ when you invoke  I BUILD_DST_SCANNERS.COM.  Thereafter it's up to YOU to define the logical  E and add the DST command verb.  I'll discuss this further in a moment.   J    So now that you've built the DST Scanner and have the command verb all , ready to use, HOW do you USE it?  Like this:  $    $ DST [qualifiers] image_filespec      Qualifiers:  
       /VAX  7           Scan a VAX/VMS (OpenVMS VAX) executable image   
       /AXP  6           Scan an OpenVMS Alpha (AXP) executable image         /DETAILS  I           Display source-file RMS attributes and EOF position in addition J           to file specifications.   The /DETAILS qualifier is allowed only$           when scanning a VAX image.  F    You can set up either /VAX or /AXP to be the default, as discussed  below.  K    The build-procedure BUILD_DST_SCANNERS.COM will define the logical name  L DSTDIR, and will add the DST command to your DCL environment.  However, the K next time you log in you will have to define the logical name, and add the   command verb, yourself.     I    Defining the logical name is done by using either the DEFINE or ASSIGN  command, like so:   E        $ DEFINE DSTDIR directory_where_DST_Scanner_executables_reside  or  E        $ ASSIGN directory_where_DST_Scanner_executables_reside DSTDIR   G    Adding the DCL command verb is done by using either of the two .CLD  L files provided by this package, with the SET COMMAND command.  Assuming the J .CLD files reside in the directory pointed to by the DSTDIR logical name,  the command is either:  '        $ SET COMMAND DSTDIR:VAX_DST.CLD  or  '        $ SET COMMAND DSTDIR:AXP_DST.CLD   H The only difference is that VAX_DST.CLD defines the DST command so that K when no qualifiers are specified the default is /VAX, and that AXP_DST.CLD  0 defines the command so that the default is /AXP.  K    Consult your system documentation for information on how to provide the  J DST command on a system-wide basis, or to yourself automatically at login  or in all processes.    F    This should be enough information for you to build and use the DST L Scanner.  If it is not, you may contact me (at the time of this writing) on M the Internet at lvt-cfc@servtech.com .  If that address ever ceases to work,  J hopefully you'll still be able to search the Usenet newsgroups for "Chris  Chiesa" and find me.  :-)   '     Chris Chiesa (lvt-cfc@servtech.com)       September 19, 1996                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     