First steps towards system programming under MS-DOS 7/Internal commands

Chapter 3 Internal commands

Internal commands are those executed by command interpreter itself. Contrary to other utilities which are to be searched for and read from their media, the interpreter is permanently present in memory, and therefore internal commands are executed much faster. Since internal commands are not to be searched for, the path for internal commands shouldn't be specified. One more common property of all internal commands is that they do not return an errorlevel code.

This chapter presents internal commands of Microsoft's proprietary command interpreter COMMAND.COM (file size 93812 bytes, file date 12.06.1996). Localized versions of this interpreter usually are slightly larger and have somewhat later date, but nevertheless execute the same set of internal commands. Among the described internal commands are those intended for batch files only (3.02, 3.14, 3.21, 3.27).

The COMMAND.COM interpreter provides a short help for its internal commands. In order to display help text you have to type the command's name, followed by a space and the  parameter, and then press the ENTER key. But the provided short help is often found too short. This chapter presents a lot of clarifications which will help you to avoid common mistakes and to make internal commands usage much more effective.

3.01 BREAK — disk access intercept control
The BREAK command is similar to synonymous configuration command (see 4.02 for details). They both affect the same binary flag which controls checks of BREAK and CTRL-C keystrokes during disk access operations. This binary flag doesn't lose its state when current resident module of command interpreter finishes its job, and local environment becomes lost. Contrary to the IO.SYS loader (4.02), the COMMAND.COM interpreter shows current state of the mentioned binary flag in response to the BREAK command entered without parameters.

3.02 CALL – batch file execution with return
CALL is a command to execute one batch file (the secondary batch) from another batch file (the primary batch). Batch files are non-formatted textual command files, from which the COMMAND.COM interpreter accepts an extended set of commands. The CALL command is just one of those intended to be entered not from keyboard, but only from lines of batch files.

Each line in a batch file may include a name of an internal command, or a name of an external utility, or a name of another batch file as well. When command interpreter encounters a name of external utility, it transfers control to this utility, but takes control back after the utility finishes its job, and proceeds to the next line in the same batch file. However, batch files don't behave like ordinary utilities. Having found a name of a batch file (the secondary batch) in a line of another batch file (the primary batch), the COMMAND.COM interpreter begins execution of the secondary batch and doesn't return to the primary one. In order to enable a return to execution of the primary batch file, the secondary one should be launched with CALL command, for example:

where :

In fact, the CALL command prevents closure of the primary batch file, keeps stored segment of the primary batch file, its dummy parameters and its file pointer position (as a target to return), lets command interpreter execute another (secondary) batch file specified after the CALL command in the same line, and then restores access to requisites of the primary batch file, thus enabling a return back to execution of the next operation in the primary batch file.

 The secondary batch file inherits not a copy of primary environment, but an access to the same primary environment. The values of variables which have been assigned during secondary batch file execution will become accessible after resumption of primary batch file execution. Execution of batch files with the CALL command is allowed to be nested more than twice. The CALL command enables to perform recursive calls, that is, a batch file may be called from a line inside the same batch file. But it's the user's responsibility to prevent uncontrolled deepening of recursion nesting level. If the secondary batch file is not found in the specified directory or in the current directory and throughout all the paths, defined by the PATH variable (2.02-02), then execution will be transferred to the next line of the primary batch file without any error message. Redirection signs (2.04-02 - 2.04-05) are not allowed in lines with the CALL command. The described CALL command, intended for COMMAND.COM interpreter, shouldn't be confused with synonymous assembler command (7.03-08) which is to be interpreted by DEBUG.EXE debugger. 
 * Notes

3.03 CD – change directory
When disk and path are not specified in command line, then MS-DOS implies presence of the addressed object in default (current) directory of the default (current) disk. Default disk assignment has been described in article 2.04-01. Default directory assignment is performed by CD command.

The CD command enables to change current directory on any disk (but not the current disk itself) according to a specified path. For example, command

will set current directory \DOS, if the current (default) disk is disk C:. CD command may be addressed to a disk which is not the current one, but the specified path is taken into account as a preset which will become the current (default) directory later, when the disk, specified in CD command, will be given status of the current disk (2.04-01).

The path in CD command may be expressed in any of its allowed forms (2.02-01). The final word in the path must be either a name of target directory or any combination of alias signs (2.02-03, 2.03-02). Such combinations enable to perform transition into the root directory, into parent directory , to climb two levels up along the directory structure and so on.

CD command without path specification, for example

shows a path to the current directory on the specified disk. When disk is not specified too, then the current disk is implied.

 CHDIR is another valid name for the same CD command.</li> <li id="note-3.03-2">The directory which is assigned current by CD command, can't be deleted with RD command (3.23), even if this directory doesn't belong to the current disk.</li> <li id="note-3.03-3">Preset paths to current directories for all logical disks are stored in CDS table structure (A.03-3). By default it is filled with paths to root directories.</li> </ol>
 * Notes

3.04 CHCP – change code page
Codepage is an array of characters and symbols used to display messages on the screen. When the CHCP command is used without following codepage number, it shows the number of the codepage which is currently active. Codepage changing function is usually disabled, Common practice is to load only one national codepage, because each national codepage contains not only national character set, but american english character set too. Switching between these character sets doesn't imply codepage change: it is performed inside any single national codepage.
 * unless 2 or more memory buffers for codepages have been prepared by DISPLAY.SYS driver (5.02-02),
 * unless these buffers are filled yet with different codepages by the  command (6.18-03),
 * and unless NLSFUNC.EXE driver (5.02-03) is loaded beforehand.

Loading several national codepages becomes needed when there is no one codepage, containing character sets for the languages which you intend to use. For example, if you prepared norwegian codepage 865 and russian codepage 866, then commands CHCP 865 and CHCP 866 will perform switching between these codepages.

