


!=====================================================================
!        This file is NOT to be edited.  Edit the input file (see
!        RUNOFF Source File:) to make the changes that you want, and
!        then use the RNOTOHLP tool on it.
!
! RUNOFF Source File:
!        $RNOTOHLP.TMP
!
! Command Used:
!        $ RNOTOHLP  $RNOTOHLP.TMP  "DCLCHANGES.HLP"  "1" "DCLCHANGES"
!
! History:
!        This file was created by AMBY on the CSD630 system
!        at 13-FEB-1991 10:35:33.68 with the RNOTOHLP tool.
!=====================================================================
1 DCLCHANGES

This tool can be used to help you determine what the effect of running a DCL
command is. This will document what logical names were changed and what
global symbols have been defined.

         $ DCLCHANGES "dcl-command"  file-name  [diff-quals]
2 Parameters

     a.  dcl-command

         This can be any valid DCL command, and is best enclosed in double
         quotes.

     b.  file-name

         The filename of output files (file-name.*). If you omit this, then
         the default is DCLCHANGES, resulting in the output files
         DCLCHANGES.* being generated.

     c.  diff-quals

         This allows you to specify qualifiers to DIFFERENCE command, that
         is used to document the changes. If omitted, then by default
         /PARALLEL and /MATCH=1 are used.

2 Outputs

This tool generates three output files, whose filenames are given by the
second parameter (file-name).

      *  file-name.LIS - logs what happens when command is actually run.

      *  file-name.LOGICALS - lists changes in logical names.

      *  file-name.SYMBOLS - lists changes in global symbols.

2 Inputs

The following files are referenced by this. They must exist in order for it
to work.

      *  DCL.COM

         This is used to run a DCL command, and direct the output to a file
         (@DCL/OUT command). Is is used by this because there is no /OUTPUT
         qualifier to the SHOW SYMBOL command (like the SHOW LOGICAL). This
         MUST be in the same directory that this procedure is found in.

2 Examples

Suppose that you have designed a command procedure that will set up a set
of tools (SETUP.COM). The following will help you to document what it
define, and write the results into the default output files.

         $ DCLCHANGES "@SETUP"

The following can be used to document what effect the command
"@SYS$LOGIN:LOGIN" has, and have the output written to the files
MYLOGIN.LIS, MYLOGIN.LOGICALS, MYLOGIN.SYMBOLS.

         $ DCLCHANGES "@SYS$LOGIN:LOGIN"  MYLOGIN

The following does the same as the previous command, but specifies
different qualifiers for the DIFFERENCES command.

         $ DCLCHANGES "@SYS$LOGIN:LOGIN"  MYLOGIN  /SEPARATED/MATCH=1
2 Processing

This is accomplished by doing Initialization, then Main processing. There
are Handlers defined for interrupt and error handling, and the Exit code is
run prior to exiting from this application.
3 Initialization

     a.  Save parameters in local symbols that are easier to reference.

     b.  Block the use of dangerous "external" personal commands. These
         are so that any personal commands defined outside of this
         procedure are effectively hidden and will not interfere with the
         application.

     c.  Save the current message and privilege settings, etc. so that
         they may be restored at the end.

     d.  Define some simple status codes for the application.

     e.  Establish the interrupt and error handlers. Make sure the status
         indicates success if we exit normally. Up to this point, errors
         and interrupts will cancel the procedure harmlessly. From this
         point on, they will cause the appropriate handler to be invoked.

     f.  Establish the message and privilege environment. The settings of
         DCL environment items are altered as required by the
         application.

     g.  Set up some useful symbols for the application. Various symbolic
         constants, personal commands, and other useful local symbols are
         define.

     h.  Supply defaults for some parameters

3 Main

This is where the actual application begins, and the real work is done.

     a.  Before going any further, make sure that the DCL.COM file exists
         in the same directory that this command procedure is found. It
         is used so that the output of the SHOW SYMBOL command can be
         directed to an output file.

     b.  If there was a command input, then we want to run it and
         generate output difference listings for logicals and symbols. If
         not, then all we want to do is generate initial versions of the
         log files.

     c.  Check to see if a command was specified as the first parameter.
         If not, output an error message end exit.

     d.  If there was a command entered, then proceed to document its
         effect.

         1.  Generate listing of current logical names and global
             symbols.

         2.  Run the command that was entered as first parameter,
             restoring directory so we get back to where listing files
             are that were generated earlier.

         3.  Generate listings of logical names and global symbols into
             temp files, and add headings to them documenting the time,
             default directory, command, and so on.

         4.  Generate difference listings of the logicals and symbols
             from the ones generated already. This then serves to
             document the effect from running the command.


3 Handlers

     a.  The interrupt handler sets the summary status to indicate that
         <CTRL/Y> was pressed and then joins the cleanup (Exit) code.

     b.  The error handler sets the summary status to the "offending"
         status then also joins the cleanup (Exit) code.

3 Exit

The exit routine first performs cleanup. Then it restores the original
DCL environment. Finally it exits with the summary status.

2 Author

         Donald E. Amby

         Harnischfeger Engineers, Inc.
         P.O. Box 1512             or    13400 Bishops Lane
         Milwaukee, WI 53201             Brookfield, WI 53005

         414-797-6713, 414-797-6533 (FAX)

         DECUServe,DCS:  AMBY
         CompuServe:     73547,3256
         Internet:       don@amby.mixcom.com     (home)
                         amby@eisner.decus.org   (DECUServe)
         UUCP:           uunet!mixcom!amby!don   (home)
                         {decwrl,nosc,crash}!simpact!eisner!amby
