.drill [through] <"var1,var2,var3"|$EnvVar|-r[p] Register> [gr[ouped by] "{}"] [sep[arated by] ","] [exec] "Command $1 $2"
The .drill command allows you to loop over a command, executing the command
once for each member of a series of values. You can specify the values on
the command line, or draw them from an environment variable or register. When
it executes a .drill command, the system uses the .drill syntax to construct
a series of command lines and sends them to the agent for execution.
For example, the command
.drill "A,B,C,D" "echo value $1"
creates the following commands:
echo value A
echo value B
echo value C
echo value D
Grouping
You can group the values and reference
multiple values in each group using the $1, $2, etc. syntax. $1 refers to
the first value in the group, $2 to the second value in the group. For example,
.drill
through "(A,B,C,D,E),(B,C,D,E,F),(C,D,E,F,G)" grouped by "()" separated by
"," exec "echo 1[$1] 2[$2] 3[$3] 4[$4] 5[$5]" creates these commands:
echo 1[A] 2[B] 3[C] 4[D] 5[E]
echo 1[B] 2[C] 3[D] 4[E] 5[F]
echo 1[C] 2[D] 3[E] 4[F] 5[G]
Note: There is no default
grouping character. There is a default separator character, the comma. If
you do not specify
grouped by, the system looks through the
supplied values as separated by the separator character and considers each
such string a single value. For example, the command
.drill "(A,B),(C,D)"
"echo $1 $2" resolves to the following commands:
echo (A 2
echo B) 2
echo (C 2
echo D) 2
Data Sources
You have several options for where
the .drill command gets the data that it loops through. The first parameter
for the command is the data source. You can include the optional command word
"through" to indicate the data source.
- You can explicitly list the data in the command line, as in the following
command, which loops over the values one, two, and three:
.drill through "one,two,three" exec "echo $1"
- You can draw the data from an environment variable. The following command
assumes that the environment variable FILENAMES is a comma-separated list
of files, and uses a DOS command to delete all the files in the list:
.drill through $FILENAMES exec "del $1"
- You can draw the data from a register or a project register. If RegisterA
contains a comma-separated list of filenames, then the following command issued
to a Linux system writes out the content of each file:
.drill -r RegisterA exec "cat $1"
while
the following example does the same but uses a project register:.drill -rp ProjectRegisterA exec "cat $1"