<ol> <li id="note-3.04-1">Codepages may be changed with  command (6.18-03), which doesn't need to have NLSFUNC.EXE driver loaded.</li> <li id="note-3.04-2">The CHCP command can't cope with national codepages, loaded by non-Microsoft's drivers, for example by KEYRUS.COM (5.02-05).</li> <li id="note-3.04-3">If you use national version of an important utility or of a TSR shell (for example, Norton Commander with russian notation), then changing of the codepage will make this national notation totally non-readable! Only american english notation (characters 32 – 127, common for all codepages) will not be affected by codepage change.</li> </ol>
 * Notes

3.05 CLS – clear screen
The CLS command erases all contents of the current screen page in video card memory and also sets colors to default values, thus providing for white text display on a black background.

3.06 COPY – make copy of a file
The COPY command is used to copy one file or several files at once. It also enables to concatenate files and to combine copying with renaming. Here is an example of copying one file into another location :

where :

When the  parameter is the last item in command line, its action is quite different: it doesn't prevent from copying the file as a whole, but rather forces the COPY command to append the copy with end-of-file mark (1Ah), if the latter isn't there yet.

The first path, specified in the COPY command, is always interpreted as a source path, and the last - as the target path. Specifying more than two paths (or filenames) within one COPY command is regarded as an error, except specifying intermediate source(s), preceded by plus symbol ( + ) for copying with concatenation, for example :

where :

A filemask instead of the source filename is allowed, but such specifications should be used with great caution. Let's consider an example :

The COPY command checks the last word in the target path (to the right of the last backslash) on whether it is a name of an existing subdirectory or not. If subdirectory CONCAT.DAT doesn't exist, all copies of files, conforming to the given filemask, will be concatenated into a new file which will be created in the C:\DOS directory and will be given name Concat.dat. But if a subdirectory with CONCAT.DAT name exists yet, all files, conforming to the filemask, would not be concatenated, but rather would be copied one-by-one separately into this subdirectory. The latter example shows that the COPY command gives you an opportunity to obtain quite different results with just the same command line. This is why you must know exactly whether the last name you specify coincides or not with the name of an existing subdirectory.

For copying with concatenation the same file may be specified as a target and as the first source, and this file will be appended with contents of the following source file(s). Specifying a non-first source as the target is not allowed (contents of this source will be lost). When new name for the copy can't be misinterpreted, then you may specify the same path to the source and for the target or even omit both paths at all (current directory will be implied).

Copying of one file into itself is qualified as an error. Nevertheless the form of copying with concatenation allows to specify the same paths for a non-renamed copy and for the source. At the same time the name of the second file for concatenation may be omitted, for example :

This form of pseudocopying doesn't change file's contents, but is used in order to assign current date to the file or in order to delete the file if it is empty.<sup id="note-3.06-1-ref">&#91;Note 1&#93; <sup id="note-3.06-2-ref-1">&#91;Note 2&#93;

The reserved word CON (= console) in place of source in COPY command causes the command interpreter not to parse the following input lines as command lines, but to accept the following input as text :

This command enables to write text typed from keyboard into Remarks.txt file, created in C:\DOS directory, until F6-ENTER key combination is pressed to return to command line input (see 1.04 for more details).

Reserved words PRN (printer), LPT1–LPT4 (parallel ports), COM1–COM4 (serial ports) or NUL (virtual "black hole") may be used as targets for copying instead of a file. The command

turns the computer into a typewriter. Of course, the chosen target must be properly configured, and the connected terminal device must be able to respond to DOS's request. When the target is a device, then the  parameter (copy as ASCII text) is taken by default. Contrary to real terminal devices, virtual device NUL is always configured properly. Copying of a real file from physical media (for example, from a floppy) into virtual "black hole" NUL is sometimes used to test whether this file is not empty or whether it is readable.

<ol> <li id="note-3.06-1">^ Empty files (having zero length) are not copied.</li> <li id="note-3.06-2">^ If both target and source(s) are empty, target file is deleted.</li> <li id="note-3.06-3">The result of copying can't be redirected, redirection affects screen messages only.</li> <li id="note-3.06-4">Attributes of the source file are not copied.</li> <li id="note-3.06-5">The copy is always given the "A" attribute.</li> </ol>
 * Notes

3.07 CTTY – redirection of I/O links
The CTTY command changes settings for all the tree standard I/O channels: STDIN, STDOUT and STDERR. Initial default I/O settings are equivalent to those set by the CTTY CON command: all channels are linked with the CON device (console), that is, with the keyboard for input and with display for output. Instead of the console (CON) the CTTY command may accept one of following ports: COM1 (AUX), COM2, COM3, COM4, LPT1 (PRN), LPT2 and also virtual device NUL (for output into "nowhere"). CTTY is an archaic command. Its name (CTTY = Change TeleTYpewriter) reminds about the times when there were no displays, and the I/O consoles resembled old-fashioned teletypes.

Nowadays there are 2 reasons to use CTTY in batch files. The first is to prevent accidental interruption of execution; the second is to prevent indication of undesirable error messages sent via DOS's STDERR channel, which can't be redirected otherwise. In both cases the problem is solved by redirection into nowhere, represented by virtual NUL device: CTTY NUL precedes the group of commands to be protected, and later CTTY CON restores normal communication with keyboard and display. Inside the protected group of commands (between CTTY NUL and CTTY CON) both internal and interactive interruptions of execution are not allowed, because otherwise no message will be displayed, no input will be accepted, and PC may seem to get hanged. Reboot via CTRL-ALT-DELETE usually remains accessible, though.

CTTY command affects only implicit I/O settings, but it doesn't affect redirections, which are specified in command lines explicitly (2.04-02 – 2.04-05). For example, let's consider the following piece of a batch file:

Here a message from the COPY command will not reach the screen, even if it will be an error message. But the message "Press any key to exit" will be shown, because it is directed to the CON device explicitly. The next PAUSE command will work properly too, because its input is explicitly linked with keyboard. This form of CTTY usage needs some caution, but opens attractive opportunities to affect interaction with the user. An example of a batch file with this form of CTTY usage is shown in article 9.03-02.

