Category : Utilities for DOS and Windows Machines
Archive   : APATH23.ZIP
Filename : APATH.DOC

APATH Copyright (c) 1992 Walt Stoneburner
v2.3 All Rights Reserved.

Altering the current PATH environment variable can be a pain at times,
especially when the changes are minor. APATH was designed to allow the PATH
variable to be manipulated quickly and easily without the overhead of extra
environment variables or terribly complex batch files.

APATH is ideal for modifying the path in everyday batch files, some makefiles,
LAN administration login/logout files, from the command line, etc.

The ability to remove directories from the PATH environment variable
until needed should result in quicker searches of the path. Software that
requires its directory be in the path can be activated by a simple batch file
which makes a path addition, runs the software, and later removes the excess
baggage.

Entering APATH without arguments provides brief usage information. It also
shows off the copyright message.


Usage:
APATH [/M] [+|-]path[;path...]

/M Changes affect the master environment.
No parameter changes the parent environment.

path Multiple directories may be specified,
separated by semicolons. If a directory
is not already part of the PATH, it will be
prepended (placed in front). If it is part of
the PATH, the path addition will be ignored.

+path Same as above, but the specified directory
will be appended to the end of the PATH.

-path The specified directory will be removed from
the PATH variable. If the directory can not
be found, the deletion will be ignored.

Multiple prepends, appends, and deletes may be specified on a
single line. Only the first character of each directory sequence
may be a - or +.


APATH can return status information via the DOS errorlevel.

