Contents of the TPENV.DOC file
TPENV - Routines for manipulating the DOS environment
Released to the public domain
TPENV is a Turbo Pascal unit that allows application programs to manipulate
the DOS environment by reading and setting environment strings in either the
current program's environment or in the system master environment.
The environment is an area defined by DOS to pass limited amounts of ASCII
text from one program to another. Standard strings stored in the environment
are those associated with COMSPEC, PATH, and PROMPT. Although the DOS batch
language provides the SET command to manipulate the environment, there are no
standard function calls to access it from a program. The TPENV unit fills this
TPENV provides another important function, useful to any program that provides
a DOS shell. This function allows the specification of a custom DOS prompt
within the shell. This prompt might show the name of the application, or a
reminder to "type EXIT to continue".
TPENV is designed to be used with Turbo Professional. If you don't have Turbo
Professional, you can delete the conditional compilation symbol UseTpro found
near the top of TPENV.PAS and TESTENV.PAS. Without Turbo Professional, you'll
be able to use all of TPENV's functions except for the special DOS shell.
TESTENV is a small program that demonstrates TPENV. Compile it to an EXE file,
and run it from the DOS command line. If you have Turbo Professional, it will
first conduct you to a DOS shell with a customized prompt. Fiddle around in
the shell, and then enter EXIT to return to the test program. Next, it will
show how you can modify the DOS master environment from within a program. Be
careful: any changes you make to the DOS environment will remain in force when
you quit the program.
TPENV interfaces about a dozen routines to manipulate the environment. Almost
all of these complement the routines found in Turbo Pascal 5's DOS unit, and
all of them do something that TP4's DOS unit doesn't. Here's a rundown of the
data types and procedures in TPENV:
EnvSeg : Word;
EnvLen : Word;
EnvPtr : Pointer;
This type is TPENV's way of packaging information about the environment.
You'll pass a parameter of this type to almost all of TPENV's routines. EnvSeg
is the segment address of the environment. At this address starts a list of
null-terminated strings that may extend for up to 32K characters. EnvLen is
the maximum usable length of that environment (not the amount currently in
use). EnvPtr is normally nil. It is used only when you allocate new
environment space from the Turbo Pascal heap, and even then you won't want to
refer to the EnvPtr field directly.
If an error occurs in one of TPENV's routines, the EnvSeg field will remain
at zero. You shouldn't continue processing with an environment record if
EnvSeg is zero.
ShellUserProc : Pointer = nil;
This constant is used only when you call the ShellWithPrompt function. It
contains the address of a user routine passed to the (Turbo Professional)
ExecDos routine (from the TPDOS unit). You'll probably want to leave it nil,
but the constant is available should you wish to take advantage of this
powerful ExecDos feature.
procedure MasterEnv(var Env : EnvRec);
Returns a record for the master system environment. Changes to this
environment are retained after the current program exits. Finding the master
environment is a little tricky, and if for some reason the method doesn't
work on your system, the EnvSeg field of the returned environment record
will be set to zero. The master environment for the system is typically
larger than that for the current program -- DOS copies only the portion of
the master environment that is actually in use when it runs each program.
procedure CurrentEnv(var Env : EnvRec);
Returns a record for the current program's environment. There isn't much
space left to add to this environment (see above), and any changes made to
it are lost when the current program ends. On the plus side, under DOS 3.0
or later, there is an additional string at the end of this environment which
specifies the complete pathname of the current program. TPENV offers a
special routine to return this pathname: see the ProgramStr function.
procedure NewEnv(var Env : EnvRec; Size : Word);
Allocates space for a new environment, from the Pascal heap. The most likely
use for this routine will be in a program that spawns other programs and
needs to pass a lot of environment information to them. Size specifies the
number of bytes to reserve for the new environment. NewEnv actually
allocates 31 bytes more than you request, to assure that paragraph
alignment is possible and to create a fake DOS memory control block which
keeps other programs and routines happy. If there isn't sufficient heap
space to allocate the new environment, NewEnv returns the EnvSeg field of
Env set to zero.
After a call to this routine, the new environment is totally filled with
nulls. Use the CopyEnv routine to copy from another environment to
initialize the new one.
procedure DisposeEnv(var Env : EnvRec);
Deallocates heap space for an environment previously allocated with NewEnv.
Calling DisposeEnv with the master or current environment record as a
parameter does nothing.
procedure SetCurrentEnv(Env : EnvRec);
Sets the environment of the current program to a different one, the one
specified by the Env parameter. You'll want to do this after calling NewEnv
and initializing the new environment, but before spawning a child process.
DOS copies the current environment to the child process. To keep from
messing up DOS's own memory allocation, you should always restore the
current environment to the one DOS allocated before quitting a program. See
the calls to SetCurrentEnv in ShellWithPrompt for an example.
procedure CopyEnv(Src, Dest : EnvRec);
Copies one environment to another. If the Dest environment is smaller than
the Src, CopyEnv copies what it can and truncates the last element wherever
it must. The copy never includes the pathname information that DOS 3.0+
tacks at the end of the normal environment. If this information is
needed, you can usually use the SetProgramStr function to copy it. See
ShellWithPrompt for an example of how to do this.
function EnvFree(Env : EnvRec) : Word;
Returns the number of bytes unused in the specified environment. You may
want to check this value before adding a new string to the environment,
although SetEnvStr checks as well.
function GetEnvStr(Env : EnvRec; Search : string) : string;
Returns the value of a particular environment string. For example, to check
the value of the COMSPEC environment setting in the master environment, you
would code a sequence like the following:
E : EnvRec;
WriteLn('Master setting for COMSPEC is ', GetEnvStr(E, 'COMSPEC'));
The search string may end with '=' if desired, but GetEnvStr will append an
equal sign if needed. Searching is not case sensitive. White space in the
search string is important and should generally be avoided. If GetEnvStr
finds no matching environment string, it returns an empty string.
function SetEnvStr(Env : EnvRec; Search, Value : string) : Boolean;
Sets the value of an environment string. Note that you can set the value in
the master or current environment, depending on how the Env parameter was
initialized. Search specifies the name of the environment string to change,
for example, 'COMSPEC'. Value specifies its new value. If Value is the empty
string, the entire item is removed from the environment. New values are
always added to the end of the environment, after first removing any
replaced value from the middle. If there is insufficient space for the new
environment value, SetEnvStr returns False, otherwise true. See TESTENV.PAS
for an example of using SetEnvStr.
This routine has one side effect. If the environment to be changed is the
current environment, SetEnvStr wipes out the program path name stored beyond
the end of the environment under DOS 3.0 and later. If you need to access
this pathname, be sure to do so (via the ProgramStr function) before calling
procedure DumpEnv(Env : EnvRec);
Parses and writes each element of the environment to the output device. The
listing is terminated with the number of unused bytes in the environment.
function ProgramStr : string;
Returns the complete pathname of the current program, if DOS 3.0 or later is
installed. Otherwise returns the empty string. Under Turbo Pascal 5, the
same result may be obtained by using the expression ParamStr(0).
function SetProgramStr(Env : EnvRec; Path : string) : Boolean;
Provides a method to set the program path name, normally available under DOS
3.0 or later. Path is appended to the specified environment just like DOS
would do it. If insufficient space remains, SetProgramStr does nothing and
function ShellWithPrompt(Prompt : string) : Integer;
Starts a DOS shell with the prompt set to the specified value. The user can
execute DOS commands until EXIT is entered, and then the calling program
continues. This routine depends on the ExecDos routine from Turbo
Professional for the mechanics of the shell. If you don't have Turbo
Professional, you could modify the routine to use Turbo Pascal's Exec
The Prompt string may specify any valid DOS prompt, including the
metacommands such as $p$g, and ANSI escape sequences if ANSI is installed.
The prompt totally replaces the existing prompt until the shell returns.
ShellWithPrompt allocates heap space for a new environment including the
specified Prompt. Heap space is allocated even if the prompt would fit in
the existing environment. The new environment is a copy of the current one,
with the PROMPT entry changed.
ShellWithPrompt returns a status value in the function result. The value
will be zero for a successful exec. Positive values are interpreted as
DOS error codes. Negative values are error codes specific to ExecDos and
ShellWithPrompt. See the Turbo Professional manual for a listing of the
error codes -1..-4. ShellWithPrompt adds the following codes:
-5 Can't read current environment
-6 Insufficient heap space for new environment
-7 Space calculation error (shouldn't happen)