System Actions


Performs a number of system-based functions.

The available commands are:

Comment

Set Variable

Delete Variable

Increment Variable

Decrement Variable

Set Environment Variable

Set Step Delay

vTask Setting Change

Write to Output

Write to Log

Set Clipboard Text

Paste Clipboard

Clear Clipboard

Image Capture

Logoff

Restart

Shutdown

Windows API

  Comment
Provides a place to enter internal comments for the script. This allows you to include notes without having the step run. This is valuable for providing descriptions beyond the individual "Comment" field in each action. It can also help to separate different sections of your file. This step will not be executed when a file is run, but breakpoints can still be placed on Comment entries.

There is no limit to the amount of text that can be put in a comment.


  Set Variable
Use this action to create a new variable, assign an initial value to it, and to update it during a run. There is no need to "declare" a variable in vTask before using it. To set it to an initial value, simply put the number or text in the "Set to Value" field.

*Tip:  If you want to set the value to the result of a Math Calculation, you must precede the formula with an equals sign "=", just like Excel. In Excel, if you enter "1 + 1", you will get "1 + 1". If you enter "=1+1", you will get "2". vTask Studio works the exact same way.

If you want to update a variable with a math calculation, see the section on Math Calculations. For example, you can update a variable by simply using a Set Variable command such as =%foo + 10:

*Tip:  To evaluate whether a variable is NULL, exists, or has an empty value, use the IF Variable check.

The No Variable Expansion option causes all text to remain in its untranslated state. The result of this is that System Variables such as {year} will remain as "{year}" instead of being substituted for "2007". User Variables will also remain untranslated.


  Delete Variable
This action deletes the both variable and its value. Once a variable is deleted, it will not be defined or substituted for data during a run.

To remove all variables, select the "Remove All Variables" checkbox option. When used, all previously existing variables will no longer be defined.

There is a difference between undefined variables and empty variables. A variable that is not defined or deleted will appear as it is typed, for example, "%foo" will appear as "%foo" in a script. In contrast, a variable with no value will appear as empty, for example, "%foo" will appear as "" if it doesn't have a value. See the Set Variable Action for more information about setting a variable to an empty value.

*Tip:  To evaluate whether a variable is NULL, exists, or has an empty value, use the IF Variable check.

  Increment Variable
This action increases the value of a variable by 1.


  Decrement Variable
This action decreases the value of a variable by 1. It continues to decrement even if the value is less than 0 and becomes negative.


  Set Environment Variable
Allows you to set a system environment variable. These are global, computer-based variables that usually contain directory information. This action performs the same function as the "Control Panel - System - Advanced" screen:



To check your environment variable, you can go to a command prompt, and type the SET command. This will list all environment variables present in the system, and your new variable will also be there. However, any open Command Prompt windows will not have the new variable - this is a limitation of Windows. All new Command Prompt windows in the current and future sessions will have the variable. Also, the variable will be immediately available in any script action.



To delete an environment variable, leave the "Set to Value" field blank. This will both remove the current value, and delete the variable from the system.


  Set Step Delay

*Tip:  To provide maximum performance while running scripts, be sure that: "Set Step Delay" is set to 0 The "Results Log" is turned OFF in Tools - Options The "Output Toolbox" is turned OFF in the View menu The "Variables Toolbox" is turned OFF in the View menu These items can have a significant effect on the performance of script execution speed. With them all turned off, scripts will run many times faster.

This is a positive number that indicates how much of a delay you want between each step, in milliseconds (thousandths of a second). 1000 milliseconds = 1 second. A value of 0 will run the script as fast as possible (without any delay). A value of 1000 will run each step at a rate of 1 per second, and 500 would run a step every half-second.

This setting takes effect immediately, and can be changed multiple times in a single script.

This "Delay All Scripts (Global)" option allows you to set the delay once and have it take effect across all scripts. Otherwise, the delay only affects the current script.