An errorlevel of 1 is returned if the path could not be changed successfully
(note that this errorlevel is not returned if you try to add an
already-existing element to the path, or delete one which didn't exist to
begin with; it's only returned if something awful happens). APATH returns an
errorlevel of 0 if the command completes without incident.

Examples:
APATH C:\UTIL Prepend C:\UTIL to front of PATH.

APATH +C:\UTIL Append C:\UTIL to end of PATH.

APATH -C:\UTIL Remove C:\UTIL from PATH.


APATH /M C:\UTIL;C:\TMP Prepend C:\UTIL then C:\TMP to PATH
in master environment only.

APATH +C:\UTIL;C:\BIN -D:\TMP F:\USR\LIB
Append C:\UTIL then C:\BIN,
Delete D:\TMP, and
Prepend F:\USR\LIB to PATH.

Note: The prepend function will effectively reverse the order of the
specified directories. e.g. APATH A;B;C will make PATH=C;B;A
This is because A is prepended, then B is prepended in front
of the A, and finally C is prepended in front of B.

Using the + to append will produce arguments in the same order
as they are specified on the command line.


Other Examples Involving APATH:

Starting Windows, in a WIN.BAT file:
apath c:\aldus;c:\excel;c:\winword;c:\windows
if errorlevel 1 goto opps
win %1 %2 %3 %4 %5
apath -c:\aldus;c:\excel;c:\winword;c:\windows
goto quit
:oops
Echo could not adjust path!
:quit

Kill the whole path to impress the girls; anyone can type PATH =
apath -%path%

Kill redundant entries in the path (works for short paths):
apath -%path% +%path%

Reverse the order of the path (just because!):
apath -%path% %path%

LAN login:
net use f: \\moocow\c-drive
apath f:\util

LAN logout:
net logout \\buckaroo
apath -g:\sound

In a "makefile":
y_tab.c : grammar.y
apath d:\usr\bin
yacc grammer.y
apath -d:\usr\bin



A Word About Makefiles

Some MAKE programs store a copy of the PATH at runtime, thus with each line
executed in a shell uses a copy of the path when invoked. If APATH doesn't
seem to work, try using the /M parameter to change the master environment.
If this still doesn't work, try using a MAKE which isn't brain-damaged.


Warning to Power Users

I'm sure some wiseass will try to break the software by trying something
like this:
APATH %path% %path% %path% %path% %path% ...

Good news for wiseasses everywhere! Most likely you'll get the weird result
you're looking for because COMMAND.COM doesn't have enough room to pass the
whole command line to the program.

My tests have shown that only 128 bytes get passed to APATH from the
command line. And one of those is the space after the command and the
other is the return key. So, really you have only 126 bytes in an
argument. Internal DOS commands do not seem to have this restriction.
Anything after the 126th character magically disappears, so you could
get part of a directory name appended!

If you get into problems where APATH is acting funny for large arguments,
break up your command into multiple APATH commands. While I've provided
for a 4K path in the program (in case anyone modifies their shell), DOS is
limited to 128 bytes and 4DOS appears to have a larger 256 byte maximum for
the size of an environment variable.

The idea is that after using APATH (with some batch files) you'll have
a much shorter path. 80 characters or less is quite reasonable and will
offer in return a better response time if you happen to enter a bad
command making DOS go searching your disk for something that isn't there.


A Word About Shells

Some shells with evaluate %path% on the command line, such as 4DOS and
its mutant sister, NDOS. Others will only evaluate %path% while in a
batch file.

The only problem I've ever had with APATH is specifying multiple, large
arguments using the above command line expansion in conjunction with
MS-DOS as the underlying operating system. The path used to get corrupted
by extra garbage characters being inserted as a path. I traced the problem
to how MS-DOS puts parameters in the _PSP segment; under the right
conditions a non-terminated string can result, screwing up
most parsing routines. The problem has a workaround in APATH v2.3.

Note that DR-DOS doesn't have this PSP problem, so prior versions
of APATH will work fine under this operating system.

However, you don't have to toss MS-DOS to use older versions of APATH
(like you really would); just keep the total length of the command-line
arguments to 127 bytes or less per command line and applications will work
fine, not just APATH.

[ I suspect everyone knows that 4DOS is owned by Rex Conn and JP Software,
that NDOS (a subset of 4DOS and the addition of the Norton Utilites) is
owned by Symantic Corp, that MS-DOS is owned by Microsoft, that DR-DOS
is owned by Digital Research, and that APATH is owned by Walt Stoneburner.

Don't you think these 'ownership' paragraphs are a bore? Look guys, if
people don't know who you are, you need to spend a little more of that
green stuff in marketing! Get a life. Enough said. ]



Version History

v1.0 APATH developed; did extensive testing and multiple revisions
before first public release. Appends, Deletes [-], and Prepends [+]
directories to the PATH environment variable. Modifies the parent
environment. APATH was written completely in assembly language in an
effort to keep size down and speed up.

v2.0 Reversed meaning of + to mean append and made default prepend.
[Code size increased to 2546 bytes long.]

v2.1 Reduced code size 800 bytes [code size now 1746 bytes long].

v2.2 Added /M for master environment. Reduced source code 15 bytes
[now 1731 bytes long]. Bug fix for empty environment.

v2.3 Reduced code size by 41 more bytes [now 1690 bytes long; 8 from a
restructure of the code, and 47 from hand optimizations, and
added 14 for new features]! Increased buffer size; that should allow
for some hefty command lines. This should also prevent bug reports
from people complaining about really-really long paths if anyone
writes a shell or operating system supporting them. Added error
levels. Found MS-DOS _PSP bug and built workaround for it.


Thank You List

Many thanks to Doug "Power User" Austin who beta-tested the software,
gave me better insight on making the user interface better, corrected
some documentation errors, and laughed at the jokes in the documentation
without a lot of prodding. He has the talent for finding the non-trivial-
obvious mistakes during development. He also handled a lot of the
distribution of earlier versions... and got a whole minute of upload credit
for this small file.

Thanks to Tamara "So What's It Do?" Harrison for calling each night to
make sure I wasn't sitting on my duff. ...usually I was. She offered
a lot of support even when the nature of the utility wasn't clear or
completely defined yet. Is that something or what?

Thanks to Phillip "Now What You Need..." Wherry, who inspired me that
people ought to be able to put things at the end of the path. He also
made a few minor revisions to the documentation.



Disclaimer & Other Legal Stuff

NO LIABILITY FOR CONSEQUENTIAL DAMAGES
In no event whatsoever shall the author, suppliers of APATH, or basically
anyone in the universe, be held liable for any damages whatsoever
(including, without limitation to, damages for loss of business profits,
business interruption, loss of business information, other pecuniary
loss, paper cuts, or the destruction of the galaxy) arising out of the use,
abuse, misuse, or inability to use this program, even if the author has
been advised of the possibility of such damages. If you are uncomfortable
with the above, please do not use the program or send any money. Look,
this program was written for personal use; it worked well for me, so I'm
virtually giving it away; I don't want my tush sued off because I was
just being generous. (This bag is not a toy!)

NO WARRANTY EXPRESSED OR IMPLIED
While you are free to try out the software for 30 days, do not send any
money until you are satisfied with the program. Monies cannot be
returned. No warranty or guarantee is provided that the software will
operate as stated in this manual.

GRANT OF LICENSE
After sending the registration card below, you are free to use APATH
on as many personal machines as you can possibly get your hands on from
now until the Return of Christ. Businesses are site licensed for a finite
number of copies executing simultaneously on different machines (see
registration card).

COPYRIGHT
This software is owned by Walt Stoneburner. You are free to
modify and patch this version to suit your needs. However, please do not
redistribute the patched version; you may redistribute the patch and/or
instructions for making the patch. I would prefer that people obtain clean
copies in the event we choose to offer technical support.

TECHNICAL SUPPORT
We make no claims or promises for offering technical support. However,
if you write me, I'll consider it. If you bribe me, I'll take you
very seriously.

OTHER RESTRICTIONS
Don't hurt anyone. It isn't nice. Look both ways before crossing the
street. Kids, don't smoke or do drugs. And if you're gonna drink and
drive, get your parents' permission first.

CUSTOMER REMEDIES
Take an aspirin. Read the directions. Read them again. Aside from that, I
can't help you.



EMail Addresses

If you'd like to write and try to weasel support, technical information,
or source code from the author, he can -indirectly- be reached by the
following EMail addresses.

Please state clearly that your message pertains to APATH (give the
version number). These friendly people below will get the message to me
one way or another and are not necessarily responsible for answering
your pleas. They are certainly not responsible if anything goes wrong.

CompuServe: 70651,2707 or 72137,1152
Internet: [email protected] or [email protected]
GEnie: AUSI-DGATE or A.GARIES


Registration

If you are an individual and are using APATH for personal use, you're in luck...
Using APATH will cost you nothing, however, I would like you to send the
registration form below in anyhow. By not charging a fee to individuals,
I'm hopeful you'll feel more inclined to let me know you are using
something I've written, and that I should therefore devote more free time to
projects like this.

If you are a company, well... you're not as lucky as the individuals above.
However I know that you will most likely want a site license or something
like that. And I'm willing to do that... cheap. Very cheap! (See below.)

So... on with the paper work.

Please fill out below and send to:

APATH Registration
c/o Walt Stoneburner
9307 Lundy Court
Burke, Virginia 22015


+----------------------------------------------------------------------------+
| |
| APATH v2.3 Copyright (c) Walt Stoneburner Mar 31, 1992 |
| Registration All Rights Reserved. |
| |
| Name: ________________________________ [ ] My personal use, |
| no charge. Thanks! |
| Company: _____________________________ |
| [ ] My personal use; I've |
| Address: _____________________________ enclosed $5 or more, send |
| commented source code |
| _____________________________ |
| [ ] Company site license |
| _____________________________ 1 - 19 users : $1.00/copy |
| 20 - 49 users : $0.75/copy |
| Phone: _____________________________ 50 - infinity : $0.50/copy |
| Optional [ Circle: DAY NIGHT WORK ] (up to $100) |
| |
| [ ] Or... we would like to distribute APATH with our products. Enclosed |
| is $100 which gives us an infinite site license for this product and |
| your permission to distribute this and future upgrades of APATH as |
| they become publicly accessible. |
| |
| ( ) I am interested in other ( ) I would be interested in Beta |
| things you develop[ed] when testing software as it is being |
| they become available. developed. |
| |
| EMail Address: ________________________________________________________ |
| |
| Comments / How Are You Using APATH: |
| |
| ________________________________________________________________________ |
| |
| ________________________________________________________________________ |
| |
| ________________________________________________________________________ |
| |
+----------------------------------------------------------------------------+