<ol> <li id="note-3.07-1">Having been banned by CTTY NUL command, the STDERR (error) messages can't be redirected explicitly and are lost.</li> </ol>
 * Notes

3.08 DATE – date display and reset
In order to set a new date one has to specify this new date after the name of the DATE command in command line, for example :

When date is not specified, the current date will be shown, and then you will be offered to input a new date via keyboard.<sup id="note-3.08-2-ref-1">&#91;Note 2&#93; If you don't want to change the date, just respond to the offer by pressing the ENTER key.

Letters and other textual files are often appended with a line with data signature. For this purpose the DATE command should be used, for example, in the following way :

Here the first redirection automatically responds to the displayed offer and enables non-stop action, the second redirection  excludes undesirable output lines, and the third redirection  appends date signature to the specified file.

Of course, all conditions for performing redirections (2.04-05) and for finding files (Find.exe and the one to be appended) should be met.

<ol> <li id="note-3.08-1">Date and month data order is country-specific and should be set by COUNTRY command (4.05).</li> <li id="note-3.08-2">^ The offer for date change is supplemented with a prompt for a two-digit year data, but that's a bug : MS-DOS 7 demands 4-digit year data.</li> </ol>
 * Notes

3.09 DEL – file(s) deletion
The DEL (DELete) command doesn't physically erase files, but rather disables their entries in directory specification. The clusters, occupied by a file with invalid entry, are considered free and may be overwritten during following operations. But until these clusters are not overwritten, the deleted file may be restored, for example, by the UNDELETE.EXE utility from Norton Utilities release.

Here is an example of a command line with the DEL command:

where:

When a filemask (2.01-03) is specified instead of a filename, then all files conforming to this filemask will be deleted. But an attempt to delete all files in a directory by means of filemask  causes a stop and a query to the user on whether all files really should be deleted. Execution will be stopped even if the  parameter is not specified. The user has to respond to the query with Y (yes) or N (no) keystroke.

In batch files a non-stop operation is often desirable, without any prompts and queries. This may be achieved, for example, by execution of the  command within a   cycle :

This form of cycle always displays a list of deleted files (even despite redirection to ). You may avoid undesirable messages by implementing the  command in another way :

In the example above the  command provides an automatic response to the query, and the only reason for   condition is to avoid the "File not found" error message, when the specified directory  initially is empty.

<ol> <li id="note-3.09-1"> is another valid name for the same   command.</li> <li id="note-3.09-2">Files with attributes R (read-only), H (hidden), S (system) and directories can't be deleted with the DEL command. To delete directories the  command (3.23) should be used instead.</li> <li id="note-3.09-3">The  command (appended with a dot) is equivalent to  .</li> <li id="note-3.09-4">The  command (appended with a backslash) deletes in the root directory of the current disk all the files which are not protected by attributes.</li> </ol>
 * Notes

3.10 DIR – display of directory contents
In MS-DOS the  ( DIRectory ) command is the main instrument of exploring the directories' contents. Here is an example of a command line with the  command :

where :

The DIR command can be used to show data about a particular file or about all files conforming to a given filemask:

Absence of path specification in combination with  parameter in the latter example means that the DIR command in fact will perform a search for   files in the current directory and in all its subdirectories. If current directory is the root, the search will proceed throughout the current disk. If you are interested in finding a forgotten file only, the  parameter will make the result more concise and easy to apprehend.

Parameters for the DIR command may be preset in the DIRCMD environmental variable (for example, with command ), and then you will get the desired action of DIR command by default. If needed, you may later override any preset parameter by prefixing a hyphen "–" to it in command line (for example,  ).

When DIR command is executed with /A parameter, then the *.* filemask (all files) doesn't exclude directories. If you need to display files only, you ought to provide  parameter instead. This feature enables to explore whether a directory (or a disk) is empty or not. Consider, for example, the following lines from a batch file : The second line specifies parameters so that DIR command will display nothing, if the directory under test is empty. In third line the output of DIR command is redirected into file FOUND.LST. COPY command in the fourth line wouldn't copy an empty file and in this case issues a message "0 files copied". Having caught this message via redirection, the FIND.EXE utility sets errorlevel to zero. The rest two lines are used to sense errorlevel and to display appropriate conditional response.

When the DIR command is executed without  or   parameters, it may display filenames in two different ways, depending on operating system environment. Inside DOS window of WINDOWS operating system filenames are displayed "as they are", but in MS-DOS 7 environment names of files and their suffixes are displayed separately without a dot between them. This feature may be used as a simple test to determine current operating environment.

<ol> <li id="note-3.10-1">The  command shows all files in the root directory.</li> <li id="note-3.10-2">During the DIR command display scrolling of output lines on the screen may be stopped by pressing CTRL–S or BREAK keys; then after any other keystroke scrolling will be resumed.</li> </ol>
 * Notes

3.11 ECHO – string output via STDOUT
The words, specified in the same command line after the name of ECHO command are sent as a message into the STDOUT channel ; unless redirected, its default terminal point is the CON (console) device, displaying the message on the screen. Examples of string output with the ECHO command are shown, in particular, in previous article 3.10.

The message to display may be up to 123 characters long. Actual message length is limited by the line itself or by the first encountered redirection symbol (2.04-02 – 2.04-05). Message string may include ASCII service marks, shown in appendix A.02-8. But message string must not be empty or begin with words ON or OFF. These and several other exceptions are used to perform special functions:

ECHO flag is a local flag, maintaining its state until batch files share common environment, but this state is not inherited and is reset to default each time the command interpreter creates a derived (child) environment.

Command lines displayed in the default ECHO ON state are not the same as original command lines in batch files: in displayed lines all aliases are replaced with their values. This is helpful for debugging. But it is not needed, when file has proved to have no errors. Therefore almost each completed batch file starts with @ECHO OFF command. The "@" character, preceding the ECHO command, prevents display of this command itself.

