TO.COM v5.0	Author: Alan E. Feldman 


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. 

Special note to users of the previous release of TO.COM (v4.3-1): With
this new version, v5.0, both styles of logical names -- TO_n and HERE,
LAST, nBACK -- are implemented in the same file: TO.COM. The user
setting TO_BACK is used to choose the style. The out-of-the-box
default is the TO_n style which follows the VMS naming convention. To
switch to the nBACK-style logical names, see the LOGICAL NAME STYLE
section. 


CONTENTS: 

CONVENTION  
INSTALLATION  
QUICK START  
FORMAT  
DESCRIPTION  
    LOGICAL NAME RECALL STACK  
PARAMETERS  
    LOGICAL NAMES
    KEYWORDS
    PRECEDENCE  
    TWO-STEP NEW-DEFAULT FUNCTION  
USER OPTIONS
    STACK SIZE
    PUT THE CURRENT DEFAULT IN YOUR DCL PROMPT
    BRIEF VS. VERBOSE OUTPUT
    LOGICAL NAME STYLE
NEW IN V5.0
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 :== @disk:[dir]TO.COM 
    $ TO -INIT  ! to initialize TO.COM 

Ensure that both commands above have been run before using TO.COM. 


*** QUICK START *** 

Use TO.COM as you would the SET DEFAULT command. 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. 


*** FORMAT *** 

    $ TO  [new-default] [save-old-def] [DCL-verification] 

Use "" as a placeholder for any skipped parameters. 


*** DESCRIPTION *** 

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 is 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. (See the section
called LOGICAL NAME RECALL STACK for more details.) 

TO.COM is designed for interactive use only. 

TO.COM v5.0 is not fully compatible with the previous public release,
v4.3-1. 

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 with an error or
because of 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 <RET> 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 distinct. 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.) 

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 portion. But if you run 

    $ TO USERDISK:FOO 

the FOO portion of the string will be interpreted as the directory
specification [FOO] !. 


*** 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 a matching file is not 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 default stack size is set.) 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. 

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]. 


\ - 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], [S], [T], 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, S, T, 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. But TO.COM can be easily modified to require a hyphen
before T, L, S, and H if desired. Edit the file and go to the
_CHECK_FOR_KEYWORDS subroutine and change "H", "L", "S", "T" to "-H",
"-L", "-S", "-T", respectively; and you can update the help screen at
the bottom of the file to reflect your changes. Displaying the recall
buffer will still show L and S, but you can fix that, too, in the
_GET_NEW_PARAMS subroutine. 


*** 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. 

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-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 overriden by
defining the logical names TO_PROMPT, TO_BRIEF, and TO_BACK,
repsectively, 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
certain minor things won't work as well with a stack size greater than
9. For example, the supplemental command procedures that clear TO.COM
logical names will work only for stack sizes of 9 or less. Note also
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 the default-spec of 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 not to 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 initial
value of 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 (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. 



*** NEW IN v5.0 *** 

o  User option to have default in DCL prompt
o  Improved processing of the new-default parameter
o  Improved checking of the validity of the new default
o  Improved error checking and control
o  Both styles of logical names in one file
o  Some minor bugs fixed
o  New keyword ~ (tilde) for SYS$LOGIN
o  New supplementary programs



*** FEEDBACK *** 

If you have any questions, comments, or problems with regard to
TO.COM, please write the author at betaneptune\a\yahoo.com. 
