The World of Computer Software/World_Of_Computer_Software-02-387-Vol-3of3.iso/r/retain11.zip/RETAIN.DOC

Text File | 1992-12-10 | 11KB | 189 lines

--- RETAIN 1.1 by Jim Groeneveld, 10/12-92, retains current path.
    Pure BATch equivalent of PUSH/POPDIR, up to 8 levels, no TSR.
    Optionally shows all nested path levels.

===CONTENTS of package===
This package (.ZIP) includes the following files:
RETAIN   BAT      14,310  12-10-92  01:10:00  Original BATch program RETAIN
RETAINCD BAT       1,387  12-10-92  01:10:00  Combination of RETAIN and CD
$RETURN$ AUX          28  08-27-92  06:00:00  Auxiliary file (necessary)
RETAIN   DOC      11,157  12-10-92  01:10:00  This documentation file

===USAGE: RETAIN current path===
Enter 'RETAIN [aux-path[aux-file]│*│[/│-]?]' from the directory to retain;
aux-path = drive:\subdir\ of auxiliary file $RETURN$.AUX, incl. trailing '\';
aux-file = the eventual alternate auxiliary file name for $RETURN$.AUX;
*        = list the currently stored paths (also with 'RETURN *');
? (or /? or -?) = display this help.
DO NOT SPECIFY OTHER PARAMETERS. THIS WILL PRODUCE ERRONEOUS RESULTS!
RETAIN may be called successive times to store up to 8 paths.

===USAGE: RETURN to previous path===
Enter 'RETURN' (the literal command, not only the RETURN/ENTER-key) to return
to the very last path stored in the path list (no parameters!). This path is
removed from the list and RETAIN thus has one more level to store the next time.
Enter 'RETURN *' to list the currently stored paths.

===USAGE: RETAINCD to retain current path and change drive:subdirectory===
Enter 'RETAINCD drive┼path [aux-path[aux-file]│*│[/│-]?]', in which:
drive    = drive specification to CD to, e.g. 'C:';
path     = absolute (\[...[\...]]) or
           relative   (...[\...]) path specification to CD to.
    At least one of these (either drive or path) or both _must_ be specified.
aux-path = drive:\subdir\ of auxiliary file $RETURN$.AUX, incl. trailing '\';
aux-file = the eventual alternate auxiliary file name for $RETURN$.AUX;
*        = list the currently stored paths (also with 'RETURN *');
? (or /? or -?) = display this help.

***WARNING!!!***
MANY (LONG) PATHS MAY CAUSE BAT FILE LINES TO EXCEED 127 CHARACTERS.
THIS WILL CREATE UNPREDICTABLE, AND ERRONEOUS RESULTS!!!!!!!!!!!!!!!
IN SOME INSTANCES THE SYSTEM MAY EVEN HANG OR CRASH! Thus, though the algorithm
is correct the DOS command line length limitation may restrict its use.

===Determination of location (and name) of auxiliary file $RETURN$.AUX===
The auxiliary file $RETURN$.AUX will be searched for in the paths or as the
full file specification (eventually with different, alternative filename and
extension) from the data below in that order until it is found.
a. the first and only parameter when calling RETAIN
   1. the full _path_ only, incl. trailing '\' (e.g. 'RETAIN C:\UTIL\') or
   2. the full _file_specification_ (e.g. 'RETAIN C:\UTIL\AUX-FILE.$$$')
b. the environment variable %RETAIN% (specify environment variable RETAIN
   either from the DOS prompt or in AUTOEXEC.BAT) (DOS 3.x and above only)
   1. the full _path_ only, incl. trailing '\' (e.g. 'SET RETAIN=C:\UTIL\') or
   2. the full _file_specification_ (e.g. 'SET RETAIN=C:\UTIL\AUX-FILE.$$$')
c. the ROOT directory of C: (C:\) (or automatically any APPENDed path)
d. the ROOT directory of the CURRENT drive (\)
e. the CURRENT directory (.\)
f. the PARENT directory of the current one (..\)
g. the SAME directory where RETAIN.BAT is residing:
   if EXPLICITELY specified when starting RETAIN (by path, DOS 3.x&up only)
   (NOT if RETAIN.BAT can only be found via the PATH!) (e.g. 'C:\UTIL\RETAIN')
h. the DOS 3.x PATH variable (this may take quite a while), new in version 1.1

So make sure to place or name $RETURN$.AUX such that it can be found in one of
these ways. All this effort is done because the DOS ECHO command can not write
lines without CRLF, so an external auxiliary file is necessary that already
contains such a line.

===Further remarks===
If using DOS 3.2&up and using the APPEND path utility do at least specify the
'/X' parameter when calling APPEND for the first time or the auxiliary file
still can not be found.

It is handy to put RETAIN.BAT in a directory that is in your path (e.g.
C:\UTIL) and to have C:\ in your path in order to be able to find the temporary
created file C:\RETURN.BAT from any drive:subdirectory.

In order to restart each time with an empty list when the system is booted
add the following statement to your AUTOEXEC.BAT file:
IF EXIST C:\RETURN.BAT DEL C:\RETURN.BAT    (eventually redirect this to NUL)

C:\RETURN.BAT is being created explicitely in C:\ in order to have only
ONE RETURN.BAT on a system. If you do not have a C: drive choose one of:
a. manually change all references to C:\ within this BATch file into A:\
b. add a command to your AUTOEXEC.BAT file: 'SUBST C: A:\', which after
   reboot will cause references for drive C: to go to drive A:.

Take care to write-enable C: (or A:) and not to have the drive or the root's
directory entry table full!

