> Please read the following information before using the DIRUTL.  J The DIRUTL was written by, and is maintained by Eric M. LaFranchi.  If youG have any suggestions for improvements or new features, or would like to < report a bug, please contact Eric M. LaFranchi via e-mail at8 eric%emlsoft@ingres.com or by phone at (707) 942 - 6655.  + Building and Installing the DIRUTL Programs + ------------------------------------------- E The DIRUTL has be tested and run successfully on VAX VMS versions 5.0 K through OpenVMS VAX Version 6.0 (FT3). In addition, the DIRUTL has been run K successfully on OpenVMS AXP V1.0. Note however that early versions of the C J compiler on OpenVMS AXP had a bug which prevented the utility from runningG successfully. To get around the problem on OpenVMS AXP systems, see the H the following paragraph for information about building this utility from source.   F The DCL command procedure build.com will build the DIRUTL from source.K Build.com also creates three cld files: pushd.cld, popd.cld, and peekd.cld. K After the utility is built, the CLD files assume the executables are in the G same directory the code was built in.  If the executables are move to a K different device and/or directory, the cld files must be updated to reflect  the change.   > This utility has online help.  You can place the .hlp files inK SYS$HELP:HELPLIB.HLB directly, or you can define the logical hlp$library to I point to the DIRUTL.HLP file. If you define the hlp$library logical name, K use the HELP/LIBRARY DCL command (e.g.  $ HELP/lIBRARY @DIRUTL) to get help J on the pushd, popd and peekd verbs.  When the DIRUTL is built, the logicalL hlp$library is defined and a DCL $ SET command is issue to set up the PUSHD,E POPD, and PEEKD verbs.  This is too allow the user to use the utility 0 without ever editing or moving any of the files.  J The command procedure build.com will build the program on both OpenVMS VAXJ and OpenVMS AXP systems.  To build a debug version, use the DCL command: $K @BUILD DEBUG.  To build a version using the AMC cross tools environment for - OpenVMS AXP, use the command: $ @BUILD GEMCC.   I **** SPECIAL NOTE: On OpenVMS AXP V1.0 the GEM compiler backend has a bug G which prevents this program from running correctly.  To get around this G problem, the following DCL command can be used to build this utility so L that it executes correctly on OpenVMS AXP systems: $ @BUILD BUG. If you are J using the AMC cross tools, the follow command should be used: @BUILD GEMCC BUG.  F This is a VMS utility and is written as such (i.e. this utility is not8 intended to be portable to any other operating systems).   Utility overview:  ----------------- 	 1.) PUSHD C The pushd program saves the current working device/directory on the D directory stack, and then changes the default to the newly specifiedI device/directory specification.  If no device/directory is specified, the I current working device/directory is exchanged with the top element on the J stack.  Note that If no directory is specified and the stack is empty, theM current working directory is exchanged with SYS$LOGIN.  Additionally, entries L can be preloaded into the stack using the /LOAD qualifier, and also an entryL in the stack may be selected for the new default using the /ENTRY qualifier.# See help on PUSHD for more details.    2.) POPDI The popd program replaces the current working directory with top entry on I the stack.  Additionally, entries may be selected form the stack with the L /ENTRY qualifier, or remove from the stack using the /REMOVE qualifier.  TheH /ALL qualifier removes all entries from the stack and leaves the current? device/directory unchanged.  See help on POPD for more details.   	 3.) PEEKD I The peekd program displays the directory entries in order from the top of H the stack.  Each entry is displayed with the corresponding entry number.  I The DIRUTL works in a manor consistent with the DCL $ SET DEFAULT command H and makes no assumptions about the device/directory specification -- theH device/directory specifications are interpreted literally.  For example,G some other utilities use DCL to implement string handling that allows a J directory specification without the brackets (e.g. "[" "]") to be entered.I If you want this functionality, you must implement it yourself, it is not  contained in these utilities.   ' Rational for implementing this utility: ' --------------------------------------- L The $ SET DEFAULT DCL command allows a user to explicitly set the device andL directory specification each time he/she wishes to change it.  Although thisF may be sufficient for some users, I find myself moving between two andL three, and sometimes more directories to accomplish my work.  Although the $J SET DEFAULT DCL command has a mechanism to change your default device and F directory specification, there is no way to save and restore directoryM previously used device/directory entries.  These limitations in $ SET DEFAULT I were the incentive to create the DIRUTL programs.  The DIRUTL is a set of M three related programs: pushd, popd and peekd.  With this utility, a user can I move between directories, saving and restoring them in a stack like manor  (i.e.  push, pop operations).   L This utility was conceived as a set of programs that would manage a stack ofI directory entries; but as I implemented this utility, I found that having L just a stack data structure was to restrictive.  As a result some additionalK operations were added.  This utility allows the top entries on the stack to J be toggled, any entry in the stack can be selected or removed, in addition to preloading stack entries.  D This utility does not use process global symbols or logical names toG maintain the directory stack.  The directory stack is maintained in the F almost undocumented per-process common area located at CTL$A_COMMON in process p1 space.    Programming Notes: ------------------* The DIRUTL is made up of three components:  L 1.) The modules pushd, popd, and peekd are programs that manager/control the+     directory stack and the user interface.   F 2.) The module default handles the changing (setting), validation, andI     constructing a current device/directory string.  Although this module G     is self contained and could be replace, there are assumptions about L     OpenVMS file specifications in the top level programs.  For example, the)     VMS command definition (CLD) utility.      G 3.) The module stackutl handles all the details of the stack.  Although J     this utility uses only ASCII text strings, the stack routines supportsK     operation on binary strings from 1 to 255 bytes in length.  This module J     is totally self contained and can be replace without any modifications)     to the sources in the other programs. 