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:

CALL C:\DOS\VC4\Help.bat J 96

where :

C:\DOS\VC4\ – an example of a path to HELP.BAT file. If path is omitted, the file will be searched for inside current directory and then according to all path(s), specified by PATH variable.
Help.bat	–	an example of a name for the secondary batch file.
J 96	–	specific parameters to be transferred to HELP.BAT file (other batch files may need other parameters or may not need them at all).

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.

Notes

1. 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.
2. Execution of batch files with the CALL command is allowed to be nested more than twice.
3. 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.
4. 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.
5. Redirection signs (2.04-02 - 2.04-05) are not allowed in lines with the CALL command.
6. 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.

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

CD C:\DOS

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 (CD \), into parent directory (CD ..), to climb two levels up along the directory structure (CD ..\..) and so on.

CD command without path specification, for example

CD C:

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

Notes

1. CHDIR is another valid name for the same CD command.
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.
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.

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,

• 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 MODE.COM CON CP PREP command (6.18-03),
• and unless NLSFUNC.EXE driver (5.02-03) is loaded beforehand.

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.

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.

Notes

1. Codepages may be changed with MODE.COM CON CP SEL command (6.18-03), which doesn't need to have NLSFUNC.EXE driver loaded.
2. The CHCP command can't cope with national codepages, loaded by non-Microsoft's drivers, for example by KEYRUS.COM (5.02-05).
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.

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 :

COPY /A C:\DOS\MS7\Trial.txt A:\DOS /V /Y

where :

/A	–	indicates that the specified source file must be copied no further than the first end-of-file mark (1Ah). For copying only one file into a target file, the opposite /B parameter is taken instead by default. It forces to copy a file as a whole, ignoring end-of-file byte 1Ah which might play a quite different role inside executable files and in binary data files.
C:\DOS\MS7\ – is an example of a path to the source file. For allowable alternative forms of path specifications see 2.02-01 – 2.02-03. If path to the source file is not specified, this source will be searched for within the current directory only (paths inside the PATH variable are ignored by COPY command).
Trial.txt – an example of a name for the source file to be copied. If source file name has an extension, it must be specified. Source file may have "A" (Archive) and "R" (Read-only) attributes. Source files with "H" (Hidden) and "S" (System) attributes are not copied.
A:\DOS	–	an example of a path to the existing target directory, where the copy should be placed. But if the \DOS directory doesn't exist, DOS will be interpreted as a new name for the copy, and a copy named DOS will be created in the root directory of disk A:. If you don't intend to rename the copy, target path must differ from the source path. If the source is not in the current directory, target path may be omitted, and in this case the current directory will be implied as the target.
/V	–	an optional parameter, inducing verification of the copy. It makes copying more slow and is not needed, when the target media is a hard disk. But when the target media is a floppy, the /V parameter may be worth the delay.
/Y	–	an optional parameter, giving permission to overwrite any synonymous file in the target directory without prompt. The /Y parameter may be preset in the COPYCMD environment variable (by command SET COPYCMD= /Y ), and then you will not need to specify it in command line. This preset may be overridden with /–Y parameter in command line, when prompt is really needed.

When the /A 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 :

COPY /B T1.dat + T2.dat /A + Remark.txt C:\DOS

where :

/B	–	copying mode parameter, which precedes the first source name, retains its effect for all following source names until an opposite parameter specification is encountered (/A in this example). The latter spreads its effect for all remaining source names, if there are any. Since concatenation is applied mainly to non-executable files, the /A parameter is taken as default for copying with concatenation.
T1.dat, T2.dat, Remark.txt – these are three source files for copying with concatenation. Since the paths to the source files are omitted, all these files are implied to be present in the current directory. The following source file names, except the first, must be preceded by plus ( + ) sign of concatenation.
C:\DOS	–	is an example of a path to the target directory. When the target directory exists, the result of concatenation will be placed there, and it will inherit the name of the first source (T1.DAT). But if the C:\DOS directory doesn't exist, then the last name DOS will be interpreted as a new name for the combined file, and the result of concatenation named DOS will be written into the root directory of disk C:.

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

COPY /B T*.dat C:\DOS\Concat.dat

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 :

COPY /B \DOS\File.ext +,,\DOS

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.^{[Note 1][Note 2]}

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 :

COPY CON C:\DOS\Remarks.txt

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

COPY CON PRN

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 /A 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.

Notes

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

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:

@ctty nul
copy /B Trial.dat Suit.dat
echo Press any key to exit > con
pause < con
ctty con

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.

Notes

1. Having been banned by CTTY NUL command, the STDERR (error) messages can't be redirected explicitly and are lost.

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 :

DATE 11.07.2002

When date is not specified, the current date will be shown, and then you will be offered to input a new date via keyboard.^[Note 2] 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 :