===Minimal system requirements===
IBM-PC (88/86/x86) or compatible
64kb memory
(MS)DOS 2.x or above; the program has been developed for DOS 3.x and above.
In order to make it run under DOS 2.x one should change the appropriate lines
within the .BAT file as indicated there. That is necessary because with DOS 2.x
a program can not be called by specifying a path before its name.

With DOS 2.x the environment variable RETAIN can not be used either. Besides,
the DOS PATH can not be scanned for the auxiliary file. Another adaptation for
DOS 2.x to include is to change .BAT file lines 'ECHO.' into 'ECHO @', in which
'@' means the ascii-255 character, thus 'echo  ', or it prints "ECHO is off".
Furthermore, with DOS 3.3&up one might change 'echo off' into '@echo off'.
The DOS 3.3&up CALL command does not occur within RETAIN, though it does within
RETAINCD. If used with lower DOS versions it may be changed into 'COMMAND/C' or
one might apply an external CALL command for the lower DOS versions (by me too).

Though not explicitely stated there these adaptations already might have been
applied to RETAIN version 1.0 too.

===New in version 1.1===
The DOS PATH environment string is used to search additionally for $RETURN$.AUX
if it could not be found elsewhere (not specified on the command line or as
environment variable RETAIN). One general method, using a recursive call to
RETAIN (somewhat more complicated) with the PATH as the arguments, is being
used. There has been thought of an alternative method, using the PATH variable
directly, but that one has some important drawbacks, as outlined below:

rem ---DOSPATH---
rem 'if' line below may cause the system to crash with a too long path. Besides,
rem the test may not work correctly because the path consists of more than one
rem specification, separated by the delimiter ';', though it seems to work if
rem it reads "%path%"=="", but not if it reads ""=="%path%".
rem So do not include it, but let the sub itself find _no path_ eventually
if "%path%"=="" goto notfound
for %%p in (%path%) do if exist %%p\$RETURN$.AUX %0 %%p\ .auxpath_checked
rem above: subdirectories; below: root directories;
for %%p in (%path%) do if exist %%p$RETURN$.AUX %0 %%p .auxpath_checked
:notfound
goto nopath

A complete path specification (environment space) may be 127 characters long
including the "PATH=" part of the DOS command to set the path, leaving a
maximum of 122 for the actual path specification. This would leave too less
space for the rest of (the 'if' and) the 'for' line. So these lines may work
well with short paths, but may cause the system to hang with longer paths. The
choosen method allows for longer paths and has preference. Besides, if the
path is too long for the command line, this alternate method would cause the
system to crash, while the applied method automatically ignores the extending
path characters and causes the batch file to continue (the last examined path
entry may be truncated and probably does not cause the auxiliary file to be
found). In the worst case extending path entries are not searched, so do not
yield an eventual positive result: thus the auxiliary file will not be found in
that case.

===History===
History of RETAIN (previous 0.versions under different names):

 version │.BAT like │  generated   │    auxiliary    │ description of changes
──date───┼─pushdir──┼──popdir.bat──┼──────file───────┼───────────────────────
 2/11-89 │ SAVE-DIR │ C:\LOAD-DIR  │    CHANGE.COM   │ initial version.
 4/ 4-90 │ REMINDIR │ C:\BACK2DIR  │ C:\CD─SP─NO.EOF │ standard DOS only;
         │          │              │                 │ add. params are next pg.
 6/ 4-90 │ REMINDIR │ C:\BACK2DIR  │    CD─SP─NO.EOF │ aux. in other subdirs.
19/ 9-91 │ REMIND   │ C:\RECALL    │ C:\$RECALL$.TMP │ faster new algorithm;
         │          │              │                 │ other subdirs removed;
         │          │              │                 │ add. params removed;
         │          │              │                 │ remembered subdir check.
20/ 8-92 │ REMEMBER │ C:\RESETDIR  │    $RESET$.TMP  │ env.var=subdir or
         │          │              │                 │ other subdirs searched;
         │          │              │                 │ better subdir check.
27/ 8-92 │ RETAIN   │ C:\RETURN    │    $RETURN$.AUX │ nesting up to 8 levels;
 vs. 1.0 │          │              │                 │ list stored paths;
         │          │              │                 │ aux. in more subdirs;
         │          │              │                 │ further improvements;
         │          │              │                 │ utility RETAINCD.BAT .
10/12-92 │ RETAIN   │ C:\RETURN    │    $RETURN$.AUX │ aux. file specification;
 vs. 1.1 │          │              │ or any if full  │ aux. may be in DOS PATH;
         │          │              │ path & file name│ aux.spec. with RETAINCD;
         │          │              │ specified as arg│ chk valid C:\RETURN.BAT;
         │          │              │ or env.var.     │ adaptable for DOS 2.x;
         │          │              │  .\$RETAIN$.BAT │ major internal changes.
         │          │              │ temporary file  │
         │          │              │ in current dir. │

===Future===
- multiple RETURN files, allowing different 'memory' sets.
If there are enough requests from users:
- deletion of a specific path level (by sequence number) from the list,
  e.g. 'RETAIN .n' in which n=1..8 (or 'FORGET n' calling 'RETAIN .n').

───────────────────────────────────────────────────────────────────────────────
Centrum voor Medische Informatica TNO       <Email>              |  |  |\/|
TNO Center for Medical Informatics | [e-mail]  |  \_/  |  |  |
( CMI-TNO )    | Y. Groeneveld     | [e-mail] | Jim Groeneveld
P.O.Box 124    | Wassenaarseweg 56 | [e-mail]      | Schoolweg 14
2300 AC Leiden | 2333 AL Leiden    |                        | 8071 BC Nunspeet
Nederland.     | (+31|0)71-181810  | Fax (+31|0)71-176382   | 03412-60413