TO.COM v5.2 Author: Alan E. Feldman alanedfeldman\a\yahoo This is a SET DEFAULT program for use with Files-11 ODS-2 volumes. It offers much more functionality than the DCL command SET DEFAULT does and fixes some of its bugs. It has features that save the user much typing. I haven't tried it on ODS-5 volumes so I don't know how well it would work on such volumes. *** NEW IN v5.2 *** o Wildcards are now supported in directory-specs. o Write and read the logical name recall stack to and from disk. o Some minor bug fixes and improved program logic. o New versions of the auxiliary programs SAVE_DEFAULT.COM, DIR-MENU.COM, CLEAR-TO-LNMS.COM, CLEAR-NBACK-LNMS.COM, and OVER.COM. CONTENTS: CONVENTION INSTALLATION QUICK START FORMAT DESCRIPTION LOGICAL NAME RECALL STACK PARAMETERS P1 WILDCARDS LOGICAL NAMES KEYWORDS PRECEDENCE TWO-STEP NEW-DEFAULT FUNCTION P2 P3 USER OPTIONS STACK SIZE PUT THE CURRENT DEFAULT IN YOUR DCL PROMPT BRIEF VS. VERBOSE OUTPUT LOGICAL-NAME STYLE FEEDBACK *** CONVENTION *** The word 'default' is used in the sense of a device together with a directory. *** INSTALLATION *** Copy TO.COM to your system and add the following to your LOGIN.COM: $ TO :== @TO.COM $ TO -INIT ! to initialize TO.COM where can be either disk:[dir] or a logical name pointing to the location of TO.COM. Ensure that both commands above have been run before using TO.COM. *** QUICK START *** After installing TO.COM (see above), run $ TO ? to get the 23-line quick-help page. This page summarizes the most important aspects of TO.COM. Then use TO.COM as you would the SET DEFAULT command. *** FORMAT *** $ TO [new-default] [save-old-def] [DCL-verification] Use "" as a placeholder for any skipped parameters. *** DESCRIPTION *** Use TO.COM as you would use the SET DEFAULT command. As you visit different defaults (directories), TO.COM automatically saves up to the last 9 defaults in its logical name recall stack. Run TO.COM without any arguments to display the recall stack and enter interactive mode from which you can select one of the stack entries, enter a new default, or press Return to exit. TO.COM has features that o save you typing o perform iterative logical name processing o deal with bad defaults Features that save you typing: Directory brackets are optional -- let the program figure it out! The logical name recall stack saves recently visited defaults. Reference stack entries via numbers inside TO.COM and via logical names outside of TO.COM. The logical name recall stack is efficient: it avoids duplicate entries in most cases. The logical name recall stack can now (as of v5.2) be written to and read from disk, saving typing across terminal sessions. Another way that TO.COM saves you typing is with the two-step default function. This is most useful if you can specify the first default very quickly via a recall-stack slot number or logical name, and then the second default as a "correction" relative to the first. See the TWO-STEP NEW-DEFAULT FUNCTION section for details. There are shortcut keys for MFD, SYS$LOGIN, top-level directory, and n levels up. Wildcard support allows you to use wildcards as a quasi--name-completion feature. Iterative logical name translation: Iterative logical names are processed properly. Dealing with bad defaults: TO.COM should not normally put you in a bad default. It should also be able to recover from nearly any bad-default situation. (If for some reason you need to go to a non-existent default, use the SET DEFAULT command.) In more detail: When you run TO.COM it processes the old and new defaults, reports any problems that it finds, and performs appropriate actions. If all is well it will then set default to the new default; otherwise, an appropriate error message is displayed. If the new default was good, TO.COM checks if it matches an entry in the logical name recall stack. If it does, it reports the entry number of the first match found. TO.COM then updates the logical name recall stack, displays it, and displays your current default. Finally, if there was an error in updating the logical name recall stack and/or the new-default was not set, TO.COM will let you know just before exiting. If you run TO.COM without any arguments, it will display the logical name recall stack and prompt you for a new default. (There is one exception to this: If you run TO.COM without any arguments and haven't initialized TO.COM yet [by having run it with or without the -INIT parameter], you get the HELP screen instead [but only once].) TO.COM is designed for interactive use only. Running TO -INIT repeatedly does no harm. *** LOGICAL NAME RECALL STACK *** Whenever you set default to a new default with TO.COM, it saves the old default in slot 1 of the recall stack, assigns it to the logical name TO_1, bumps the other stack entries up one level, and assigns the new default to the logical name TO_0. By default, the logical name recall stack holds up to nine previous defaults plus the current default. Stack entries are assigned the following logical names: TO_0 - current default TO_1 - last default TO_2 - 2 defaults back . . TO_9 - 9 defaults back You can use these logical names in subsequent DCL commands or programs to refer to previous defaults. You can use the logical name TO_0 to mean the current default in subsequent DCL commands. This is better than using SYS$DISK:[] because SYS$DISK:[] doesn't work when your default is something like SYS$STARTUP, and it's also less typing. The logical name TO_0 is always your current default if you always use TO.COM to change your default, even when TO.COM exits because of an error or a control-Y interrupt. You can use the logical name TO_HERE instead of TO_0 if you prefer. Two auxiliary logical names are provided: TO_LOST and TO_SAVE. The TO_LOST slot is for saving defaults set by other programs that would otherwise be "lost" when running TO.COM. The TO_SAVE slot is for defaults saved with the auxiliary program SAVE_DEFAULT.COM. Run TO.COM without any arguments to display the logical name recall stack. To switch to one of the defaults listed, type the number of the default and press Return. Alternatively, you can type any valid default at the prompt according to the rules for the new-default parameter. TO.COM will display only stack entries that are not empty. Example: $ TO Enter 3 for TO_3 = DISK$DATA1:[FELDMAN] Enter 2 for TO_2 = DISK$DATA1:[FELDMAN.CHECK] Enter 1 for TO_1 = DISK$DATA1:[FELDMAN.UTI.GENERAL] Press for TO_0 = DISK$DATA1:[FELDMAN.UTI.DEFAULT] ! (current default) Or enter new default: 2 =============================================================================== Checking DISK$DATA1:[FELDMAN.CHECK] MATCH = 2 TO_3 = DISK$DATA1:[FELDMAN] TO_2 = DISK$DATA1:[FELDMAN.UTI.GENERAL] TO_1 = DISK$DATA1:[FELDMAN.UTI.DEFAULT] TO_0 = DISK$DATA1:[FELDMAN.CHECK] ! (current default) Your default is DISK$DATA1:[FELDMAN.CHECK] $ The program TO.COM avoids duplicate entries in the logical name recall stack. This holds true even if you specify different default-specs that refer to the same actual default. For example, a specific disk can be specified in several ways and one can have multiple logical names pointing to the same default. However, there are exceptions: Aliases that point to the same directory are treated as if they were different directories. Also, different search list logical names that independently translate iteratively to the same list of equivalence names are not recognized as being identical by TO.COM. Regardless, the same default-spec-string will not normally appear twice in the recall stack. One exception is when you abort TO.COM via control-Y while it is updating the logical name recall stack. Another exception is that the values of TO_LOST and TO_SAVE may by chance be duplicated in the regular part of the stack. TO.COM offers an alternate set of logical names for the recall stack: HERE - current default LAST - last default 2BACK - 2 defaults back 3BACK - 3 defaults back . . 9BACK - 9 defaults back LOST - same as TO_LOST SAVE - same as TO_SAVE To use these logical names instead of the default style TO_0, TO_1, ..., DEFINE the logical name TO_BACK to 1 (true). See the section LOGICAL-NAME STYLE for additional information. *** PARAMETERS *** P1: [new-default] Specify [disk:][directory], a logical name, or a reserved keyword. (You can also specify two defaults separated by a comma -- see the section titled TWO-STEP NEW-DEFAULT FUNCTION for details. Additionally, wildcards are allowed in the directory-spec -- see the WILDCARDS section below for more information.) Specifying [disk:][directory] takes you to that default. The directory brackets are optional. For example, $ TO USERDISK:FOO is legal and takes you to USERDISK:[FOO]. NB: TO.COM fills in missing directory brackets only when P1 is not a logical name; i.e., logical names used with TO.COM must still be defined according to normal VMS RMS rules. Therefore, if you define a logical name thusly... $ DEFINE MYDIR USERDISK:FOO and then run $ TO MYDIR the FOO part would be interpreted by TO.COM as the name component of a file-spec, not the directory component. But if you run $ TO USERDISK:FOO the FOO portion of the string will be interpreted as the directory specification [FOO] !. *** WILDCARDS *** You can use wildcards in new-default. TO.COM uses F$SEARCH to look for .DIR;1 files that match your wildcarded directory-spec. Each matching directory will be offered to the user as it is found. You can type Y to accept, N to skip, or Q to quit. Note that some wildcarded directory-specs may take a while to process. Also, directory-specs that have a trailing ellipsis are not supported. You can, however, use a trailing ...* instead. There is no significant loss of functionality because of this. *** LOGICAL NAMES *** If you specify a logical name, TO.COM performs iterative translation and sets default to the result. Iterative translation stops when TO.COM reaches a concealed, a terminal, or a search list logical name. Iterative translation also stops, of course, when an equivalence name is encountered that is not itself a logical name. The equivalence name (after iterative translation as specified above) may contain any file-spec components except a node-spec. If it contains name, type, or version components, it is assumed to be a file-spec and TO.COM uses F$SEARCH to look for a matching file. If a matching file is found, the device and directory are extracted from the F$SEARCH result. If no matching file is found, the device and directory are extracted using F$PARSE. If the logical name is a search list that points to various files and none of the files are found, TO.COM will set default to the disk and directory extracted from the first file-spec in the list. If the first translation of a logical name starts with the @ character, the @ character is removed and TO.COM then looks for a matching file. This is useful for logical names like SYS$ANNOUNCE. *** KEYWORDS *** You can use the following reserved keywords for new-default (P1): -8 thru -1: Go up minus that many directory levels. Example: TO -3 is the same as TO [---] . 1 thru 9: Go to that entry in the logical name recall stack. (The upper limit of 9 assumes that the stack is set to its default size.) Leading zeros will cause TO.COM to interpret P1 as a directory-spec. See the section titled "LOGICAL NAME RECALL STACK" for more information. H, -HELP, or ?: Display the 23-line quick-help page. L - Go to the TO_LOST default. If you use another program to change the default, then run TO.COM to change the default, TO.COM will put the default set by the other program into the TO_LOST slot if it would otherwise be lost from the stack. R - Read the saved logical name recall stack from disk. The stack is read from SYS$LOGIN:TO_STACK.DAT. S - Go to the saved default. This is the default that is assigned to the logical name TO_SAVE by SAVE_DEFAULT.COM. When you are in a default that you wish to save, run SAVE_DEFAULT.COM. (SAVE_DEFAULT.COM is supplied with this package.) T - Go to the top level of the current directory tree. For example, if your current default is disk:[AAA.BBB.CCC], this takes you to disk:[AAA]. W - Write the logical name recall stack to disk. The stack is written to SYS$LOGIN:TO_STACK.DAT. \ - This is equivalent to [000000]. It can be used with or without a disk-spec. Both $ TO new-disk:\ and $ TO \ are legal. .. - Same as [-] and it can be used with or without a disk-spec. ~ (tilde) - Same as SYS$LOGIN . Note: To set default to directories named [H], [L], [R], [S], [T], [W], or [n] where n is a positive integer .LE. the stack size, include at least one of the brackets. To set default to logical names H, L, R, S, T, W, or n, include a trailing colon. See the PRECEDENCE section for more information. *** PRECEDENCE *** In the case of P1 containing no colons or brackets it is interpreted with the following precedence: reserved keywords, logical names, directories Use a trailing colon or a bracket to force the desired interpretation if necessary. For example, to go to a directory named [2], you would run TO 2] or TO [2], but not TO 2. TO.COM was designed this way with the assumption that people don't normally use single-character directory names. If you wish to modify TO.COM to require a hyphen before the single-letter keyword you'll have to check for and remove any leading hyphen just before the statement GOSUB _CHECK_FOR_KEYWORDS and skip this GOSUB command if there was no leading hyphen. *** TWO-STEP NEW-DEFAULT FUNCTION *** The idea for this function was borrowed from a comp.os.vms post by Hunter Goatley about his "SD program". Format: $ TO default-1,default-2 ! go to default-1 and from there go to ! default2 (There must be no spaces or tabs around the comma.) This is useful when default-1 is a stack entry, logical name, or keyword which is "partly correct" and default-2 is an easy-to-type "correction". Basically, TO.COM goes to default-1, and then goes to default-2 "from there". Note that relative directory-specs in default-2 are relative to default-1 and not to the old default, which, of course, is precisely what makes this feature useful. Example: Your current default is DISK1:[USER], stack entry 3 is DISK3:[HELLO.THERE], and you wish to go to DISK3:[HELLO.THERE.MY.FRIEND]. Run $ TO 3,.MY.FRIEND to accomplish this task. Note that in this example the relative directory-spec is relative to the value of stack entry 3, not to the current default. Feel free to be creative with this feature. P2: [save-old-def] - By default, TO.COM saves the old default in the logical name recall stack. You can override this behavior by specifying N for this parameter in which case the old default will not be saved in the recall stack. P3: [DCL-verification] - Specify 1 or Y to enable DCL command verification. DCL verification will be restored to its previous state upon exit. The default is no DCL verification. *** USER OPTIONS *** The following can be found near the top of the code: $!! *** User Settings *** $ STACK_SIZE = 9 ! Total number of slots in logical name recall stack. $ TO_PROMPT = 0 ! If true, set prompt string to current default. $ TO_BRIEF = 0 ! If true, omit match value and outgoing recall stack. $ TO_BACK = 0 ! If true, use old nBACK-style logical names. These are the out-of-the-box defaults for these features. Edit the file to change them if you wish. The last three can be overridden by defining the logical names TO_PROMPT, TO_BRIEF, and TO_BACK, respectively, to 0 (false) or 1 (true) as desired. Details follow. *** STACK_SIZE *** If you don't like the default size of 9 for the recall stack, you can change it by setting the STACK_SIZE symbol to a different positive integer. You will find this symbol near the top of the file. Note that making the stack size very large may slow TO.COM considerably. Better stack-manipulation algorithms would be needed in that case. *** PUT THE CURRENT DEFAULT IN YOUR DCL PROMPT *** TO.COM can put the current default in your DCL prompt. Run the command $ DEFINE TO_PROMPT 1 to enable this feature. Note that if your current default is longer than is longer than 31 characters, TO.COM will truncate it on the left. To disable this feature, either re-DEFINE TO_PROMPT to 0 (false) or DEASSIGN it. In either case, finish by running the DCL "SET PROMPT" command to clear the last default from the prompt. The out-of-the-box default for this feature is 0 (false). If you want to enable this feature without using the logical name, go to the User Settings section at the top of the code and change $ TO_PROMPT = 0 to $ TO_PROMPT = 1 Note that the logical name takes precedence over this symbol. *** TO_BRIEF *** By default, TO.COM tells you which stack entry your new default matches if any. For example, if you type in a new-default that happens to match stack entry 3, TO.COM will display "MATCH = 3". Also, by default, TO.COM displays the full logical name recall stack after processing a new default. Define the logical name TO_BRIEF to "TRUE" or "1" if you want TO.COM to *not* display the MATCH line and the "outgoing" recall stack. Alternatively, you can set the symbol TO_BRIEF near the top of the code to TRUE or 1 to make it the default. Note that the logical name TO_BRIEF takes precedence over the symbol TO_BRIEF. *** LOGICAL-NAME STYLE *** As mentioned at the end of the LOGICAL NAME RECALL STACK section, there are two styles of logical names available with TO.COM . TO_n style: TO_0, TO_1, ..., TO_LOST, TO_SAVE nBACK style: HERE, LAST, 2BACK, 3BACK, ..., LOST, SAVE The out-of-the-box default is the TO_n style. This follows the VMS naming convention which minimizes the risk of conflicting logical names. But the nBACK style is easier to use (in the author's opinion) and can be used if it does not conflict with logical names on your system. To use the nBACK style, edit TO.COM. Near the top of the file you will find the User Settings section. Change $ TO_BACK = 0 to $ TO_BACK = 1 Note that TO.COM also supports the logical name TO_BACK. Defining this logical name to 0 (false) or 1 (true) overrides the value specified in the file. Additionally, if this logical name is undefined, TO.COM will define it to be the value it is set to in the file. This is done in order to let SAVE_DEFAULT.COM know which style you are using. This way, SAVE_DEFAULT.COM knows whether to assign the current default to logical name SAVE or TO_SAVE. If you change from nBACK style TO_n style in the same interactive session, any nBACK-style logical names will be "left over" and will not be updated further. If you want to clear these leftovers, run @CLEAR-NBACK-LNMS.COM. If you change from TO_n style to nBACK style, no such problem arises as the TO_n logical names are always kept current while the nBACK-style logical names are defined based on the corresponding TO_n-style logical names when the nBACK style is enabled. Summary: TO_BACK = 0 ! Use TO_0, TO_1, ..., TO_LOST, TO_SAVE TO_BACK = 1 ! Use HERE, LAST, 2BACK, 3BACK, ..., LOST, SAVE Remember that the logical name has precedence over the symbol in the User Settings section in the file. Therefore, if you change the symbol value in the file, be sure that the logical name is defined according to your wishes. If for some reason you wish to DEASSIGN all logical names created by TO.COM and SAVE_DEFAULT.COM, run @CLEAR-TO-LNMS.COM. *** FEEDBACK *** If you have any questions, comments, or problems with regard to TO.COM, please write the author at betaneptune\a\yahoo or alanedfeldman\a\yahoo.