DOS Environment Table Description; Basic's ENVIRON Statement

ID: Q69846

The information in this article applies to:

Microsoft Visual Basic Standard and Professional Editions for MS-DOS, version 1.0
Microsoft QuickBASIC for MS-DOS, versions 4.0, 4.0b, 4.5
Microsoft BASIC Compiler, version 1.0
on the following platforms: MS-DOS
Microsoft Basic Professional Development System for MS-DOS, versions 7.0, 7.1

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:

variable=value

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.

REFERENCES

The information contained in this article was extracted from the following books from Microsoft Press:

"The MS-DOS Encyclopedia"

"The New Peter Norton Programmers Guide to the IBM PC & PS/2"

"Advanced MS-DOS Programming"

Additional query words: VBmsdos QuickBas BasicCom

Keywords :
Version : MS-DOS:1.0,4.0,4.0b,4.5,7.0,7.1; :1.0
Platform : MS-DOS
Issue type :