SUMMARY
MS-DOS versions 2.0 and later use an environment block. An
environment block is a concatenated set of null-terminated (ASCIIZ)
variable-length strings of the form:
These strings provide information such as the following:
- The current path used by COMMAND.COM to find executable files
- The location of COMMAND.COM itself
- The format of the MS-DOS prompt
The end of the set of strings is marked by a null string, that is, the
last string is followed by two null bytes.
A local environment block is associated with each program in memory
through a pointer contained at offset 2C hex in each program's PSP
(program segment prefix).
This article provides background information necessary when using the
ENVIRON statement in Microsoft Visual Basic for MS-DOS, version 1.0;
in Microsoft Quick Basic for MS-DOS, versions 4.0, 4.0b, and 4.5; in
Microsoft Basic Compiler for MS-DOS, versions 6.0 and 6.0b; and in
Microsoft Basic Professional Development System (PDS) for MS-DOS,
versions 7.0 and 7.1.
MORE INFORMATION
The system's master environment block is normally owned by the shell
COMMAND.COM. COMMAND.COM creates this set of environment strings in
memory from the contents of the AUTOEXEC.BAT file, using the SET,
PATH, and PROMPT commands. The initial size of COMMAND.COM's
environment block can be controlled by loading COMMAND.COM with the /E
parameter, using the SHELL directive in CONFIG.SYS. For example:
SHELL=COMMAND.COM /E:2048 /P
This line in CONFIG.SYS sets the initial size of COMMAND.COM's
environment to 2K. The maximum size the environment can be set to is
32K; the default size is 160 bytes. (The /P option prevents
COMMAND.COM from terminating, keeping it in memory until the system is
restarted.)
The SET command is used to display or change the COMMAND.COM
environment contents. SET with no parameters displays the list of all
the environment strings in the environment. A typical listing in the
AUTOEXEC.BAT file might show the following settings:
COMSPEC=C:\COMMAND.COM
PATH=C:\;C:\DOS;C:\WINDOWS
PROMPT=$P$G
TMP=C:\TEMP
The following is a dump of the environment segment containing the
previous environment example:
0 1 2 3 4 5 6 7 8 9 A B C D E F
0000 43 4F 4D 53 50 45 43 3D-43 3A 5C 43 4F 4D 4D 41
0010 4E 44 2E 43 4F 4D 00 50-41 54 48 3D 43 3A 5C 3B
0020 43 3A 5C 44 4F 53 3B 43-3A 5C 57 49 4E 44 4F 57
0030 53 00 50 52 4F 4D 50 54-3D 24 50 24 47 00 54 4D
0040 50 3D 43 3A 5C 54 45 4D 50 00 00 00 00 00 00 00
COMSPEC=C:\COMMA
ND.COM.PATH=C:\;
C:\DOS;C:\WINDOW
S.PROMPT=$P$G.TM
P=C:\TEMP.......
When a program is executed, such as when you start a .EXE, .COM, or
.BAT file by typing its name on the DOS command line, DOS sets aside a
256-byte block of memory for the program segment prefix (PSP). The PSP
contains various information that DOS uses to help run the program.
One part of this PSP contains the segment address of the local copy of
the master environment block.
Below is a diagram of the program segment prefix (PSP):
OFFSET DESCRIPTION
0000H ----------------------------------------------
| Int 20H |
0002H ----------------------------------------------
| Segment end of allocation block |
0004H ----------------------------------------------
| Reserved |
0005H ----------------------------------------------
| Long call to MS-DOS function dispatcher |
000AH ----------------------------------------------
| Previous contents of termination handler |
| interrupt vector (Int 22H) |
000EH ----------------------------------------------
| Previous contents of CTRL+C |
| interrupt vector (Int 23H) |
0012H ----------------------------------------------
| Previous contents of critical-error handler|
| interrupt vector (Int 24H) |
0016H ----------------------------------------------
| |
| Reserved |
| |
002CH ----------------------------------------------
|*** SEGMENT ADDRESS OF ENVIRONMENT BLOCK ***|
002EH ----------------------------------------------
| |
| Reserved |
| |
0050H ----------------------------------------------
| RETF instructions (INT 21H) |
0053H ----------------------------------------------
| Reserved |
005CH ----------------------------------------------
| Default file control block #1 |
| |
006CH ----------------------------------------------
| Default file control block #2 |
| (overlaid if FCB #1 opened) |
0080H ----------------------------------------------
| |
| Command tail and default |
| Disk Transfer Area (DTA) |
| |
00FFH ----------------------------------------------
MS-DOS always builds a program's PSP in memory just below the memory area
allocated to the program itself.
(More detailed information on the PSP can be found in the "MS-DOS
Encyclopedia" published by Microsoft Press.)
If a transient program starts another transient program, then MS-DOS DOES
NOT make a copy of the master environment table; MS-DOS makes a copy of
the environment table of the parent program that made the call.
Therefore, now there is a copy of a copy of the original table.
When the child program started by the parent program terminates, any
changes that were made to its local copy of the environment table are
lost. Likewise, when the parent program terminates and control is
returned to MS-DOS, its local copy of the master environment table is
lost.
Note that each copy of the environment table is exactly the size of
the original, with no space for additions. Thus, if a program tries to
add something to its environment table, an "Out of environment space"
error message will occur. The environment table cannot get any larger
that its original size. Therefore, before something can be added, one
of the other variables must be deleted or reduced in size.
The "Out of environment space" error can also occur if a TSR
(Terminate-and-Stay-Resident) utility is installed when you try to add
to the master environment table, or if adding to the master
environment table exceeds the size specified in the CONFIG.SYS file
with the /E parameter on the SHELL directive.
The master environment table cannot be affected by any child program.
For example, if you write a Basic program that alters the environment
table using the ENVIRON statement, the local copy of the environment
table is changed, not the original.
To increase the size of the local environment block so that additional
variables can be added, put a junk variable in the master environment
block to hold space, and then erase it from the local copy to allocate
space.
For example, with a Visual Basic for MS-DOS program:
- SET a large string in the MS-DOS environment table before running
Visual Basic for MS-DOS, or a compiled program:
C:\> SET JUNK=123456789012345678901234567890
- Use the ENVIRON statement in your program to set the large string
equal to null. This will eliminate the variable JUNK and its string
value from the local environment table:
ENVIRON "JUNK="
- Add a new environment variable and its value to the local
environment table:
ENVIRON "TEST=C:\MASM"
Note, environment variable names must be uppercase.
Remember that when this program terminates, the local environment
table will be lost and it will be as if no changes were made to the
environment.
How to Make Basic Change Environment After Exiting
To make the Basic program change the MS-DOS environment after ending, you
can perform the following steps using MS-DOS batch files:
- Invoke your Visual Basic for MS-DOS program from an MS-DOS batch file.
- At run time, your Visual Basic for MS-DOS program can create a text file
containing MS-DOS batch commands to SET environment variables.
- After the Visual Basic for MS-DOS program ends and returns control to
the batch file, the batch file can use the batch Call statement to
invoke the batch (text) file created by the Visual Basic for MS-DOS
program.