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