ECHO= | DATE | Find.exe "Current" >> Anyfile.txt

Here the first redirection (ECHO= | DATE) automatically responds to the displayed offer and enables non-stop action, the second redirection (DATE | Find.exe) excludes undesirable output lines, and the third redirection (>> Anyfile.txt) 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.

Notes

1. Date and month data order is country-specific and should be set by COUNTRY command (4.05).
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.

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:

DEL D:\TEMP\Filename.ext /P

where:

D:\TEMP\	–	an example of disk and path specification for the directory, containing the file(s) to be deleted. If path is omitted, then current directory is implied.
Filename.ext – a name example of a file to be deleted;
/P	–	optional parameter, causing a prompt for confirmation before deletion of each file.

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 /P 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 DEL command within a FOR cycle :

FOR %%Z in (*.*) do DEL %%Z

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

ECHO Y | IF EXIST D:\TEMP\*.* DEL D:\TEMP\*.* > NUL

In the example above the ECHO Y command provides an automatic response to the query, and the only reason for IF EXIST condition is to avoid the "File not found" error message, when the specified directory (D:\TEMP\) initially is empty.

Notes

1. ERASE is another valid name for the same DEL command.
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 RD command (3.23) should be used instead.
3. The DEL . command (appended with a dot) is equivalent to DEL *.*.
4. The DEL \ command (appended with a backslash) deletes in the root directory of the current disk all the files which are not protected by attributes.

3.10 DIR – display of directory contents

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

DIR C:\DOS /P /A:HS /O:GN /S /L /V

where :

C:\DOS	–	an example of a path to the directory to explore. If not specified, current directory is implied.
/P	–	optional parameter causing a stop after each screenful of output data until any key is pressed by the user.
/A:HS	–	a parameter specifying permission to show the items with particular attributes: H (hidden), S (system), A (new or changed files, not saved in an archive yet), R (read-only), D (directories). Prefix "–" may be used to reverse the choice: –H (except hidden), –D (except directories), and so on. Parameter /A without following attributes forces to show all the items in the directory. When parameter /A is omitted, hidden and system files are not displayed.
/O:GN	–	specification of the sorting order for the displayed items: G – directories first, N – by name (the default), S – by size (smallest first), E – by extension, D – by date and time (earliest first), A – by last access date (earliest first). Prefix "–" may be used to reverse the order: –N – by name with inverse alphabetic order, –S – by size with largest the first, and so on.
/S	–	an optional parameter, forcing to show contents of subdirectories too.
/L	–	an optional parameter, forcing conversion of the shown filenames to lower case, otherwise these names will be shown just as they were originally specified.
/V	–	an optional parameter, causing display of supplementary data: attributes, time of the last access, allocated disk space, total disk space and its usage. Other parameters, having preference over /V, are : /W – show item names in 5 columns, /B – show item names in one column, without disk summary ; no time loss for preparing summary makes the DIR /B command much faster.

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

DIR *.txt /P /S /B

Absence of path specification in combination with /S parameter in the latter example means that the DIR command in fact will perform a search for *.txt 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 /B 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 SET DIRCMD= /P /S /B), 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, /–P ).

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 /A: –D 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 :

@echo off
set DIRCMD=/a /b
dir *.* > C:\Temp\Found.lst
copy C:\Temp\Found.lst NUL | Find.exe "0 file" > nul
if errorlevel 1 echo Current directory is NOT empty
if not errorlevel 1 echo Current directory is empty

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 /W or /B 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.

Notes

1. The DIR \ command shows all files in the root directory.
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.

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 ON – switches ON the ECHO flag, enabling to display batch file lines as they are executed (this is the default status).
ECHO OFF – switches the ECHO flag OFF (no lines display). Outside batch files this causes disappearance of command prompt.
ECHO	–	(without following message) shows current status of ECHO flag.
ECHO=	–	(appended with equals sign) – sends bytes 0Dh 0Ah via STDOUT channel, just as if the ENTER key were pressed (example in article 3.08). On the screen or in a file this causes insertion of an empty line.
ECHO+	–	sends bytes 0Dh 0Ah via STDOUT, but also sends words specified after plus sign, if there are any, including words ON and OFF. The ECHO command acts similarly, when it is appended with slash or dot

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 :

FOR %Z IN (First Second Third) DO TYPE %Z.txt

where :

%Z	–	an example of a name for cycle variable which is sequentially set equal to each of the items specified in parenthesis. Cycle variable name shouldn't commence with a digit. Usually it is a one-letter name, preceded by a percent symbol ( % ), when the cycle is executed from command line, or by double percent symbol (%%), when the cycle is executed from a batch file.
IN	–	a required reserved word, introducing the following list of variable's values, specified inside parenthesis.
DO	–	a required reserved word, introducing the following name of the command which is to be executed in the cycle as many times as many values are specified for the cycle variable. In each iteration a new value is substituted for the name of cycle variable.

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 :