vTask is optimized to run with 0 delay - (run as fast as possible, no pauses). The only advantage to slowing down the execution is so that you can watch the progress of the script, when combined with the highlight current step option. To wait for other processes to finish, use the Delay action instead of this command.


  vTask Setting Change
Updates a vTask setting during a run. This can be useful for modifying a setting inside of a script, rather than using a single setting for the entire run. For example, you may want to turn off the Run Tracking during only a portion of your script so it doesn't block the screen.

vTask Option	Description
Run Tracking	Shows or hides the run tracking popup
Logging	Activates or deactivates vTask run logging
Highlight Current Step	Starts or stops the tracking of the current step in the script

  Write to Output
Provides a method to view text in the Output window of vTask.

This can be very useful for debugging.

The text that is shown with this action has the advantage of being fully translated. This allows you to see the contents of variables (such as {hwnd}) that might not otherwise be available while running a script.

If you have a debugger available on your PC, the output text from this command will also go to the debugger output:



If you don't have a debugger, you can download "DebugView" from http://www.sysinternals.com or http://www.microsoft.com/technet/sysinternals/Miscellaneous/DebugView.mspx.

Here is a screen shot of it running:



  Write to Log
Provides a method to add your entries to the logfile. This can be used for many purposes, such as debugging scripts, and recording information that is not provided by vTask internally.

The text that is shown with this action has the advantage of being fully translated. This allows you to see the contents of variables (such as {hwnd}) that might not otherwise be available while running a script.


  Set Clipboard Text
Puts the specified text into the clipboard. The previous clipboard contents are not saved.

To get the clipboard contents at any time, use the "{clipboard}" system variable.


  Paste Clipboard
Pastes the current clipboard contents into the active application. (Note: this method does *not* use the WM_PASTE system message, which is highly unreliable for various reasons).


  Clear Clipboard
Empties the clipboard. The previous clipboard contents are not saved.


  Image Capture
Allows you to save a bitmap image of a portion of the screen. The format of the image is Windows Bitmap (.BMP).

*Tip:  Also see the related Grid Snapshot to Clipboard feature.

The "Capture Window" option will save an image of the active window. You can set the active window with the Use Window command. This feature also includes the capability of saving images of child windows, such as buttons. Given the following window:





The script above would capture the following image:




Because it generates an image format, the Image Capture command can only save bitmaps to Files and the Clipboard. The other Save Output options, such as "Save to Variable," are not supported. You can use variables in the File Name field, such as "C:\Screen Image %hh%mm%ss.bmp". This allows you to create dynamic names if you want to save various images during the run.

If you want to capture window images for use in a script, see the Creating Images for use in vTask entry which describes using the camera tool included in vTask.


  Logoff
Logs off the current user in Windows. This is the same as the "Start - Log Off User" command. Some programs may ask for verification before the logoff is complete. This provides an opportunity to cancel the logoff command.


  Restart
Shuts down Windows and restarts the computer. All programs that are running are forcibly shut down (no user intervention is required).


  Shutdown
Powers off the computer. All programs that are running are forcibly shut down (no user intervention is required).


  Windows API
"Windows API" stands for "Windows Application Programming Interface", and is a distinguishing feature of vTask. It allows you to directly access the internals of the Windows operating system without programming, and as far as we're aware, one of the only tools to accomplish this.

The ability to directly type in text functions to access the operating system including parameters without a dedicated SDK is a very unique capability of vTask, and allows you the same level of access as a Windows programmer. When combined with vTask's ability to compile standalone programs, some truly remarkable automation scripts are possible, that can approach professional programmer-level applications.

vTask has the ability to save output data into passed parameters. The "GetWindowText" function is an example of this: parameter #2 is where the title string is saved. Since vTask does not have memory pointer variable types, the variable that is passed must be deleted prior. If it is not deleted, it will contain a value, and it will be translated (interpreted or substituted) prior to running the function.
Here is an example:



