Simtel MSDOS - Coast to Coast/simteldosarchivecoasttocoast.iso/pathutil/desetp12.zip/SETPATH.DOC

Text File | 1991-09-07 | 10KB | 242 lines

                                    SETPATH

       A Utility for showing or setting the DOS environment PATH string
                        (Version 1.2 - September 8, 1991)
        Copyright (c) Donald E. Ekman 1990, 1991.  All rights reserved.



SETPATH either prints or sets the current PATH environment variable.  When
setting the PATH variable, SETPATH expects a PATH string in the form required
by DOS, or the name of a file containing the wanted PATH string.  In either
case, SETPATH places that string in the active environment, replacing any
existing PATH string.  The new string need not be the same size as the current
string, but if it is longer, there must be enough available environment space
to accommodate it.  In particular, the string may be longer than the 128-byte
limit imposed by the DOS command line buffer, but to use this feature, the PAT
string must come from a file.
SETPATH has been tested with DOS Versions 2.1 through 3.3, 4.01, and 5.0; it
has not been tested with Version 4.0.  Because SETPATH uses undocumented
features of DOS to find the active environment, its correct operation for
versions of DOS with which it has not been tested is not assured.  (The author
has received reports that SETPATH also works correctly with the 4DOS and NDOS
replacements for COMMAND.COM, but he has not personally verified this.)

USAGE

SETPATH is invoked by:

     SETPATH

     SETPATH path_string

     SETPATH -f[d:\path]filename
     SETPATH -F[d:\path]filename
     SETPATH /f[d:\path]filename
     SETPATH /F[d:\path]filename

where:

     path_string is the new PATH environment variable string in the same form
                 required by the DOS PATH command.  (Do not include "PATH=".)

     filename    is the name of a file containing the new PATH string.  The
                 drive path qualifiers are optional.  No space is permitted
                 between the switch (-f, -F, /f, or /F) and its argument.  The
                 file content must have the form:

                 PATH=any_wanted_text_string

                 The word PATH may be in any combination of upper and lower case
                 letters.  This word and the following equals sign are required
                 to help prevent using the wrong file, and must be the first
                 five characters in the file except for spaces and control
                 characters such as tabs and newlines.  (See NOTES below.)

If no argument is given, SETPATH locates and displays the current PATH
environment variable.

MESSAGES

SETPATH first displays a copyright notice, followed by either the current path
environment variable string (if no argument is given), a successful completion
message, or an error message.  In the event of any error, the original PATH
string is left undisturbed.

Error Messages

An error message appears whenever SETPATH cannot perform its requested
operation.  The following error messages are possible:

     Too many arguments    (1)   [Numbers in parentheses are values returned
                                 by SETPATH; these may be tested in a batch
                                 file using the "if errorlevel" test.]

          SETPATH was invoked with more than one argument.  This message will
          also occur if one or more spaces are left between the file switch and
          its argument.

     Can't open path file [d:\path]filename    (2)

          SETPATH was unable to open the specified file for read only.

     Failure seeking end of [d:\path]filename    (3)

          SETPATH was unable to position its pointer to the end of the file
          using the C library function fseek.  Recreate the file.  If the
          condition persists, notify the author.

     Failure in ftell with [d:\path]filename    (4)

          SETPATH was unable to determine the length of the file using the C
          library function ftell.  Recreate the file.  If the condition
          persists, notify the author.

     Failure allocating new PATH buffer    (5)

          Inadequate memory was available to allocate temporary buffer space for
          the new path string.  This memory must exist within the 640K DOS lower
          memory.  Release some TSRs if necessary.

     Path file must begin with PATH=    (6)

          The specified file was successfully opened, but it did not begin with
          "PATH=".

     Not enough environment space for new path    (7)

          The new path is too long to fit in the available environment space.
          See your DOS manual for information on how to increase the environment
          space. If you are using a secondary command shell, see the section
          headed NOTES below.

Normal Completion Message

When SETPATH has successfully placed the new PATH string into the environment,
it issues the message:

     New PATH string successfully placed in environment.    (0)