@echo off
set P=
FOR %%Y IN (. %PATH%) DO if exist %%Y\Fc.exe set P=%%Y\Fc.exe
if %P%"==" echo Requested file hasn't been found!
if not %P%"==" echo Path to the requested file is %P%

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 (%%Y) 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 :

FOR %%X IN (A:\*.txt A:\*.doc) DO COPY /B %%X C:\DOS

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 :

ECHO ON
@FOR %%X IN (A:\*.txt A:\*.doc) DO COPY /B %%X C:\DOS
@ECHO OFF

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 :

FOR %%Z IN ("set E=%W%" "echo E is set" "goto L23") DO %%Z

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 (IF), jump commands (GOTO) 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

For %%Z in ("echo 1st line >> Q.txt" "echo 2nd line") do %%Z

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.

Notes

1. The name of the cycle variable must be chosen so as to prevent interference with any of currently used other variables.
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).
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.
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.

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 :L36 in some line of a batch file, then a jump to this label is performed by command

GOTO L36

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.

Notes

1. Label name after the GOTO command can be obtained by substitution for a variable's name (%VAR%, for example).
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).
3. The GOTO command doesn't affect errorlevel, thus giving an opportunity to continue errorlevel checks after the jump.

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 :

IF EXIST C:\DOS\Format.com C:\DOS\Format.com A: /S
IF NOT EXIST C:\DOS\Format.com ECHO Format.com isn't found!

where :

EXIST	–	a reserved word, defining type of check and forcing to interpret the following element as a name or a mask (may be with path) of the object to be searched for.
C:\DOS\Format.com – an example of a filename to be searched for; preceded by a path. This filename will be searched for in the specified directory only. When path is omitted, then current directory is implied.
C:\DOS\Format.com A: /S – an example of a utility to be launched if the preceding condition is met ( if the check returns TRUE). Note that utility name should be followed by all necessary parameters. When path is not specified, the utility will be searched for in current directory and then along all the paths, stored in PATH variable’s value.
NOT	–	a reserved word, meaning a logical inversion of the result (TRUE or FALSE), returned by a check of any condition type.
ECHO Format.com isn't found! – another example of a command to be executed depending on preceding condition (when the utility is NOT found).

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:

IF NOT EXIST EMMXXXX0 ECHO The EMM driver isn't loaded!

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:

IF EXIST C:\DOS\NUL ECHO The C:\DOS directory exists!

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 :

IF %VAR%==%2 GOTO L23
IF NOT %VAR%==%2 GOTO HELP

where :

%VAR%	–	an alias to be replaced with value of environmental variable VAR ;
%2	–	an alias (dummy parameter) to be replaced with the second parameter's value of the batch file;
GOTO L23 – a command to be executed if the %VAR%= =%2 condition is met ;
NOT	–	a reserved word, meaning a logical inversion of the result (TRUE or FALSE), returned by condition check ;
GOTO HELP – a command to be executed if the %VAR%= =%2 condition is NOT met.

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 (%2 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 :

IF %VAR%.==%2. GOTO L23
IF NOT %VAR%.==%2. GOTO HELP

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 :

IF .==%CASH%. ECHO The CASH variable has an empty value

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):

IF NOT A: B: C:.==. ECHO Compared items are not equal
IF .A: B: C:==.A: ECHO Compared items (.A: and .A:) are equal
IF . B: C:==. ECHO Compared items (dots) are equal too

In all of these three examples the presence of the B: and C: 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 :

IF ERRORLEVEL 1 ECHO Execution has failed
IF NOT ERRORLEVEL 1 ECHO Execution has terminated successfully

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 :

IF NOT ERRORLEVEL 16 IF ERRORLEVEL 15 GOTO ERROR15

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.

Notes

1. Non-zero errorlevel code is used by some utilities to indicate different circumstances of normal (not erroneous) outcome.
2. All internal commands (3.01 - 3.34) don't return and don't change errorlevel code.
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.

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

