DO
![[ Return to TOC ]](jp_toc.gif){kind=small}
DO |
|
| Purpose: | Create loops in batch files. |
| Format: | DO loop_control |
commands
[ITERATE]
commands
[LEAVE]
commands
ENDDO
Loop_control formats
DO count
DO varname = start TO end [BY step]
DO WHILE condition
DO UNTIL condition
DO UNTIL DATETIME date time
DO FOR n [SECONDS | MINUTES | HOURS]
DO varname IN [range...] /D"directory" [/I:"text" /S[n] /A:[[-|+]rhsadecijopt] fileset
DO varname IN [/T"delimiters"] /L stringset
DO varname IN /C stringset
DO varname IN @file
count |
Integer in the range [0, 2 147 483 647], or an internal variable or variable function that evaluates to such a value, specifying the number of times the loop is executed. |
varname |
The environment variable containing the current value of the loop index, or the current filename or string, or the current line from a file. Do not prefix the variable name with %. |
start, end, step |
Integers in the range [-2 147 483 647,2 147 483 647] or internal variables or variable functions that evaluate to such values, controlling the number of times the loop is executed. |
condition |
A conditional expression to determine whether or not the loop should be executed |
fileset |
A filename or list of filenames, possibly using wildcards |
stringset |
An arbitrary set of strings. Wildcards are not interpreted. |
file |
A file each line of which contains a string the loop is to be executed for |
A date, time, size or exclusion range. At most one of each, in any order. |
|
commands |
One or more commands to execute each time through the loop. If you use multiple commands, they must be separated by command separators or be placed on separate lines. |
date |
The loop termination date in ISO 9601 format |
time |
The loop termination time in 24-h hh:mm:ss format |
(Attribute select) |
|
Loop through each character in expression |
|
Start directory |
|
(match description) Description range. |
|
members of set are strings, not filenames |
|
Perform the loop in the current directory and all its subdirectories |
Supports extended wildcards, ranges, and include lists for the set. Use wildcards with caution on LFN volumes; see LFN File Searches for details.
Usage
DO can only be used in batch files.
Types of DO Loops
DO can be used to create several different kinds of loops.
set ct=0
do 5
beep
set ct=%@inc[%ct]
enddo
do i = 2 to 20 by 2
echo %i
enddolea
DO can also count down, rather than up. If step is negative, varname will be decreased by the absolute value of step with each loop, and the loop will stop when varname is less than end. For example, to display the even numbers from 2 through 20 in reverse order, replace the first line of the example above with:
do i = 20 to 2 by -2
| • | DO WHILE condition evaluates condition each time through the loop as a conditional expression before executing the loop, and will execute it only if it is true. If condition is FALSE when the DO is first executed, the loop will never be executed. |
| • | DO UNTIL condition evaluates condition as a conditional expression each time after execution of the loop, and repeats the loop only if it is FALSE. Therefore, the statements within the loop will always be executed at least once. |
| • | DO varname IN fileset executes the commands between DO and ENDDO by creating an environment variable, varname, and setting it equal to every filename in the fileset, ignoring items not matching file or directory names. This is similar to the set used in the FOR command, but it can only include file and directory names, not arbitrary text strings. If varname already exists in the environment, it will be overwritten (unlike the control variable in FOR). For example: |
do x in *.txt
...
enddo
will execute the loop once for every .TXT file in the current directory; each time through the loop the variable x will be set to the name of the next file that matches the file specification. The order of matches is dependent on the file system, and is totally unrelated to any characteristics of the filenames matched.
If, between DO and ENDDO, you create a new file that could be included in the list of files, it may or may not appear in an iteration of the DO loop. Whether the new file appears depends on its physical location in the directory structure, a condition over which TCC has no control.
To use date, time, size, description, or file exclusion ranges for the set place them just before the filename(s), for example:
do x in /[d9-1-2004,9-31-2004] *.txt
| • | DO varname IN /L stringset executes the commands between DO and ENDDO once for every string literal in stringset, setting varname to each in turn. |
| • | DO varname IN /C stringset executes the commands between DO and ENDDO once for every character in stringset (including whitespace and special characters), setting varname to each in turn. |
| • | DO varname IN @file executes the commands between DO and ENDDO once for every line in file, setting varname to the content of each one in turn. Beware of characters with special meaning to TCC, such as redirection and piping symbols, within the file (use SETDOS /X as needed). |
To execute the loop once for each line of text in the clipboard, use CLIP: as the file name (e.g. DO X IN @CLIP:). CLIP: will not return any data unless the clipboard contains text. See Redirection for more information on CLIP:.
Special DO keywords: ITERATE and LEAVE
Two special keywords, ITERATE and LEAVE, may be used inside a DO / ENDDO loop. ITERATE ignores the remaining commands inside the loop and returns to the beginning of loop for another iteration, unless DO determines that the loop is finished. LEAVE exits from the current DO loop and continues with the command following its ENDDO. Both keywords may be repeated as often as desired. Both ITERATE and LEAVE are most often used in an IF or IFF command (group):
do while "%var" != "%val1"
...
if "%var" == "%val2" leave
enddo
Usage Notes
Numeric input may be entered in either decimal format (series of digits 0-9) or in hexadecimal format ("0x" followed by a sequence of 0-F hex digits).
DO loops can be nested, i.e. you can have a DO/ENDDO loop within another DO/ENDDO loop.
The DO and ENDDO commands must be on separate lines, and cannot be placed within a command group, or on the same line as other commands. (This is the reason DO loops cannot be used in aliases.) However, commands within the DO loop can use command groups or the command separator in the normal way. For example, the following command will not work properly, because the DO and ENDDO are inside a command group and are not on separate lines:
if "%a" == "%b" (do i = 1 to 10 & echo %i & enddo) invalid command line
However, this batch file fragment uses multiple commands and command grouping within the DO, and will work properly:
do i = 1 to 10
...
if "%x1" == "%x2" (echo Done! & leave)
...
enddo
You can exit from all DO / ENDDO loops by using GOTO to a line past the corresponding ENDDO. However, be sure to read the cautionary notes about GOTO and DO under the GOTO command before using GOTO in any other way inside any DO loop.
You cannot use RETURN to return from a GOSUB while inside a DO loop.
Note: Do not confuse the DO command with the unrelated optional do keyword of the FOR command.
Options:
| /A: | Select the files in a DO x IN ... by their specified attribute(s). See Attribute Switches for information on the attributes which can follow /A:. |
| /C | For each loop, assign the next character (including whitespace and special characters) in the expression to the DO variable. |
| /I"text" | Select files in a DO x IN ... by matching text in their descriptions. See Description Ranges for details. |
| /L | The parameters following DO x IN /L are strings, not filenames. Each parameter will be assigned in sequence, from left to right, to the loop control variable on consecutive passes through the loop. |
| d | Skip hidden directories (when used with /S) |
| j | Skip junctions (when used with /S) |
| /S | Perform the DO loop in the current directory and then on all of its subdirectories. (DO also supports /R as a synonym, for compatibility with FOR.) |
If you specify a number after the /S, DO will limit the subdirectory recursion to that number. For example, if you have a directory tree "\a\b\c\d\e", /S2 will only affect the "a", "b", and "c" directories.