3.12 EXIT – closure of current interpreter session
Command interpreter COMMAND.COM (6.04) is a resident program which arranges environment for execution of other programs. On the other hand, command interpreter itself may be launched just as an ordinary program in order to arrange a separate (local) environment, if it is required. In such cases several resident modules of command interpreter may coexist in memory simultaneously, but only one of them may be active – the one which is loaded the last. The EXIT command closes current session of the active resident module, releases the memory occupied by the module, and transfers control to the parent program (which has launched the mentioned resident module).

Just as current interpreter session is closed, its local environment with all values and variables becomes lost. At the same time the former environment of the parent program becomes accessible again, and execution of this program is automatically resumed. The very first resident module of command interpreter is launched by the IO.SYS loader with the SHELL command (4.26) in CONFIG.SYS file (9.01-01). This first resident module can't transfer control to its "parent", since the IO.SYS loader is not resident and has finished its job yet. If the first resident module of command interpreter were able to execute the EXIT command, then computer were get hanged. To prevent such outcome, the COMMAND.COM interpreter must be launched for the first time with the /P parameter (6.04), which disables EXIT command.

3.13 FOR – cycle operator
The FOR cycle operator arranges cyclic execution of other command(s). Assume, for example, that we need to display three short files: First.txt, Second.txt and Third.txt. Instead of sending these files to display with separate commands, the FOR operator enables to do the same in one line :

where :

Item(s) in parenthesis may be any word(s), including environmental variable substitutions (such as %TEMP%) and dummy parameter substitutions (2.03-03). Items in parenthesis may be separated by spaces, or by semicolons, or by commas. Note that paths in PATH variable value are separated by semicolons, hence the PATH's value will be disintegrated by the FOR cycle into a group of separate paths. This operation is often used in order to determine accessibility of a given file or in order to provide explicit path specification for it. The following piece of a batch file shows a typical path determination example : Here in the second line an auxiliary variable P is assigned an empty value, and in the third line — the path to the specified file, if the latter happens to be found. Note that the cycle variable name is prefixed with a percent character pair, as it must be in batch files. The last two lines check presence of auxiliary variable's value and issue a corresponding message according to the result.

Item(s) in parenthesis may include wildcards (2.01-03), but items with wildcards become interpreted as filenames which should be searched for in the current directory or according to the preceding path, if it is specified. Automatic search along all the paths in the PATH variable is not implied. Each of several items in parenthesis may include wildcards, for example :

Sometimes it is desirable to display separately each operation performed within FOR cycle, but not the cycle itself. This opportunity may be illustrated by the following modification of the preceding example : If the file specified in parenthesis with wildcards is not found, then corresponding operation is skipped without any error message. This is why the FOR cycle sometimes is used as a means to get rid of undesirable error messages (see 3.09 for an example). One more "side effect" of the FOR cycle is that it enables to parse a multi-word value of an environmental variable and to get rid of extra spaces which may precede or follow separate words within this value.

Inside parenthesis a string, including separation symbols, may be regarded as one item, if it is enclosed in double quotes (absence of the closing quote is qualified as an error). Double quotes themselves are not regarded as belonging to the item. This enables to specify several different commands in one line, for example :

There are sequences of operations which can't be performed in separate lines, but can be performed within the FOR cycle. Examples of such sequences are shown in line 46 of the batch file in article 9.03-02, and also in the 6th line of batch file in article 9.01-03.

Inside parenthesis the commands, enclosed in double quotes, may include substitutions of variable's values (as %W%), conditional commands, jump commands and redirections (2.04-02 - 2.04-05). When a jump to a label is performed from within the FOR cycle, the next operations (placed to the right, if such exist) will be skipped. Redirections inside the FOR cycle spread their action on all following commands. For example, in a cycle

the words "2nd line" will not be shown on the screen, but rather will be appended to the Q.txt file. Redirection for the following operation(s) can be changed, but it must be specified explicitly.

The ability of FOR cycle to take away enclosing double quotes from its arguments is essential not only for execution of commands, but also for displaying messages, protected from parsing by double quotes.

Nested FOR cycles are not allowed, but an internal FOR cycle may be executed by a separate resident module of command interpreter (COMMAND.COM), itself launched within an external FOR cycle specified in the same command line. If inside a batch file the FOR cycle is used to execute another (secondary) batch file, this secondary batch file may contain its own internal FOR cycles.

<ol> <li id="note-3.13-1">The name of the cycle variable must be chosen so as to prevent interference with any of currently used other variables.</li> <li id="note-3.13-2">Inside parenthesis the forward slash ( / ) is regarded as separator, but any single item preceded by the forward slash will be appended to this slash and converted to the upper case (in earlier DOS versions, slash acts otherwise).</li> <li id="note-3.13-3">Attempts to redirect all messages from FOR cycle affect only the first operation within this cycle. If the following operations have no explicit redirections, they will be subjected to default settings.</li> <li id="note-3.13-4">When interpreter COMMAND.COM is explicitly launched from command line in order to execute a FOR cycle, the cycle variable must be preceded by double percent signs, just as in batch files.</li> </ol>
 * Notes

3.14 GOTO – jump to a label
The GOTO command performs a jump within batch file to a label which must be specified in any line of the same batch file. A line with label begins with a colon, and after the colon an arbitrary label's name follows. The same name must be specified after GOTO command. When label's name is long, its first 8 characters only are taken into account. Synonymous labels in one batch file are not allowed. If, for example, there is a label  in some line of a batch file, then a jump to this label is performed by command

The GOTO command may be preceded in the same line by conditional operator IF (3.15). A lot of jump examples, both conditional and unconditional, can be found in articles 9.03-02, 9.09-02.

<ol> <li id="note-3.14-1">Label name after the GOTO command can be obtained by substitution for a variable's name (%VAR%, for example).</li> <li id="note-3.14-2">A value of dummy parameter (%1, %2..) cannot be used after the GOTO command as name of a label, but it may constitute a part of this name after any preceding letter(s).</li> <li id="note-3.14-3">The GOTO command doesn't affect errorlevel, thus giving an opportunity to continue errorlevel checks after the jump.</li> </ol>
 * Notes

