Loop and Flow Actions


Allows repeating blocks of steps, and controls flow of execution.

"LOOP" blocks are functionally identical to the processing of all computer languages, such as BASIC. The generic syntax is:

START LOOP . . command block . . NEXT LOOP

LOOP blocks can be nested to multiple levels:

*Tip:  Be sure to use the Auto-Indent and Validate command with scripts that use Loops and IF statements. It will help your script be more readable and reliable.

The available commands are:

Start 'For' Loop

Start 'While' Loop

Start Text Loop

Start Files Loop

Start File Line Loop

Start Folders Loop

Start Windows Loop

Start Dataset Loop

Start Registry Loop

Start Process Loop

Break out of Loop

NEXT LOOP

Label

GOTO Label

GOSUB Label

Return from GOSUB

Set Run Repeats

Exit Run

Exit vTask Studio

  Start 'For' Loop
Repeats a group of steps. All script actions between the "Start Loop" and "End Loop" are repeated. This action must be closed with a NEXT LOOP step.

Only the "Stop Number (To/Total)" is required; the other values (Start, Step Increment) will default to "1" if omitted. Multiple Loops may be embedded inside of each other. User variables may be used for the number of loops. Negative numbers can be used for the "Step Increment" value to create descending loops (10, 9, 8,... etc).


  Start 'While' Loop
Repeats a group of steps, as long as an expression is true. A sample expression:



In the example, once the user variable "%done" is set to something besides 0, the loop will stop repeating. For further information on Expressions, see Running Scripts - Expressions. Another sample, using CALC instead of Increment Variable:




  Start Text Loop
Repeats a group of steps, once for each text item in a list. If the source string is not empty, the loop will perform at least one time.

For example, you may loop through a list of items. If you had the text "A,B,C" it would first return A, then B, then C (assuming you set "comma" as the delimiter). Another common delimiter is the newline (such as {newline}, {return}, {\n}, etc). Therefore, the list:

      uno
      dos
      tres

would cycle through each line during this action.

If the delimiter is omitted, a newline is assumed to separate each text entry.


  Start Files Loop
Repeats a group of steps, once for each file that is found for the "File Spec" that is provided.

*Tip:  This action is most useful when using wildcard file searches: C:\Folder\*.* - will loop all files in the folder C:\Folder\*.txt - will loop through each of the text files in the folder C:\Folder\%pattern - will loop through each of the files that conforms to the user variable %pattern

Recursion and Wildcards are described in detail in the Copy File section. File Loops that use recursion cannot be nested with other recursive file loops (but can be nested with any other loop). Please note that the file count of this action may be higher than what is returned at the command prompt, because vTask is also able to find hidden and system files.


  Start File Line Loop
Repeats a group of steps, once for each line in the specified file. The return value (in Save Output) will contain the full file name + path. To parse the file name, such as to a short name or folder name, use the Get File Info action with the "Name: Base+Extension" option.


  Start Folders Loop
Repeats a group of steps, once for each Folder (Directory) that is listed under the starting folder. If the "Recursive" option is chosen, it will loop through all sub-folders to all levels under the main folder. Otherwise, only folders in the first level of the main source folder are returned.

The return value (in Save Output) will contain the fully qualified path name. To parse the file name, use the Get File Info action with the various "Drive/Path/Base/Extension" options.


  Start Windows Loop
Repeats a group of steps, once for each main program window that is running.

If "Child Controls" option is chosen, the controls that are under the provided "Parent Window" are enumerated. For loops through program windows, the "Parent Window" will set the first window of the loop, and then continues with the next sequential sibling windows.

There are two options for the output data return: Text and Handle. "Text" is the window title, and "Handle" is the numeric HWND value.


  Start Dataset Loop
Repeats a group of steps, once for row of data that is returned from the previously executed SQL statement - a Execute SQL Query action must precede the Start Dataset Loop step:



The data from the Execute SQL Query will be used to provide the data results for the loop. It is highly recommended to use the ORDER BY statement in SQL to retrieve rows in the correct sort order.

The dataset loop cannot be embedded within another dataset loop. However, unlimited Execute SQL Query commands may be used inside the loop. For example, the following works properly:



But due to data set conflicts and memory constraints, the following is not permitted:




  Start Registry Loop
Repeats a group of steps, once for each key entry that is under a tree, such as "NoDriveTypeAutoRun". The data contained under the key is not returned. Use the Read Registry action to read the data.

For example, in the following sample using "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer", the Registry Loop would loop twice, and return first "NoDriveTypeAutoRun", and then "NoFind":



To view all registry entries, use the "regedit.exe" program (which can be launched in Start-Run).