FOR %%Z in (*.*) do echo %%Z

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 DOS=UMB (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 :

LH /L:1,23680 \DOS\DRV\Mscdex.exe /D:CD1 /E /S /V /L:O /M:32

The name of the driver is preceded by a path (\DOS\DRV\) 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 /L 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 /L:1,23680, where /L:1 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 /L parameter is optional, but when the size is specified, the LH command can accept one more parameter /S, for example :

LH /L:1,2160 /S \DOS\COM\Escape.com

The /S 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 /S parameter apart from memory optimization procedure, performed by memory optimization utility MEMMAKER.EXE (5.04-03). During this procedure the /L and /S parameters together with exact size specification will be automatically inserted in all those lines of AUTOEXEC.BAT file with LH command.

Notes

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.

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

ECHO Y | LOCK C: D:

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 :

MD C:\DOS\ARC

where :

C:\DOS\	–	an example of a path to an existing directory, where the new subdirectory should be created ;
ARC	–	an example of a unique name for the new subdirectory to be created. Backslash after this name is not allowed.

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.

Notes

1. MKDIR is another valid name for the same MD command.

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 :

PATH C:\DOS\VC4;C:\DOS\MS7;C:\WINDOWS\COMMAND

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.

Notes

1. Within a string of path specifications there must be no spaces on both sides of each semicolon separator.
2. There must be no semicolon at the end of a string of path specifications.
3. The PATH command with no following arguments just displays the defined paths and leaves them unchanged.
4. The PATH ; command (followed by one semicolon only) deletes all previously defined paths.
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.

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 > NUL

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 :

PAUSE < CON

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 :

ECHO ©| PAUSE > NUL

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 :

$Q	equality sign ( = )
$$	single dollar symbol ( $ )
$T	current time
$D	current date
$P	current disk’s letter-name and path to current directory
$V	Windows' version number
$N	current disk’s letter-name
$G	right arrow (or greater-than) sign ( > )
$L	left arrow (or less-than) sign ( < )
$B	vertical bar (or pipe) sign ( | )
$H	the 08h code "Backspace" (A.02-8)
$_	carriage return (0Dh) and linefeed (0Ah)
$E	code 1Bh "Escape" (A.02-8)

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 (PROMPT $P$G), 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 :

prompt @echo off$_Set Ret$q$p
C:\Command.com /c Ret.bat > Ret.bat
Call Ret.bat

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 :

@echo off
Set Ret=D:\BACKUP

Note that prompt parameter "Set Ret$q$p" has been transformed into "Set Ret=D:\BACKUP", where "D:\BACKUP" 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 :

%Ret%\
CD %Ret%

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 :

• 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.

Here is a RD command usage example :

RD D:\TEMP\NOTES

where :

NOTES	–	is the name of a directory to be deleted ;
D:\TEMP\	–	is an example of a path to the directory to be deleted. The path may be specified in any of its allowed forms (2.02-01, 2.02-03). If path is omitted, a subdirectory of the current directory is implied.

Notes

1. RMDIR is another valid name for the same RD command.

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

REM > Anyfile.ext

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.

Notes

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).
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.

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 :

REN C:\DOS\Notes.txt Notes.old

where :

C:\DOS\	–	an example of a path to the file to be renamed; the path may be specified in any of its allowed forms (2.02-01, 2.02-03) or may be omitted.
Notes.txt – current name of the file to be renamed.
Notes.old – an example of new name for the same file; the new name must be specified without preceding path, even if the file to be renamed exists anywhere else beyond the current directory.

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 :

REN Part_??.txt Chap_??.txt

Notes

1. Directories and files with H (hidden) attribute can't be renamed by the REN command.
2. Attributes of the renamed file(s) remain unchanged.

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:

SET TEMP=D:\Temp

where :

TEMP	–	is an example of variable's name ;
D:\Temp	–	is the value to be assigned to the variable TEMP. Equation sign(s) and redirection symbols (2.04-02 – 2.04-05) inside value specification are forbidden.

Notes

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.
2. If a part to the right of the equation sign is empty, then specified variable will be deleted (will cease to exist).
3. The SET command is able to expand environmental space, when it is not enough to accommodate the new value of a variable.
4. In batch files the value to the right of the equation sign may include substitutions for other variable's names (for example, %VAR%) and for dummy parameters (2.03-03). All such aliases will be replaced with their values before defining the new variable.
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).

3.27 SHIFT – dummy parameter’s order shift

The SHIFT command shifts by −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 :

TIME 11:39:23,24

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 :

ECHO= | TIME | Find.exe "Current" >> Anyfile.txt

Here the first redirection (ECHO= | TIME) automatically responds to the displayed offer and enables non-stop action, the second redirection (TIME | Find.exe) excludes undesirable output lines and the third redirection (>> Anyfile.txt) 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).

Notes

1. The TRUENAME command does not display error messages.
2. The TRUENAME command cannot be applied to network paths unless a LAN driver is installed.
3. The action of TRUENAME command is based on INT 21\AH=60h (8.02-72).

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 :

TYPE C:\DOS\Notes.txt

where :

Notes.txt – a name example of the file to be displayed; wildcards in a name are not allowed by TYPE command.
C:\DOS\	–	is an example of a path to the file to be displayed; the path may take any of allowed forms (2.02-01, 2.02-03) or be omitted. In the latter case the file is implied to exist in the current directory.

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

TYPE A:\Config.sys > PRN

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 :

UNLOCK C:

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 /R parameter

VER /R

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).

Notes

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 /V parameter of COPY command (3.06) for copying file(s) only to diskette(s).
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.

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 :

VOL A:

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