3.15 IF – condition operator
Condition operator enables to perform three types of condition checks : existence check, equality check and errorlevel check.

Command line with conditional execution of any operation must commence with conditional operator IF, followed by condition type definition, condition specification and full specification of the command which should be executed if the condition is met.

Several condition operators with separate condition definitions and specifications may be written sequentially in one line, and then logical operation AND is applied implicitly to results of separate condition checks. Examples of combining several condition checks in one line are shown in articles 3.15-03, 9.03-01, 9.09-02. Peculiar composition of command line for each type of condition checks is described below in detail.

3.15-01 Existence condition check
Existence condition check, performed by IF EXIST command, can be applied to files, directories and logical devices. Inversion of existence condition – absence condition check – is performed by IF NOT EXIST command. Here are two examples of existence check usage : where :

Given examples enable to execute a specified utility (FORMAT.COM), when it is found in its proper place, or to have an intelligible message displayed, when this utility isn't found.

Names of logical devices are reserved words (2.01-01), assigned by DOS's core or by drivers during loading procedure. By existence check, applied to a logical device name, one can clear up whether a particular driver is loaded. Full list of logical devices in your computer is shown by the MEM.EXE utility being launched with /D parameter (6.17). For example, the EMM386.EXE (5.04-02) driver reserves logical device name EMMXXXX0. Hence the loading check for this driver can be done with the following line:

When you use a filemask with wildcards instead of utility name to be searched for, it will be referred to conforming files only, but not to directories. Existence condition with filemask *.* is true, when there is at least one file (or more, example in 3.09). In order to check existence of a directory you should append the directory name with a name of virtual file NUL:

However, the shown check for existence of a directory may fail on CD-ROMs because of peculiarity of their file system (ISO 9660).

It is often important to provide non-stop execution of batch files. The existence check provides non-stop execution on accessible media only: the file or directory may not exist, but disk must exist (must be inserted) and must be formatted with a file system accessible for MS-DOS 7 (FAT12, FAT16, FAT32) or accessible by means of installed drivers. When it is not known whether the media is accessible, a non-stop execution of the existence check still may be performed, but it needs special measures to prevent critical error handler calls (8.02-84) and to avoid appearance of undesirable messages (example in 9.03-02).

3.15-02 Equality condition check
Equality condition check is applied to two words, separated by double equality symbol. Since there is no sense in comparing a-priori known words, equality condition implies using aliases which may be dummy parameter(s) or variable's value(s) (2.03-03). Wildcard symbols ( and  ) in words to compare are allowed, but these are interpreted as ordinary symbols and are not expanded as wildcards. Contrary to ordinary DOS practice, upper and lower case letters in words to compare are NOT regarded as equal. Here are two examples of equality check usage in batch files : where :

Of course, any one of the words to compare may be specified directly, without aliases. Each of the words to compare may combine one or more aliases with directly specified part(s). But words to compare are not allowed to be empty: this is regarded as syntax error. Since any batch file may be executed without parameters, it must be prepared to the case when its dummy parameter ( in the example above or any other) becomes empty. The simplest way to solve the problem is to append any certain symbol (for example, a dot) to both left and right parts of the equation : These equality checks do the same as in the previous example, but are immune against the empty value of the aliases. The same principle is used to compose a check on whether the value of a variable (or of a dummy parameter as well) is empty :

Special care should be taken when the value of a variable may include spaces. The word to the right of the double equality symbol doesn't allow space(s) in its value. If the value of the variable CASH (in the example above) includes spaces, it will be interpreted as syntax error. But the word to the left of double equality symbol is allowed to have spaces inside. When this word consists of several items, separated by spaces, only the first (leftmost) item will be taken into account. This is illustrated by the following three examples (all three are valid): In all of these three examples the presence of the  and   items is ignored.

3.15-03 Errorlevel condition check
When execution of any utility in DOS is about to terminate, it may leave errorlevel code, a message to the algorithms that follow. Errorlevel informs whether the terminated execution has been successful or not, and if not, then what kind of obstacle has been encountered. Errorlevel is a 8-bit binary code in DOS's swappable data area (offset 14h in A.01-03), but it is presented as decimal number from 0 to 255 (without sign). Errorlevel 0 means successful termination, other errorlevel values usually mean different kinds of errors, interpreted specifically for each utility.

Errorlevel condition is identified by presence of the word ERRORLEVEL. It gives an opportunity to check whether the errorlevel code is equal or greater than a specified decimal number, for example : The check in the first line of the example above returns TRUE for all errorlevel values from 1 to 255, that is, for all possible unsuccessful outcomes. The check in the second line includes reserved word NOT and this is why acts as logical inversion, returning TRUE for errorlevels lower than 1, that is, for a single value 0 which means successful termination.

When you need to execute a separate procedure for a single type of erroneous outcome, you may concatenate errorlevel checks. Suppose, for example, that in the case of errorlevel 15 you need to perform a jump to label ERROR15. This may be achieved by the following command line :

The first check in the line above returns TRUE for all errorlevels from 0 to 15, and the second, for all errorlevels from 15 to 255. Errorlevel 15 is then the single errorlevel value which enables the following GOTO command.

<ol> <li id="note-3.15-1">Non-zero errorlevel code is used by some utilities to indicate different circumstances of normal (not erroneous) outcome.</li> <li id="note-3.15-2">All internal commands (3.01 - 3.34) don't return and don't change errorlevel code.</li> <li id="note-3.15-3">Mixed successive concatenation of several existence checks, equality checks, and errorlevel checks in one line is allowed in the same way as that shown above for two errorlevel checks.</li> </ol>
 * Notes

3.16 LFNFOR – long filenames display mode
LFNFOR is an undocumented local switch which may be set ON (LFNFOR ON) or OFF (LFNFOR OFF). Being used without parameters, LFNFOR command shows the state of this switch. Its default state is OFF. Under "bare" MS-DOS 7 the state of LFNFOR is ignored, but inside DOS box under Windows OS switching LFNFOR ON enables non-truncated treatment of long file names by the FOR command (3.13), for example, by