Be sure to use the "lookup" button; it provides many common examples of Windows functions:



You won't need to tell vTask in what DLL to find the Windows function - it knows how to do that automatically. Below are some working examples of Windows API calls. You can copy and paste these directly into the Action Text in your script:

*Tip:  The sample files included with vTask and the examples below demonstrate correct syntax for many functions. Use them as templates for your own function calls.

Standard user message: MessageBox( 0, "Direct call into Win API", "Title here", MB_OK ) MessageBox with "MB_YESNOCANCEL" and "MB_ICONERROR": MessageBox( 0, "Yes/No/Cancel with Error icon", "Title", MB_YESNOCANCEL+MB_ICONERROR ) Returns screen width: GetSystemMetrics( SM_CXSCREEN ) Returns screen height: GetSystemMetrics( SM_CYSCREEN ) Sends "WM_SYSCOMMAND + SC_RESTORE" to a window: SendMessage( %hWnd, 274, 61728, 0 ) Copies a file: CopyFile( "c:\filename1.txt", "c:\filename2.txt", 0 ) Use the Windows Shell to open a file: ShellExecute( 0, "open", "c:\filename.txt", 0, 0, 1 ) Sounds the speaker: Beep( 1000, 250 ) Flashes the top window: FlashWindow( %hWnd, 1 )

Here are some examples of multiple-step Windows API function calls:

Empties the clipboard: Step #1:   OpenClipboard(%hWnd) Step #2:   EmptyClipboard() Step #3:   CloseClipboard()

Demonstrates accessing a return string: Step #1:   Delete Variable %title Step #2:   GetWindowText( %hWnd, %title, 512 ) Step #3:   Display Message: "%title"

Moving a window to a new location: Step #1:   Use Window: "Untitled - Notepad" Step #2:   MoveWindow( %hWnd, 10, 10, 200, 200, 1 )

Checks a pixel color in a window: Step #1:   Start Program: notepad.exe Step #2:   Use Window: "Untitled - Notepad" Step #3:   %hdc = GetDC( %hWnd ) Step #4:   %color = GetPixel( %hdc, 100, 100 ) Step #5:   ReleaseDC( %hWnd, %hdc ) Should be "16777215", which is "#FFFFFF" (white): Step #6:   Display Info Message: %color

Draws a diagonal red line on the screen: Step #1:   Set Run Speed 10 Step #2:   %hdc = GetDC( 0 ) Step #3:   Start For Loop: 50 loops Step #4:   SetPixel( %hdc, {loopcount}, {loopcount}, 255 ) Step #5:   End Loop Step #6:   ReleaseDC( 0, %hdc )

Access a file handle for low-level I/O: Step #1:   %file = CreateFile( "c:\test_file.txt",               GENERIC_READ | GENERIC_WRITE,               FILE_SHARE_READ | FILE_SHARE_WRITE,               NULL, OPEN_ALWAYS,               FILE_ATTRIBUTE_NORMAL, NULL ) Step #2:   WriteFile( %file, "test", 4, "", 0 ) Step #3:   CloseHandle( %file )

Various system-level "C" string functions:   %length = lstrlen( "abc" )   %difference = lstrcmp( "abc", "xyz" )   %substring_exists = StrStr( "abc123", "bc" )

Please note that it is not possible for us to test every function call in Windows with vTask. Certain functions may cause problems due to the intricacies of programming the Windows operating system (books on this subject tend to be quite large). Additionally, little error validation is possible prior to running external function calls - for example, no data type checking is possible. Calling a function which expects a string with a number will cause undesirable results (a euphemism for a crash). Therefore, this feature is meant to serve in special circumstances where there is no other alternative, or where you just have to use a low-level Windows function to accomplish something. However, after that disclaimer, the Windows API access should normally work just fine, and all of the samples listed above have been tested and work as expected.