*Tip:  Use caution when working with the Registry. Improper use of the Registry can make your computer non-functional! If you are not familiar with the Registry settings, do not change or delete them.

  Start Process Loop
Repeats a group of steps, once for process that is currently running. A process may be a visible program, such as Notepad, or an invisible background process.

This process list is also visible in the Windows Task Manager, which can be accessed by pressing Ctrl+Shift+Escape:



There are two options for the output data return: EXE and ID. "EXE" is the full file name of the program, and "ID" is the Process ID from Windows.


  Break out of Loop
Immediately leaves the loop without executing any more loop steps or further evaluation. As with other programming languages, this action only breaks out of the inner loop in which it is embedded. Processing continues with the step after the matching NEXT LOOP step. For a global break out of all embedded loops, use the Goto Label action.


  NEXT LOOP
Returns to the first step in the loop, which was begun with the "Start Loop" action. Loop completion is evaluated at this step, and if the loop is finished, processing continues with the following step.


  Label
Lets you add a label marker inside of your script. This is used for jumps from other lines and errors (see GOTO Label and GOSUB Label). A label can be any text, up to 63 characters long. This step has no other special function when a file is run (it's only a placeholder).


  GOTO Label
Jumps to a label. The label can come before or after this command (anywhere in the script). User Variables (such as "%label") may be used as the destination. Labels that are skipped will not be used as a destination.

You can jump directly to a hard-coded step (without defining a Label) by using the {STEP1}, {STEP2}, etc. system variables. These system variables are only accessed by the Goto Label action. If you move steps around, the Goto Label will still jump to the same step.

"Goto Label" serves the same purpose as a GOTO programming statement - it immediately goes to the indicated step. If the specified label does not exist, a warning is displayed and execution stops.


  GOSUB Label
Jumps to a label, and remembers the curent location in the script. This allows execution to return to the same spot later, when the Return from GOSUB command appears. The label can come before or after this command (anywhere in the script). User Variables (such as "%label") may be used as the destination.

The basic structure of a GOSUB is:



The GOSUB command in vTask is similar to "calling a procedure" functionality in programming languages. This allows you to "call" or run a section of your script, and then return to the same original spot when the sub-section is done. The GOSUB command is convenient for performing the same function several times in a program without duplicating the steps.

The advantage of GOSUB over GOTO is that you don't need to manually manage the return point, which avoids needing another GOTO and LABEL steps for the return. This results in cleaner scripts and more predictable script flows.

Here's a basic example:



A GOSUB can call another GOSUB, and so on. Each will return to the point where it was originally called. Be sure to add steps to prevent entry into a GOSUB section during normal execution, such as with the "Exit Run" step (as shown in sample above). Otherwise the script will run through the steps in the block without the GOSUB calling them.

GOSUB can only jump to a location inside of the same script. Although GOSUB cannot go to a Label inside of a different script, however the CALL SCRIPT action has the ability to jump to an external file.


  Return from GOSUB
Redirects execution to the step that follows the GOSUB Label step. This command terminates the GOSUB block, and returns back to the script location that originally called the GOSUB.

This command is not required (it doesn't need to match a GOSUB). However, if omitted, execution will continue in the script without returning to the original GOSUB point. If this command appears by itself, an error is generated if vTask cannot find the matching GOSUB. The error information will be displayed in the Output window.

For an example of GOSUB functionality, including examples, please see the GOSUB Label action.


  Set Run Repeats
This is the number of times the entire command file will be repeated. To continuously repeat a file, set "Run Repeats" to -1 (available as a checkbox inside of the Repeats field).


  Exit Run
Immediately stops execution of the script at the current step. You can set the "return code" for the process. This is the numeric value that is passed to the previous process, and usually is used to indicate success or failure. It is commonly referred to as the ERRORLEVEL environment variable. This return code also works when a file is compiled into an executable. Refer to the "Default Return Code" option to see how to set this to a default value.

Below is an example of accessing the return code inside a script:



Here is a sample of a batch file that uses the return code:

TEST.BAT @echo off rem Display the return code and check if positive: vTask.exe /r Myfile.vxm rem (you could also run a compiled EXE:) Myfile.exe echo The return code was %ERRORLEVEL% rem How to check if the return code was positive: if ERRORLEVEL 1 echo PASSED rem How to check for a specific number: if %ERRORLEVEL% EQU 1234 echo PASSED rem How to take a path based on return code: goto answer%ERRORLEVEL% :answer0 echo Program had return code 0 goto end :answer1 echo Program had return code 1 goto end :end echo done!

  Exit vTask Studio
Immediately stops execution of the script at the current step, and closes the vTask program.

The "Return Value" is the result number that is passed to any program that called the script.