When LFNFOR is switched OFF, the FOR command truncates long file names to 8 characters, just as it always does in MS-DOS 7.

3.17 LH – load beyond conventional memory
The LH command (LH = Load High) loads drivers and TSR utilities beyond the 640 kb boundary of conventional memory in computers having the 80386 or higher processor. Access beyond the 640 kb boundary must be enabled in advance by command  (4.08) in CONFIG.SYS file and by loading memory managers: the HIMEM.SYS driver (5.04-01) and then either EMM386.EXE (5.04-02) or UMBPCI.SYS (5.04-04) driver. In both cases access to the TSR modules, loaded by the LH command, will be performed via the UMB region (640–1024 kb) of address space. When there is no more free space in UMB region, the LH command issues no error message and continues to load drivers and TSR utilities into conventional memory below 640 kb.

LH acts similar to the INSTALLHIGH command (4.16); the main difference is that INSTALLHIGH command is performed by the IO.SYS loader and can't take part in memory optimization procedure (5.04-03). The LH command is performed by COMMAND.COM interpreter from ordinary command line, or (preferably) from a line in AUTOEXEC.BAT file. Here is an example of a line from AUTOEXEC.BAT file, in which the LH command is used to load MSCDEX.EXE driver :

The name of the driver is preceded by a path which may take any of its allowed forms (2.02-01). If the path is omitted, the driver will be searched for in the current directory and throughout all the paths, specified in PATH variable’s value (2.02-02). All items following the driver's name are not identified by LH command, but rather are transferred to the driver as its specific parameters.

Between the name of LH command and specification of the software to be loaded, there may be an optional  parameter which gives an opportunity to point out a particular part of USB memory region which should be devoted for access to each TSR module (see also 4.07). In the example above this parameter looks as, where   means addressing via the first part of UMB region, and the number 23680 is the size of space (in bytes) required for TSR module of MSCDEX.EXE driver.

Size specification after the  parameter is optional, but when the size is specified, the LH command can accept one more parameter , for example :

The  parameter means that allocated UMB block should be truncated to the specified size. This results in the most efficient usage of address space, but doesn't guarantee from a crash, if size specification is not quite correct. It is not recommended to use the  parameter apart from memory optimization procedure, performed by memory optimization utility MEMMAKER.EXE (5.04-03). During this procedure the  and   parameters together with exact size specification will be automatically inserted in all those lines of AUTOEXEC.BAT file with LH command.

<ol> <li id="note-3.17-1">If access beyond conventional memory is opened by UMBPCI.SYS driver (5.04-04), then LH command loads TSR modules into UMB memory region (640–1024 kb). But EMM386.EXE driver (5.04-02) acts otherwise: it adjusts processor's address translation table (TLB) so that access to memory beyond 1088 kb is performed via the same UMB region of address space. This is why in the latter case the same LH command physically loads TSR modules not into the UMB region, but elsewhere beyond 1088 kb.</li> </ol>
 * Notes

3.18 LOCK – forbid concurrent access
Requests of various programs for disk access are controlled by MS-DOS 7 in order to provide proper order of access and effective buffering. Programs which require direct access to a disk, must coordinate their operations with MS-DOS 7 by means of the INT 13\AH=45h interrupt (8.01-58). But some programs don't do that, for example, the program for recovering deleted files UNDELETE.EXE from MS-DOS6.22 release. In order to permit such programs to do their job the COMMAND.COM interpreter in MS-DOS 7 provides the LOCK command. It gives exclusive rights to access the requested disk for the program that will be launched next.

Arguments for the LOCK command are one or more letter-names of the disks which should acquire exclusive treatment. During execution of LOCK command you will be asked for confirmation (Y or N) from keyboard. In order to avoid stops for confirmation in batch files you have to prepare a response in advance, for example

The result of the shown command line will be excusive non-interrupted access to disks C: and D: for the program which will be launched next. When this program terminates, the locked state of disk(s) should be turned off by UNLOCK command (3.31). Since direct access operations may be nested, up to 256 lock levels are allowed. Of course, each involved program must be supported by proper sequence of LOCK and UNLOCK commands.

3.19 MD – make directory
The MD command enables to create a new directory or subdirectory, for example :

where :

The unique new name is a required argument, but the preceding path is optional. When it is omitted, new (sub)directory will be created in the current directory of the current disk.

<ol> <li id="note-3.19-1">MKDIR is another valid name for the same MD command.</li> </ol>
 * Notes

3.20 PATH – search path(s) specification
The PATH command defines the default paths for searching programs that have no prescribed path and are not present in the current directory. The paths, specified by PATH command, constitute the value of synonymous environmental variable PATH. Its value may be defined by SET command (3.26) as well. But there is an important difference : unlike SET command, PATH command automatically converts all the characters in the specified path(s) into upper case (otherwise search procedure may go wrong). The PATH command must be followed by one or more existing paths, separated by semicolon(s), for example :

The ability of PATH command to convert arbitrary word(s) into upper case is sometimes used in order to avoid ambiguities further in course of case-sensitive equality check.

<ol> <li id="note-3.20-1">Within a string of path specifications there must be no spaces on both sides of each semicolon separator.</li> <li id="note-3.20-2">There must be no semicolon at the end of a string of path specifications.</li> <li id="note-3.20-3">The PATH command with no following arguments just displays the defined paths and leaves them unchanged.</li> <li id="note-3.20-4">The PATH ; command (followed by one semicolon only) deletes all previously defined paths.</li> <li id="note-3.20-5">The name of PATH command may be separated from the following string of path specifications by either a space or by equality sign ( = ) as well.</li> </ol>
 * Notes

3.21 PAUSE – temporary stop
The PAUSE command, being encountered in a line of a batch file, stops execution of this batch file and displays message "Press any key to continue...". This message is not quite true, because CTRL-C, CTRL-BREAK and ALT-03 keystroke combinations terminate execution, enabling to bypass all the rest lines of batch file (this action does not depend on the BREAK status). When PAUSE's message is not desirable, it may be redirected :

