<DIRUTL, Utilities, Directory PUSHD POPD and PEEKD Navigation>Please read the following information before using the DIRUTL.JThe DIRUTL was written by, and is maintained by Eric M. LaFranchi. If youGhave any suggestions for improvements or new features, or would like to<report a bug, please contact Eric M. LaFranchi via e-mail at8eric%emlsoft@ingres.com or by phone at (707) 942 - 6655.+Building and Installing the DIRUTL Programs+-------------------------------------------EThe DIRUTL has be tested and run successfully on VAX VMS versions 5.0Kthrough OpenVMS VAX Version 6.0 (FT3). In addition, the DIRUTL has been runKsuccessfully on OpenVMS AXP V1.0. Note however that early versions of the CJcompiler on OpenVMS AXP had a bug which prevented the utility from runningGsuccessfully. To get around the problem on OpenVMS AXP systems, see theHthe following paragraph for information about building this utility fromsource.FThe DCL command procedure build.com will build the DIRUTL from source.KBuild.com also creates three cld files: pushd.cld, popd.cld, and peekd.cld.KAfter the utility is built, the CLD files assume the executables are in theGsame directory the code was built in. If the executables are move to aKdifferent 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 inKSYS$HELP:HELPLIB.HLB directly, or you can define the logical hlp$library toIpoint to the DIRUTL.HLP file. If you define the hlp$library logical name,Kuse the HELP/LIBRARY DCL command (e.g. $ HELP/lIBRARY @DIRUTL) to get helpJon the pushd, popd and peekd verbs. When the DIRUTL is built, the logicalLhlp$library is defined and a DCL $ SET command is issue to set up the PUSHD,EPOPD, and PEEKD verbs. This is too allow the user to use the utility0without ever editing or moving any of the files.JThe command procedure build.com will build the program on both OpenVMS VAXJand 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 bugGwhich prevents this program from running correctly. To get around thisGproblem, the following DCL command can be used to build this utility soLthat it executes correctly on OpenVMS AXP systems: $ @BUILD BUG. If you are Jusing the AMC cross tools, the follow command should be used: @BUILD GEMCCBUG.FThis is a VMS utility and is written as such (i.e. this utility is not8intended to be portable to any other operating systems).Utility overview:----------------- 1.) PUSHDCThe pushd program saves the current working device/directory on theDdirectory stack, and then changes the default to the newly specifiedIdevice/directory specification. If no device/directory is specified, theIcurrent working device/directory is exchanged with the top element on theJstack. Note that If no directory is specified and the stack is empty, theMcurrent working directory is exchanged with SYS$LOGIN. Additionally, entriesLcan be preloaded into the stack using the /LOAD qualifier, and also an entryLin the stack may be selected for the new default using the /ENTRY qualifier.#See help on PUSHD for more details.2.) POPDIThe popd program replaces the current working directory with top entry onIthe stack. Additionally, entries may be selected form the stack with theL/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.) PEEKDIThe peekd program displays the directory entries in order from the top ofHthe stack. Each entry is displayed with the corresponding entry number.IThe DIRUTL works in a manor consistent with the DCL $ SET DEFAULT commandHand makes no assumptions about the device/directory specification -- theHdevice/directory specifications are interpreted literally. For example,Gsome other utilities use DCL to implement string handling that allows aJdirectory specification without the brackets (e.g. "[" "]") to be entered.IIf you want this functionality, you must implement it yourself, it is notcontained in these utilities.'Rational for implementing this utility:'---------------------------------------LThe $ SET DEFAULT DCL command allows a user to explicitly set the device andLdirectory specification each time he/she wishes to change it. Although thisFmay be sufficient for some users, I find myself moving between two andLthree, and sometimes more directories to accomplish my work. Although the $JSET DEFAULT DCL command has a mechanism to change your default device and Fdirectory specification, there is no way to save and restore directoryMpreviously used device/directory entries. These limitations in $ SET DEFAULTIwere the incentive to create the DIRUTL programs. The DIRUTL is a set ofMthree related programs: pushd, popd and peekd. With this utility, a user canImove between directories, saving and restoring them in a stack like manor(i.e. push, pop operations).LThis utility was conceived as a set of programs that would manage a stack ofIdirectory entries; but as I implemented this utility, I found that havingLjust a stack data structure was to restrictive. As a result some additionalKoperations were added. This utility allows the top entries on the stack toJbe toggled, any entry in the stack can be selected or removed, in additionto preloading stack entries.DThis utility does not use process global symbols or logical names toGmaintain the directory stack. The directory stack is maintained in theFalmost undocumented per-process common area located at CTL$A_COMMON inprocess p1 space.Programming Notes:------------------*The DIRUTL is made up of three components:L1.) The modules pushd, popd, and peekd are programs that manager/control the+ directory stack and the user interface.F2.) The module default handles the changing (setting), validation, andI constructing a current device/directory string. Although this moduleG is self contained and could be replace, there are assumptions aboutL OpenVMS file specifications in the top level programs. For example, the) VMS command definition (CLD) utility. G3.) The module stackutl handles all the details of the stack. AlthoughJ this utility uses only ASCII text strings, the stack routines supportsK operation on binary strings from 1 to 255 bytes in length. This moduleJ is totally self contained and can be replace without any modifications) to the sources in the other programs.