If SETPATH is invoked with no argument, it displays the copyright notice,
followed by the current path environment variable string, and returns a value
of 0.

NOTES

The file must contain a copy of the new PATH string that is wanted in the
environment, except that it may contain spaces and control characters such as
tabs and newlines.  Before placing the file content in the environment, SETPATH
changes any lower case letters in the word "path" to upper case and squeezes
out all blanks and all control characters.  (SETPATH defines a control character
as any character in the range 0x00-0x1f and the character 0x7f.)  If you do use
newlines to separate the elements of your PATH string, do not forget the
required semicolons; SETPATH will NOT add them automatically.

SETPATH searches for and modifies the active environment (given an argument).
Normally this is the root environment, which was created when you booted.
However, if you shell out of a program or run a secondary command processor, or
if you explicitly run a shell of COMMAND.COM, then the active environment will
be different from the root environment.  The distinction is important because it
is the active environment, rather than the root, that gets passed (as a copy)
to a program and is also used by DOS for the path and prompt.

When a program or a user creates a secondary shell, DOS does not insure that
the environment used by the shell is at least as large as the one in the root.
Instead, by default, it looks at how much of the environment is actually in use
and rounds this up to a multiple of 16 bytes.  With DOS 3.2 and later, you can
set a shell with the command

     command /e:xxx

and adjust the size of the environment.  Unfortunately, most application
programs that shell out to the operating system do not use this feature, so the
active environment in the shell has very little extra room.

If an inherited environment is too small, there is a way around the problem.
Before loading the program from which you want to shell, issue several commands
of the form:

     set a=junkjunkjunkjunkjunkjunk

Then, in the shell, use:

     set a=

The space created by the bytes taken up by the initial SET commands will be
available after you remove the a variable.

BUGS AND INCOMPATIBILITIES

Yes, a section on bugs and incompatibilities.  All software should come with
documentation that contains such a section, but, alas, few do.

Bugs

There are no presently known bugs in SETPATH.

Incompatibilities

The following compatibility problems have been reported.  Most appear to
result from certain software assuming that the path environment variable
cannot be longer than 128 bytes.  There is no general solution to this
problem that can be implemented in SETPATH.

DOS 4.01.

The DOS backup program appears to have a problem with long path statements.
For example, if one enters "backup c: a:", the backup program dies with the
message "No source drive specified."  This appears to be limited to DOS 4.x.

An unspecified version of zoo ends with the message "Abnormal program
termination."  Whether zoo correctly performs its intended task before this
message appears was not reported.  Again, this is limited to DOS 4.x.

Mathematica 1.2, which uses the PharLap DOS extender, displays a curious
error under DOS 4.01.  If an external program is run, and then run again,
the second execution of that program terminates with an (unspecified) error
message.

DOS 5.0

Although SETPATH works correctly with DOS 5.0, the DOS PATH command, when
used with no argument, displays only the first 128 bytes of the path
environment variable.  This misfeature is new with DOS 5.0.  Instead of the
DOS PATH command, use SETPATH without an argument.  SETPATH will display the
entire path variable.

DOS Version Independent

Turbo C++ does not operate properly when the portion of the path variable
specifying the Turbo C++ directory appears after byte 128 in the path
variable.  This was cured by placing the reference to that directory within
the first 128 bytes of the path variable.

PROGRAMMING

SETPATH was written in C, and compiled with the Microsoft C Version 5.10
compiler, and linked with the Microsoft Version 5.03 linker.  The small memory
model was used, which required special treatment of the environment space, which
is accessible only with far pointers.

LICENSE

You may use this program and distribute it freely, provided that not charge
is made for its distribution, and all copyright notices are retained.  SETPATH
is a copyrighted program.  All ownership rights remain with the author.  You
may not use this program, or any portion of it, in any derivative work without
the express permission of the author.

If you distribute this program, please keep this documentation file with it in
some archived form.  If you have any comments or suggestions for improvement,
send them to:

          Donald E. Ekman
          3586 Berry Way
          Santa Clara, CA  95051-1902

          Internet:  [e-mail]
                     [e-mail]