PAUSE command may be followed in the same line by a commentary string, just like the REM command. This commentary will not be displayed unless the ECHO flag (3.11) is set ON.

When default communication with console is halted by the "CTTY NUL" command (3.07), then PAUSE command must be given explicit input redirection :

In batch files redirection of the 03h symbol (shown as ©, see A.02-8) to PAUSE command provides the shortest way to quit execution of the batch file at once, without any pause :

Symbol 03h may be inserted into command line with ALT-03 keys, the digits should be entered via numeric keypad while the ALT key is kept pressed. But you shouldn't dare to disable such line by a preceding REM command (3.24): the ECHO command only will be disabled, redirected symbol wouldn't be received by PAUSE command, and the computer will hang.

3.22 PROMPT – prompt specification
The PROMPT command redefines the value of synonymous environmental variable PROMPT, which specifies the form of DOS's command prompt. Usually the PROMPT command is written in a line of AUTOEXEC.BAT file, but it also may be entered from an ordinary command line. The name PROMPT should be followed by the suggested prompt text. In this text pairs of characters, beginning with a dollar symbol ( $ ), are interpreted in a special way and are substituted with other data that can't be written into prompt text directly. Here is a table of correspondence between character pairs and the substituting data :

The PROMPT command without arguments deletes the variable PROMPT, and then DOS's prompt would present current disk’s letter-name appended with right arrow sign ( > ), the same prompt as after command PROMPT $N$G. By default MS-DOS 7 assigns to the PROMPT variable another value, which corresponds to most common form of command prompt: full path to the current directory appended with right arrow sign.

The data displayed by prompt can be written into a file and then assigned as a value to an environmental variable. Consider the following example of batch file lines : The first line in the example above sets a complicated form of a prompt, and the second line writes this prompt into a new batch file RET.BAT. Obtained RET.BAT file's contents may look as follows : Note that prompt parameter " " has been transformed into " ", where " " is an example of current disk’s lettername followed by actual current path at the moment of batch line execution. If you execute the RET.BAT file with CALL command (3.02), then actual full path will become written into value of environmental variable RET. After that you can delete RET.BAT file and may use the RET variable whenever necessary in order to return to the former disk and directory : Another example of PROMPT command usage for obtaining current disk’s letter-name is shown in article 9.01-03. Current time, date and OS version number can be written into environmental variable(s) in a similar way.

3.23 RD – remove directory
The RD command (Remove Directory) enables to delete a directory, if the following conditions are met : Here is a RD command usage example :
 * the directory to be deleted is empty ;
 * the directory exists on a writable disk ;
 * the directory is not the root directory of a disk ;
 * the directory is not the current directory on its disk, even if the addressed disk is not the current disk.

where :

<ol> <li id="note-3.23-1">RMDIR is another valid name for the same RD command.</li> </ol>
 * Notes

3.24 REM – remark line
The REM command (REMark) forces COMMAND.COM interpreter to ignore all the following character(s) in the same command line up to any nearest sign of redirection (2.04-02 – 2.04-05) or up to the end of the line. The main mission of the REM command is to provide an opportunity to insert comment lines in batch files. Comments may be up to 123 characters long in one line. The REM command is used for commentaries that shouldn’t be displayed during normal execution of a batch file, but rather are to be displayed only for tracing with the ECHO flag (3.11).

The REM command is sometimes used to disable an executable line in a batch file, but it can't disable redirection. Double colon " " (2.04-01) is more suitable for this purpose. The other mission of REM is an "empty" command, accepted as valid and formally executed, but which does nothing (see VCEDIT.EXT in 6.25-03 for an example).

Since the REM command sends no output into STDOUT channel, redirection

is used to create an empty file of the specified name. If a synonymous file already exists, it will be overwritten and will become empty. Overwriting of a real file with a file of zero length erases address of its first cluster in directory specification. Therefore, files overwritten by a file of zero length cannot be restored by UNDELETE.EXE or by other similar utilities.

<ol> <li id="note-3.24-1">REM command shouldn't be used to disable command lines with intermediate redirection (2.04-05). The REM command disables only the first command in such line, its output is not sent, and command in the rest part of command line never gets the awaited data. Therefore computer may get hanged (example in article 3.21).</li> <li id="note-3.24-2">Inside "DOS box" of Windows OS empty redirections are not performed, so there the REM command can't be used to create a file of zero length.</li> </ol>
 * Notes

3.25 REN – rename a file
The REN command (REName) enables to rename one file or several files at once if their names conform to a certain mask. Here is an example of renaming one file with REM command :

where :

Specifying wildcards within the first (old) name only is allowed, but often leads to an error: attempt to create several synonymous files in one directory. Therefore it is recommended to specify wildcards in the same positions in both old and new filenames, so as to retain unique features of each filename. Characters hidden under wildcards will not be changed. Suppose a group of files Part_01.txt – Part_12.txt to be renamed as Chap_01.txt – Chap_12.txt. This operation is performed with one command :

<ol> <li id="note-3.25-1">Directories and files with H (hidden) attribute can't be renamed by the REN command.</li> <li id="note-3.25-2">Attributes of the renamed file(s) remain unchanged.</li> </ol>
 * Notes

3.26 SET – value assignment to a variable
When SET command is specified without parameters, it displays all variables of the current environment together with their values. But if name of the SET command is followed by any word, this word is interpreted as a name of an environmental variable which should be assigned a new value, for example:

where :

<ol> <li id="note-3.26-1">Any space to the right of the equation sign between valid characters, preceding or following valid characters (up to the end line mark) will be included in variable's value.</li> <li id="note-3.26-2">If a part to the right of the equation sign is empty, then specified variable will be deleted (will cease to exist).</li> <li id="note-3.26-3">The SET command is able to expand environmental space, when it is not enough to accommodate the new value of a variable.</li> <li id="note-3.26-4">In batch files the value to the right of the equation sign may include substitutions for other variable's names (for example, ) and for dummy parameters (2.03-03). All such aliases will be replaced with their values before defining the new variable.</li> <li id="note-3.26-5">A synonymous command SET (4.25) in lines of CONFIG.SYS file is interpreted by IO.SYS loader. The latter doesn't perform substitutions and redirections, but thus it gives an opportunity to include corresponding symbols in variable's value(s).</li> </ol>
 * Notes

3.27 SHIFT – dummy parameter’s order shift
The SHIFT command shifts by &minus;1 (minus one) the numeric order of dummy parameters (2.03-03) in a batch file, so that former %0 is lost, former %1 becomes %0, former %2 becomes %1, and so on. It's important to notice that the dummy parameter, which becomes the 9th, previously was the 10th and couldn't be accessed. Thus the SHIFT command gives an opportunity to specify more than 9 dummy parameters for a batch file and to access them sequentially, shifting their numeration from one iteration to each next. An example of such numeration shift is presented by a subroutine in lines 29–38 of DISK.BAT file in article 9.03-02. When the shifted address order comes to the end of parameter's sequence, the last dummy parameter becomes empty, and this is a sign to terminate execution of the whole cycle containing the SHIFT command.

3.28 TIME – time display and reset
In order to set a new time, one has to specify this new time after the name of the TIME command in command line, for example :

where the successive numbers mean hours, minutes, seconds, and hundredths of a second. Separation symbols within the shown time specification are colons and a comma, but that depends on what national conventions are set by the COUNTRY command (4.05).

When time is not specified, the current time will be shown, and then you will be offered to input a new time via keyboard. If you don't want to change time, just respond to the offer by pressing the ENTER key.

In order to append a textual file with a time signature, the TIME command should be used, for example, in the following way :

Here the first redirection automatically responds to the displayed offer and enables non-stop action, the second redirection  excludes undesirable output lines and the third redirection  appends time signature to the specified file. Of course, all conditions for performing redirections (2.04-05) and for finding files (FIND.EXE and the one to be appended) should be met.

3.29 TRUENAME – canonical form for path and name
Given a file's relative specification, TRUENAME returns its full name along with its absolute path, where, in addition, all letters are uppercased, forward slashes are converted to backslashes, asterisks (2.01-03) are converted into appropriate number of question marks, long names are truncated to 8 characters, long suffixes converted to 3 characters.

If the original specification points out a fake path arranged by utilities ASSIGN.COM, JOIN.EXE or SUBST.EXE, then the TRUENAME command returns the true path. When used without following specification, the TRUENAME command returns full path to the current directory, just as CD command (3.03).

<ol> <li id="note-3.29-1">The TRUENAME command does not display error messages.</li> <li id="note-3.29-2">The TRUENAME command cannot be applied to network paths unless a LAN driver is installed.</li> <li id="note-3.29-3">The action of TRUENAME command is based on INT 21\AH=60h (8.02-72).</li> </ol>
 * Notes

3.30 TYPE – read a file to STDOUT
The TYPE command reads contents of a specified file and sends it line-by-line into STDOUT channel, which has the CON device (display) as its default terminal point. Sending may be terminated by CTRL-C or CTRL-BREAK keystrokes, or suspended by pressing CTRL S or BREAK keys and then resumed by any other keystroke. Usage example :

where :

The output of the TYPE command may be redirected, for example, to the printer connected to LPT1 port :

The TYPE command is often used together with the MORE.COM viewer (6.19), which displays long STDOUT messages page-by-page.

3.31 UNLOCK – concurrent access permission
After termination of a program that has been given direct access to a disk with LOCK command (3.18), the original access state should be restored by the UNLOCK command, applied to the same disk, for example :

In fact, the UNLOCK command does not permit concurrent access, but rather decreases by 1 the count of nested ban levels, forbidding concurrent access. Thus a proper treatment of nested program calls is provided. But if the original ban level was 1, then UNLOCK command will reactivate a queue of requests for access to the disk. This is important in multitasking operating environment, for example in "DOS box" under Windows95/98 OS. If a disk originally is not locked, no action will be taken by the UNLOCK command. In any case no message will be displayed.

3.32 VER – operating system version display
In MS-DOS 7 and in MS-DOS 8 the VER command (VERsion) shows version number of the corresponding WINDOWS software release. Having been supplied with  parameter

The VER command appends its version message with a remark about whether the DOS's kernel is loaded into high memory area or not.

3.33 VERIFY – verification function control
VERIFY command, launched without parameters, indicates the state of verification function which defines whether or not each written file should be re-read and compared with its original. By default the verification function is turned OFF, and verification is not performed. You can change the state of verification function with VERIFY ON or VERIFY OFF commands (more about this in note 2 to 8.02-60).

<ol> <li id="note-3.33-1">High reliability of modern HDDs makes verification unnecessary, it leads to time loss and to excess disk wear. It is better to initialize verification by the  parameter of COPY command (3.06) for copying file(s) only to diskette(s).</li> <li id="note-3.33-2">The VERIFY function acts as a global switch: it doesn't loose its state when current resident module of command interpreter finishes its job and local environment becomes lost.</li> </ol>
 * Notes

3.34 VOL – disk’s label and serial number
Disk's label is a string of up to 11 characters long, chosen by the user. If the user wouldn't define label while formatting, disk will be given the NO NAME label. Later disk's label may be changed with the LABEL.EXE utility (6.16) or by means of some TSR shells (Norton Commander, Volkov Commander, etc.).

The serial number is an 8-digit hexadecimal identifier which is automatically assigned to a disk during formatting procedure. Diskettes may have no serial number, if their production technology employs formatting by magnetic contact copying. Contrary to this during ordinary copying procedures both label and serial number are inherited by diskette-copy from diskette-origin.

In order to display label and serial number of a particular disk, you have to specify its letter-name after the name of the VOL (= VOLume) command in the same command line, for example :

If disk’s letter-name is omitted, then volume label and serial number of the current disk will be displayed.