SystemUtil Object

Description

An object used to control applications and processes during a run session.

IMPORTANT

The SystemUtil object is a UFT One reserved object. Reserved objects are not learned or stored in the object repository. Reserved objects enable you to retrieve or control UFT One settings or to modify UFT One behavior during a run session.  Most UFT One reserved objects are described in the Utility section of the Object Model Reference.

Operations

The sections below list the built-in methods and properties that you can use as operations for the SystemUtil object.

Methods

Method BlockInputPrevents keyboard and mouse input events from reaching applications.
Method CloseDescendentProcessesCloses all processes opened by UFT One.
Method CloseProcessByHwndCloses a process that is the owner of a window with the specified handle.
Method CloseProcessByIdCloses a process according to its Process ID (PID).
Method CloseProcessByNameCloses a process according to its name.
Method CloseProcessByWndTitleCloses all processes that are owners of windows with the specified title.

Method PrintToDebugStream

Prints custom log messages from a UFT One test to the Windows debug stream.
Method RunRuns a file or application.
Method UnblockInputRe-enables keyboard and mouse input events after a BlockInput statement was used to block them.

Back to top

 

BlockInput Method

Description

Prevents keyboard and mouse input events from reaching applications.

Syntax

object.BlockInput

Return Type

None

IMPORTANT

You can use this method to prevent a run session being accidentally interrupted by someone using the keyboard or mouse on a UFT One computer.

After using this method, keyboard and mouse input is blocked until one of the following occurs:

  • An UnblockInput statement is used
  • A run session ends or is paused for any reason (end of test run, run error, breakpoint)
  • The Ctrl+Alt+Delete key combination is pressed on the keyboard
  • A critical system error occurs

Example

'The following example uses the BlockInput method to block keyboard
'and mouse input to the UFT One computer during the run session.

SystemUtil.BlockInput
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").WebEdit("userName").Set "mercury"
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").WebEdit("password").SetSecure "4082986e39ea469e70dbf8c5a29429fe138c6efc"
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").Image("Sign-In").Click 2, 2
SystemUtil.UnblockInput

Back to top

 

CloseDescendentProcesses Method

Description

Closes all processes opened by UFT One.

Syntax

object.CloseDescendentProcesses

Return Type

A long integer value.

The number of instances of the application that are closed when the statement runs.

IMPORTANT

Note: UFT One initially tries to close the process by sending a WM_CLOSE message to the process window. If the process is still open after 5 seconds, UFT One terminates the process.

Example

'Suppose that the Record and Run dialog box opens a Windows Explorer window
'at the beginning of a test run, and then the statement below opens a
'Notepad window.  In this case the message box statement below displays 2.

SystemUtil.Run "Notepad.exe"
MsgBox SystemUtil.CloseDescendentProcesses

Back to top

 

CloseProcessByHwnd Method

Description

Closes a process that is the owner of a window with the specified handle.

Syntax

object.CloseProcessByHwnd (hWnd)

Arguments

ParameterDescription
hWnd Required. An unsigned long integer value.
The handle of the window owned by the process you want to close.
Tip: You can retrieve the window handle using the hwnd property.  For example:
Window("MyAppName").GetROProperty("hwnd")

Return Type

A Boolean value.

  • True--The specified process was successfully closed.
  • False--The specified process was not closed.

IMPORTANT

Note: UFT One initially tries to close the process by sending a WM_CLOSE message to the process window. If the process is still open after 5 seconds, UFT One terminates the process.

Example

'The following example retrieves the handle of the Notepad window, and then
'uses the CloseProcessByHwnd method to close the notepad application.

hWnd = Window("Notepad").GetROProperty("hwnd")
SystemUtil.CloseProcessByHwnd (hWnd)

Back to top

 

CloseProcessById Method

Description

Closes a process according to its Process ID (PID).

Syntax

object.CloseProcessById (wdProcessId)

Arguments

ParameterDescription
wdProcessId Required. An unsigned long integer value.
The Process ID (PID) of the process you want to close.
Tip: You can find the PID of an application by viewing the value in the Processes tab of the Windows Task Manager, or you can retrieve the value using the process id property.  For example:
Window("MyAppName").GetROProperty("process id")

Return Type

A Boolean value.

  • True--The specified process was successfully closed.
  • False--The specified process was not closed.

IMPORTANT

Note: UFT One initially tries to close the process by sending a WM_CLOSE message to the process window. If the process is still open after 5 seconds, UFT One terminates the process.

Example

'The following example retrieves the process ID of the Notepad window, and then
'uses the CloseProcessByID method to close the notepad application.

PID = Window("Notepad").GetROProperty("process id")
    SystemUtil.CloseProcessById (PID)

Back to top

 

CloseProcessByName Method

Description

Closes a process according to its name.

Syntax

object.CloseProcessByName (bsProcessName)

Arguments

ParameterDescription
bsProcessName Required. A String value.
The name of the process you want to close.

Return Type

A long integer value.

The number of instances of the application that are closed when the statement runs.

IMPORTANT

Note: UFT One initially tries to close the process by sending a WM_CLOSE message to the process window. If the process is still open after 5 seconds, UFT One terminates the process.

Example

'The following example uses the CloseProcessByName method to close any open
'instances of Notepad.  If the only instances of Notepad that are open are
' those opened by the statements below, then the MsgBox displays 3.

SystemUtil.Run "Notepad.exe"
SystemUtil.Run "Notepad.exe"
SystemUtil.Run "Notepad.exe"
MsgBox SystemUtil.CloseProcessByName("Notepad.exe")

Back to top

 

CloseProcessByWndTitle Method

Description

Closes all processes that are owners of windows with the specified title.

Syntax

object.CloseProcessByWndTitle (bsTitle, [bRegExp])

Arguments

ParameterDescription
bsTitle Required. A String value.
The title of the window owned by the process you want to close.
bRegExp Optional. A Boolean value.
Indicates whether the bsTitle argument is treated as a regular expression. 

Default value = False

Return Type

A long integer value.

The number of instances of the application that are closed when the statement runs.

IMPORTANT

Note: UFT One initially tries to close the process by sending a WM_CLOSE message to the process window. If the process is still open after 5 seconds, UFT One terminates the process.

Example

'The following example closes all top-level windows with a titlebar that contains the
'string "Notepad", by specifying "Notepad" as a regular expression.

SystemUtil.CloseProcessByWndTitle "Notepad", True
'The following example closes all top-level windows with the exact title: "Untitled - Notepad".
'The title string is treated as a literal string.

SystemUtil.CloseProcessByWndTitle "Untitled - Notepad"

Back to top

PrintToDebugStream

Description

Prints custom log messages from a UFT One test to the Windows debug stream.

Tip: A useful tool for viewing debug messages is DbgView.

For more details, see the OutputDebugString function in the Windows Dev Center.

Syntax

object.PrintToDebugStream (message)

Arguments

ParameterDescription
message Required. A String value.
The message to be printed to Windows debug stream.

Return Type

None

Example

'The following example prints the "Hello World" text to the Windows debug stream.

SystemUtil.PrintToDebugStream "Hello World"

Back to top

 

Run Method

Description

Runs a file or application.

Syntax

object.Run file, [params], [dir], [op], [mode]

Arguments

ParameterDescription
file Required. A String value.
The name of the file you want to run.
params Optional. A String value.
If the specified file argument is an executable file, use the params argument to specify any parameters to be passed to the application.

Default value = ""
dir Optional. A String value.
The default directory of the application or file.

Default value = ""
op Optional. A String value.
The action to be performed. If this argument is blank ( ""), the open operation is performed.
The following operations can be specified for the op argument:

Operation

Description

open
Opens the file specified by the FileName parameter. The file can be an executable file, a document file, or a folder. Non-executable files are open in the associated application.
edit
Launches an editor and opens the document for editing. If the FileName argument does not specify an editable document file, the statement fails.
explore
Explores the folder specified by the FileName argument.
find
Initiates a search starting from the specified folder path.
print
Prints the document file specified by the FileName argument. If the specified file is not a printable document file, the statement fails.

Default value = "open"
mode Optional. An integer value.

Specifies how the application is displayed when it opens. You can specify one of the modes in the table below.
Default = 1

Mode

Description

0
Hides the window and activates another window.
1 
Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. Specify this flag when displaying the window for the first time.
2 
Activates the window and displays it as a minimized window.
3 
Activates the window and displays it as a maximized window.
4 
Displays the window in its most recent size and position. The active window remains active.
5 
Activates the window and displays it in its current size and position.
6 
Minimizes the specified window and activates the next top-level window in the Z order.
7 
Displays the window as a minimized window. The active window remains active.
8 
Displays the window in its current state. The active window remains active.
9 
Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. Specify this flag when restoring a minimized window.
10 
Sets the show-state based on the state of the program that started the application.

Default value = 1

Return Type

None

IMPORTANT

When specifying a non-executable file, the file opens in the associated application.

Note: A SystemUtil.Run statement is automatically added to your test when you run an application from the Start menu or the Run dialog box while recording a test.

Tip: You can also use this method to perform operations on the specified file, similar to the usage of the Windows ShellExecute command.

Example

'The following example uses the Run method to open a file named type.txt
'in the default text application (Notepad). It then types "happy days",
'saves the file using shortcut keys, and then closes the application.

SystemUtil.Run "C:\type.txt", "", "", ""
Window("Text:=type.txt - Notepad").Type "happy days"
Window("Text:=type.txt - Notepad").Type micAltDwn & "F" & micAltUp
Window("Text:=type.txt - Notepad").Type micLShiftDwn & "S" & micLShiftUp
Window("Text:=type.txt - Notepad").Close

Back to top

 

UnblockInput Method

Description

Re-enables keyboard and mouse input events after a BlockInput statement was used to block them.

Syntax

object.UnblockInput

Return Type

None

IMPORTANT

You can use this method to unblock keyboard and mouse input that was earlier blocked using a BlockInput statement.

Example

'The following example uses the UnblockInput method to unblock keyboard
'and mouse input to the UFT One computer that was blocked
'during the run session.

SystemUtil.BlockInput
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").WebEdit("userName").Set "mercury"
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").WebEdit("password").SetSecure "4082986e39ea469e70dbf8c5a29429fe138c6efc"
Browser("Welcome: Mercury Tours").Page("Welcome: Mercury Tours").Image("Sign-In").Click 2, 2
SystemUtil.UnblockInput

Back to top

See also: