Peformance Testing with Citrix Protocol : Citrix ICA Vuser Functions (CTRX)

Mouse Functions

ctrx_mouse_click	Emulates a mouse click on a Citrix client
ctrx_mouse_double_click	Emulates a double mouse click on a Citrix client
ctrx_mouse_down	Emulates a mouse down click on a Citrix client
ctrx_mouse_move	Emulates a mouse move on a Citrix client sent to a Citrix server.
ctrx_mouse_up	Emulates a mouse up click on a Citrix client

ctrx_mouse_click

Emulates a mouse click on a Citrix client sent to a Citrix server.

int ctrx_mouse_click( long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

int ctrx_obj_mouse_click( const char *obj_desc, long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

obj_desc	A description of the object recorded if the agent is installed on the server.
x_pos	The horizontal distance of the mouse click from the edge of the active window.
y_pos	The vertical distance of the mouse click from the edge of the active window.
mouse_button	Mouse Key Values.
key_modifier	Key Modifier Values.
window_name	The title of the window in which the mouse click occurs. NULL if not within an active window.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_mouse_click waits for window window_name to appear, then executes the mouse click.

If the agent is installed on the server, ctrx_obj_mouse_click is recorded. The only difference is the additional object description.

If the mouse click occurs on the desktop (i.e., not within a window), then x_pos and y_pos will hold values relative to the edge of the ICA client window. If the mouse click occurs on the desktop, window_name is NULL.

The wildcard character (*) can be used in window_name.

Limitation in Windows 8.1

On Windows 8.1, a click on the Start button does not display the Start menu. When clicking on the Start Button, add a second ctrx_mouse_click or ctrx_obj_mouse_click to the script below the recorded click.

Return Values

The following is a list of error codes returned by Citrix ICA functions. They are defined in the file ctrxfuncs.h under the include directory of the installation.

Define value	Value	Description
E_OK	0	Success
E_NOT_DISPLAYED	-91999	Failed wait for window to appear
E_DISPLAYED	-91998	Failed wait for window to close
E_ILLEGAL_PARAMETER	-91997	One of the parameters is invalid
E_GENERAL_ERROR	-91996	Unspecified error
E_DISCONNECTED	-91995	The server has disconnected prematurely
E_WRONG_ICAFILE	-91994	The specified .ica file could not be found
E_NOT_ACTIVE	-91993	The specified window is not active
E_INCORRECT_CLIENT_VER	-91992	Citrix client version no longer supported
E_NFUSE_FAIL	-91991	Citrix web connection failed
E_OUT_OF_TIME	-91990	Synchronization or wait operation timed out
E_INTERNAL	-91989	Internal error
E_SYNC_ATTRIB_FAILED	-91988	Synchronize on object information timed out

Parameterization

No parameterization is available for this function.

Example: ctrx_mouse_click

In the following example, after connecting to the server ludens and opening Microsoft's Internet Explorer application, the function ctrx_mouse_click clicks the "exit" window checkbox of Internet Explorer.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Launch the web browser by clicking on desktop IE icon */
     ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);
     lr_think_time(13);
     ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

     /* Exit the web browser by clicking on top left Exit check box */
     ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,
               "Welcome to MSN.com - Microsoft Internet Explorer");
     lr_think_time(12);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_mouse_double_click

Emulates a double mouse click on a Citrix client sent to a Citrix server.

int ctrx_mouse_double_click( long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

int ctrx_obj_mouse_double_click( const char *obj_desc, long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

obj_desc	A description of the object recorded if the agent is installed on the server.
x_pos	The horizontal distance of the mouse click from the edge of the ICA client window.
y_pos	The vertical distance of the mouse click from the edge of the ICA client window.
mouse_button	Mouse Key Values.
key_modifier	Key Modifier Values that were pressed together with the mouse_button.
window_name	The title of the window in which the double mouse click occurs. NULL if not within an active window.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_mouse_double_click waits for window window_name to appear, then executes a mouse double click.

If the agent is installed on the server, ctrx_obj_mouse_double_click is recorded. The only difference is the additional object description.

If the double mouse click occurs on the desktop (i.e., not within a window), then x_pos and y_pos will hold values relative to the edge of the screen.

The wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_mouse_double_click

In the following example, after connecting to the Citrix server ludens, ctrx_mouse_double_click double-clickswith the left mouse button onMicrosoft's Internet Explorer to start that application.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Launch the web browser by clicking on desktop IE icon */
     ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);
     lr_think_time(13);
     ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

     /* Exit the web browser by clicking on top left Exit check box */
     ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,
               "Welcome to MSN.com - Microsoft Internet Explorer");
     lr_think_time(12);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_mouse_down

Emulates a mouse down click on a Citrix client sent to a Citrix server.

int ctrx_mouse_down( long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

int ctrx_obj_mouse_down( const char *obj_desc, long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

obj_desc A description of the object recorded if the agent is installed on the server.

x_pos The horizontal distance of the mouse down click from the edge of the ICA client window.

y_pos The vertical distance of the mouse down click from the edge of the ICA client window.

mouse_button Mouse Key Values.

key_modifier Key Modifier Values that were pressed together with the mouse_button.

window_name The title of the window in which the double mouse click occurs. NULL if not within an active window.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_mouse_down waits for the window window_name to appear, then executes the mouse down.

If the agent is installed on the server, ctrx_obj_mouse_down is recorded. The only difference is the additional object description.

If the mouse down click occurs on the desktop (i.e., not within a window), then x_pos and y_pos will hold values relative to the edge of the screen.

The wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_mouse_down

In the following example, after connecting to the Citrix server ludens, Microsoft's Word application is launched and some text is typed into the new document. The text is then highlighted, ctrx_mouse_down is invoked at the beginning of the text, and ctrx_mouse_up is recorded when the cursor has been drawn across the entire string.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Double click on Microsoft Word icon */
     ctrx_mouse_double_click(37, 243, LEFT_BUTTON, 0, NULL);

     ctrx_set_window("Document1 - Microsoft Word"); /* wait for Word to appear */
     ctrx_type("This is a test ");

     /* Highlight "This is a test" with the mouse */
     ctrx_mouse_down(29, 138, LEFT_BUTTON, 0, "Document1 - Microsoft Word");
     ctrx_mouse_up(117, 137, LEFT_BUTTON, 0, "Document1 - Microsoft Word");

     lr_think_time(6);
     ctrx_key("DELETE_KEY", 0); /* delete text */
     lr_think_time(3);

     /* Exit Word */
     ctrx_mouse_click(24, 39, LEFT_BUTTON, 0, "Document2 - Microsoft Word");
     ctrx_set_window("Microsoft Word"); /* The "Do you want to save" dialog */
     /* Click on don't save */
     ctrx_mouse_click(44, 217, LEFT_BUTTON, 0, "Microsoft Word");

     /* Wait for Word to exit */
     ctrx_unset_window("Document1 - Microsoft Word");
     lr_think_time(2);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_mouse_move

Emulates a mouse move on a Citrix client sent to a Citrix server.

int ctrx_mouse_move( long x_pos, long y_pos, long mouse_button, long key_modifier, CTRX_LAST );

int ctrx_obj_mouse_move( const char * obj_desc, long x_pos, long y_pos, long mouse_button, long key_modifier, CTRX_LAST );

obj_desc A description of the object recorded if the agent is installed on the server.

x_pos The horizontal distance of the mouse up click from the edge of the ICA client window.

y_pos The vertical distance of the mouse up click from the edge of the ICA client window.

mouse_button Mouse Key Values.

key_modifier Key Modifier Values that were pressed together with the mouse_button.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_mouse_move and ctrx_obj_mouse_move moves the mouse to the specified coordinates on the screen.

ctrx_mouse_move is not recorded. It can be entered manually in a script if necessary.

Parameterization

No parameterization is available for this function.

Example: ctrx_mouse_move

This is an example of the use of ctrx_mouse_move to move the pointer to 35 pixels from the left edge and 235 pixels from the top edge of the client window while pressing the left mouse button:

ctrx_mouse_move(34, 235,LEFT_BUTTON, 0, CTRX_LAST );

ctrx_mouse_up

Emulates a mouse up click on a Citrix client sent to a Citrix server.

int ctrx_mouse_up( long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name , [CONTINUE_ON_ERROR,] CTRX_LAST );

int ctrx_obj_mouse_up( const char *obj_desc, long x_pos, long y_pos, long mouse_button, long key_modifier, char *window_name , [CONTINUE_ON_ERROR,] CTRX_LAST );

obj_desc A description of the object recorded if the agent is installed on the server.

x_pos The horizontal distance of the mouse up click from the edge of the ICA client window.

y_pos The vertical distance of the mouse up click from the edge of the ICA client window.

mouse_button Mouse Key Values.

key_modifier Key Modifier Values that were pressed together with the mouse_button.

window_name The title of the window in which the double mouse click occurs. NULL if not within an active window.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_mouse_up waits for the window window_name to appear, then executes a mouse up at the specified position.

If the agent is installed on the server, ctrx_obj_mouse_up is recorded. The only difference is the additional object description.

If the mouse up click occurs on the desktop (i.e., not within a window), then x_pos and y_pos will hold values relative to the edge of the screen.

The wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_mouse_up

In the following example, after connecting to the Citrix server ludens, Microsoft's Word application is launched and some text is typed into the new document. The text is then highlighted, ctrx_mouse_down is invoked at the beginning of the text, and ctrx_mouse_up is recorded when the cursor has been drawn across the entire string.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Double click on Microsoft Word icon */
     ctrx_mouse_double_click(37, 243, LEFT_BUTTON, 0, NULL);

     ctrx_set_window("Document1 - Microsoft Word"); /* wait for Word to appear */
     ctrx_type("This is a test ");

     /* Highlight "This is a test" with the mouse */
     ctrx_mouse_down(29, 138, LEFT_BUTTON, 0, "Document1 - Microsoft Word");
     ctrx_mouse_up(117, 137, LEFT_BUTTON, 0, "Document1 - Microsoft Word");

     lr_think_time(6);
     ctrx_key("DELETE_KEY", 0); /* delete text */
     lr_think_time(3);

     /* Exit Word */
     ctrx_mouse_click(24, 39, LEFT_BUTTON, 0, "Document2 - Microsoft Word");
     ctrx_set_window("Microsoft Word"); /* The "Do you want to save" dialog */
     /* Click on don't save */
     ctrx_mouse_click(44, 217, LEFT_BUTTON, 0, "Microsoft Word");

     /* Wait for Word to exit */
     ctrx_unset_window("Document1 - Microsoft Word");
     lr_think_time(2);
     ctrx_disconnect_server("ludens");

     return 0;
}

Keyboard Functions

Click one of the following functions for more information:

ctrx_key Emulates a non-alphanumeric key press on a Citrix client

ctrx_type Emulates alphanumeric key presses on a Citrix client

ctrx_key

Emulates a non-alphanumeric key press on a Citrix client sent to a Citrix server.

int ctrx_key( char *key, long int key_modifier, [filename,] CTRX_LAST );

key The name of the non-alphanumeric key, such as "END_KEY". See the Key Codes for a list of the available keys.

key_modifier Key Modifier Values that were pressed together with key.

filename The name of the bitmap file containing a screen shot of the window. This file is located in the script directory under data/bitmap/.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_key emulates a user pressing a non-alphanumeric key on a Citrix client.

Parameterization

Parameterization is available for all arguments of this function.

Example: ctrx_key

In the following example, the user starts the Microsoft Word application. Various key activities are recorded including calls to ctrx_key. To save the application, the user presses the Ctrl–S combination. This registers in ctrx_key as key "s" with "MODIF_CONTROL" as the key_modifier.

/* Run the Microsoft Word application by clicking icon on desktop */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window("Document1 - Microsoft Word");

ctrx_type("This is the start of a new MS Word document");

ctrx_key("HOME_KEY", 0); /* Go to the beginning of the line */

ctrx_key("1", MODIF_NUMPAD, CTRX_LAST); /* Emulates pressing "1" on the number pad*/

ctrx_key("1", NO_MODIF, CTRX_LAST); /* Emulates pressing "1" on keyboard above the "Q" key */

ctrx_key("END_KEY", 0); /* Go to the end of the line */

ctrx_key("ENTER_KEY", 0); /* Start a new line with a line feed */

ctrx_type("This is a new line");

ctrx_key("UP_ARROW_KEY", 0); /* Go up to the previous line */

/* Now save document with Ctrl-S */ctrx_key("s", MODIF_CONTROL);

lr_think_time(6);

ctrx_set_window("Save As");

/* save as the default name which MS Word provides */

ctrx_mouse_click(604, 392, LEFT_BUTTON, 0, "Save As");

/* Exit Word application */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Document1 - Microsoft Word");

ctrx_type

Emulates typing alphanumeric keys.

int ctrx_type( char *data, [filename,] CTRX_LAST );

data The alphanumeric key presses

filename The name of the bitmap file containing a screen shot of the window. This file is located in the script directory under data/bitmap/.

CTRX_LAST A marker that indicates the end of the argument list.

The function ctrx_type emulates a user typing alphanumeric characters.

During recording, alphanumeric key presses are recorded until some other type of keyboard activity, such as mouse clicks or non-alphanumeric key presses.

Note: When typing is slow, VuGen may break up a typing session into successive invocations of ctrx_type. By manually editing the script, these calls can be concatenated. This will enable easier parameterization if you require the string to be substituted with a parameter.

Parameterization

Parameterization is available for all arguments of this function.

Example: ctrx_type

In the following example, theuser starts the Microsoft Word application. When the user types the document, key activity is recorded by ctrx_type. To save the application the user presses the Ctrl–S combination, which is recorded by ctrx_key.

/* Run the Microsoft Word application by clicking icon on desktop */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window("Document1 - Microsoft Word");

/* 2 calls to ctrx_type were recorded because of slow typing. They can

be concatenated manually to facilitate parameterization

i.e., ctrx_type("This is the start of a new document"); */

ctrx_type("This is the start of");

ctrx_type("a new document");

ctrx_key("HOME_KEY", 0); /* Go to the beginning of the line */

ctrx_key("END_KEY", 0); /* Go to the end of the line */

ctrx_key("ENTER_KEY", 0); /* Start a new line with a line feed */

ctrx_type("This is a new line");

ctrx_key("UP_ARROW_KEY", 0); /* Go up to the previous line */

/* Now save document with Ctrl–S */

ctrx_key("s", MODIF_CONTROL);

lr_think_time(6);

ctrx_set_window("Save As");

/* Save as the default name MS Word provides */

ctrx_mouse_click(604, 392, LEFT_BUTTON, 0,

"Document1 - Microsoft Word");

/* Exit Word application */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Document1 - Microsoft Word");

Selection Functions

Click one of the following functions for more information:

ctrx_list_select_item Selects an item from a list.

ctrx_menu_select_item Highlights a menu item.

ctrx_list_select_item

Selects an item from a list.

int ctrx_list_select_item( char *window_name, long xpos, long ypos, char *item, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The title of the window in which the menu appears.

xpos The input parameter containing the horizontal distance of the left edge of the item from the edge of the application window.

ypos The input parameter containing the vertical distance of the top edge of the item from the edge of the application window.

item The item in the list.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

The ctrx_list_select_item function selects an item from list. It supports lists of class ListBox or ComboBox.

ctrx_list_select_item is available only if the agent is installed on the Citrix server.

Parameterization

Parameterization is available for all arguments of this function.

Example: ctrx_list_select_item

In this example, ctrx_list_select_item selects a font in the Notepad application.

ctrx_sync_on_window( "Untitled - Notepad",

ACTIVATE, -4, -4, 809, 609, "snapshot1", CTRX_LAST );

ctrx_obj_mouse_click("<text=OK class=Button>",

394, 376, LEFT_BUTTON, 0, "Untitled - Notepad=snapshot2",

CTRX_LAST );

ctrx_obj_mouse_click("<text=Untitled - Notepad class=Notepad>",

80, 32, LEFT_BUTTON, 0, "Untitled - Notepad=snapshot3",

CTRX_LAST );

ctrx_sync_on_window("58_37_100_41", CREATE, 58, 37, 100, 41,

"snapshot4", CTRX_LAST );

ctrx_obj_mouse_click("<class=#32768>", 93, 66, LEFT_BUTTON, 0,

"Untitled - Notepad=snapshot5", CTRX_LAST );

ctrx_sync_on_window( "Font", ACTIVATE, 20, 126, 438, 345,

"snapshot6", CTRX_LAST );

ctrx_obj_mouse_click("<text=Times New Roman class=Edit>",

124, 58, LEFT_BUTTON, 0, "Font=snapshot7", CTRX_LAST );

ctrx_list_select_item( "Font", 124, 58, "Arial Black", CTRX_LAST );

ctrx_key( "ENTER_KEY", 0 );

ctrx_sync_on_window( "Untitled - Notepad", ACTIVATE, -4, -4, 809, 609, "snapshot8", CTRX_LAST );

ctrx_type( "Test" );

ctrx_menu_select_item

Highlights a menu item.

int ctrx_menu_select_item( char *window_name, char *menu_path, [CONTINUE_ON_ERROR,] CTRX_LAST) ;

window_name The title of the window in which the menu appears.

menu_path The full path of the menu.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_menu_select_item highlights an item in a menu, but does not activate it.

The window should be in the foreground when the ctrx_menu_select_item is called.

ctrx_menu_select_item is available only if the agent is installed on the Citrix server.

The menu path consists of all the items at each menu level that are selected to activate the selected. Levels are separated by a semi-colon ( ; ). The text of each level is passed to ctrx_menu_select_item exactly as it appears, including the periods that separate the menu item from the short-cut, and the short cut. The spaces in the menu can be replaced with a single white space.

Parameterization

Parameterization is available for all arguments of this function.

Example: ctrx_menu_select_item

In this example, ctrx_menu_select_item selects the file open menu in Note Pad. ctrx_obj_mouse_click then activates the selection.

ctrx_set_connect_opt(APPLICATION, "#NOTES");

ctrx_set_connect_opt(NETWORK_PROTOCOL, "TCP/IP");

ctrx_connect_server("plato", "test", lr_decrypt("test"), "plato");

ctrx_wait_for_event("LOGON");

ctrx_sync_on_window("Untitled - Notepad", ACTIVATE, -4, -4, 809, 609, "snapshot1", CTRX_LAST );

ctrx_obj_mouse_click("<text=OK class=Button>", 383, 373, LEFT_BUTTON, 0, "Untitled - Notepad=snapshot2", CTRX_LAST );

ctrx_menu_select_item("Untitled - Notepad",

"File;Open... Ctrl+O", CTRX_LAST );

ctrx_sync_on_window("Open", ACTIVATE, 0, 38, 564, 348, "snapshot6", CTRX_LAST );

ctrx_obj_mouse_click("<text=&Open class=Button>", 506, 303, LEFT_BUTTON, 0, "Open=snapshot7", CTRX_LAST );

Synchronization Functions

Functions automatically generated by VuGen:

Functions which can be manually inserted by user:

ctrx_set_waiting_time	Sets the waiting time for all Citrix ICA wait functions
ctrx_set_window	Waits for a window to appear in the Citrix client
ctrx_set_window_ex	Waits for a window to appear in the Citrix client for a specified amount of time
ctrx_sync_on_bitmap	Waits until a bitmap appears
ctrx_sync_on_bitmap_change	Waits until a bitmap changes
ctrx_sync_on_obj_info	Wait until the specified object's attributes have the specified value
ctrx_sync_on_text	Waits until specified text is displayed around the specified position.
ctrx_sync_on_text_ex	Waits until specified text is displayed in the specified area.
ctrx_sync_on_text_ocr	Waits until specified text is displayed in the specified rectangle, using optical character recognition.
ctrx_sync_on_window	Waits for a window to become created or active
ctrx_unset_window	Waits for a window to close in the Citrix client
ctrx_wait_for_event	Waits for a specified event to occur
ctrx_win_exist	Checks if a window is visible on the screen

ctrx_set_waiting_time

Sets the waiting time for all Citrix ICA wait functions.

int ctrx_set_waiting_time( long waitTime );

waitTime The time to wait in seconds

ctrx_set_waiting_time changes the waiting time of the Synchronization Functions from the default 60 seconds.

Note: This function does not change the waiting time of the Connection Functions that connect and disconnect from the Citrix server.

Parameterization

No parameterization is available for this function.

Example: ctrx_set_waiting_time

In the following example, a ctrx_set_waiting_time has been inserted before launching the Web browser, because the default waiting time of 60 seconds wasn't long enough for the browser to appear. Note that the value of 180 also changes the waiting time of all other Synchronization Functions.

Actions () {

/* set_waiting_time for all sync functions. Used here for ctrx_set_window */

ctrx_set_waiting_time(180);

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on the desktop IE icon */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

/* ctrx_set_window now has a 2 minute waiting time instead of 1 */

ctrx_set_window(

"Mercury Interactive Corporation at mercuryinteractive.com");

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Mercury Interactive Corporation at mercuryinteractive.com");

lr_think_time(12);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_set_window

Waits for a window to appear in the Citrix client.

int ctrx_set_window( char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The window title.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

When emulating a GUI user, a window must appear before it can be used.

ctrx_set_window is a synchronization function that waits for a window to appear before the Vuser emulates any keyboard or mouse activity in the window.

The window_name argument indicates the name of the window that ctrx_set_window waits for, as it appears in the window's top header frame. The asterisk wildcard character (*) can be used in window_name.

If there is a succession of windows appearing in a short period of time, VuGen will only record the last call to ctrx_set_window.

Parameterization

The parameter window_name can be parameterized

Example: ctrx_set_window

In the following example, after connecting to the Citrix server ludens, ctrx_set_window waits for the window of Microsoft's Internet Explorer. Internet Explorer's home page is the Mercury Interactive site, so the string "Mercury Interactive Corporation at mercuryinteractive.com" appears in the header frame of the window. When the window appears, the code then continues with the next statement, ctrx_mouse_click.

Actions () {

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on desktop IE icon */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window(

"Mercury Interactive Corporation at mercuryinteractive.com");

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Mercury Interactive Corporation at mercuryinteractive.com");

ctrx_unset_window(

"Mercury Interactive Corporation at mercuryinteractive.com");

lr_think_time(12);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_set_window_ex

Waits a specified time for a window to appear in the Citrix client.

int ctrx_set_window_ex( char *window_name, long waitTime, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The window title.

waitTime The time, in seconds, to wait for window_name to appear

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

When emulating a GUI user, a window must appear before it can be used.

ctrx_set_window_ex is a synchronization function that waits up to waitTime seconds for a window to appear before the Vuser emulates any keyboard or mouse activity in the window.

The window_name argument indicates the name of the window that ctrx_set_window_ex waits for, as it appears in the window's top header frame. The asterisk wildcard character (*) can be used in window_name.

waitTime is the timeout for the window to appear. If window_name does not appear in within this period, ctrx_set_window_ex exits. waitTime does not affect the timeout of other functions, only the call to ctrx_set_window_ex.

If there is a succession of windows appearing in a short period of time, VuGen will only record the last call to ctrx_set_window_ex.

Parameterization

The parameter window_name can be parameterized

Example: ctrx_set_window_ex

In the following example, after connecting to the Citrix server ludens, ctrx_set_window_ex waits for the window of Microsoft's Internet Explorer (with a timeout of 75 seconds). Internet Explorer's home page is the Mercury Interactive site, so the string "Mercury Interactive Corporation at mercuryinteractive.com" appears in the header frame of the window. When the window appears, the code then continues with the next statement, ctrx_mouse_click.

Actions () {

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on desktop IE icon */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window_ex(

"Mercury Interactive Corporation at merc*", 75);

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Mercury Interactive Corporation at mercuryinteractive.com");

ctrx_unset_window(

"Mercury Interactive Corporation at mercuryinteractive.com");

lr_think_time(12);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_sync_on_bitmap_change

Waits until a bitmap changes.

int ctrx_sync_on_bitmap_change( long x_start, long y_start, long width, long height, [int Initial Wait Time,] [int Timeout,] [const char * Initial Value,] [CONTINUE_ON_ERROR,] CTRX_LAST );

x_start The horizontal distance, in pixels, of the bitmap's top left edge from the left border of the ICA client window.

y_start The vertical distance, in pixels, of the bitmap's top left edge from the upper border of the ICA client window.

width The width, in pixels, of the bitmap.

height The height, in pixels, of the bitmap.

Initial Wait Time The initial time to wait before the starting to check the bitmap for changes. Default: 0 seconds.

Timeout The period to wait for any changes to occur in the bitmap. Default: 0 seconds

Initial Value The hashed string representing the value of the bitmap that must change.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_bitmap_change is a synchronization function that waits for a specified bitmap to change before continuing. It is typically used when a change occurs in a window but the window name remains the same. If the window name changes, ctrx_set_window is automatically generated instead.

ctrx_sync_on_bitmap_change captures a snapshot of an active bitmap when called and waits for that bitmap to change. However, if the bitmap changed before the call, it captures the new bitmap after the expected change has already occurred, and synchronizes on this bitmap. In this case, the function will fail on timeout.

If it is possible in your application for the bitmap to change before the call, use the Initial Value argument. Capture the bitmap before the change with ctrx_get_bitmap_value. Use the output buffer from ctrx_get_bitmap_value as the Initial Value. If the value of the bitmap when ctrx_sync_on_bitmap_change is called is the same as the Initial Value, the script will wait for the bitmap to change. If the bitmap is any other value, the script will continue without waiting.

Example:

// At some point before the bitmap changes

ctrx_get_bitmap_value(x_start, y_start, width, ht, capture_bmap);

// Later when you want to wait for the change

ctrx_sync_on_bitmap_change(x_start, y_start, width, ht,

0, 10, capture_bmap, CTRX_LAST );

Note: The optional arguments must be passed in the order given. To use any of the optional arguments, all preceding optional arguments must also be passed. For example, if you pass an Initial Value, you must first pass values for the Initial Wait Time and the Timeout.

Tip: ctrx_sync_on_bitmap_change can be manually recorded by clicking on the rectangle icon in VuGen's Citrix recording toolbar. The mouse pointer changes to a precision shape, which you use to select a bitmap area. VuGen automatically records the function as ctrx_sync_on_bitmap. After recording has finished, edit the name of the function to ctrx_sync_on_bitmap_change and remove the final arguments to match its parameters.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_bitmap_change

The following example launches Microsoft's Internet Explorer after connecting to the Citrix server ludens. The test run waits for the browser window to appear using ctrx_set_window.

The example then navigates to a URL that has a navigation frame. Every item in the frame loads another news story, but the title of the window ("News - Microsoft Internet Explorer") remains the same. Therefore, ctrx_set_window is not generated. In this case, a call to ctrx_sync_on_bitmap_change is inserted to wait for the change in the text that indicates that the new story has been loaded. If it loads successfully, the transaction news_item is deemed a success.

Actions () {

int rc;

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on desktop IE icon */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

/* Wait for browser window to appear */

ctrx_set_window("Nasdaq liveQUOTES - Microsoft Internet Explorer");

lr_think_time(8);

lr_start_transaction("news_item");

/* Go to the "NEWS" tab */

ctrx_mouse_click(133, 186, LEFT_BUTTON, 0,

"The Nasdaq Stock Market - Microsoft Internet Explorer");

ctrx_set_window("News - Microsoft Internet Explorer");

lr_think_time(7);

/* Click on a news item in the left frame */

ctrx_mouse_double_click(198, 320, LEFT_BUTTON, 0,

"News - Microsoft Internet Explorer");

/* Wait for news item to appear to appear */

rc = ctrx_sync_on_bitmap_change(137, 211, 51, 17, CTRX_LAST );

if (rc != E_OK)

lr_end_transaction("news_item", LR_FAIL);

else

lr_end_transaction("news_item", LR_PASS);

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Welcome to MSN.com - Microsoft Internet Explorer");

lr_think_time(12);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_sync_on_bitmap

Waits until a bitmap appears.

int ctrx_sync_on_bitmap( long x_start, long y_start,long width, long height, char *hash, [CONTINUE_ON_ERROR,] CTRX_LAST );

x_start The horizontal distance, in pixels, of the bitmap's top left edge from the left border of the ICA client window

y_start The vertical distance, in pixels, of the bitmap's top left edge from the upper border of the ICA client window

width The width, in pixels, of the bitmap

height The height, in pixels, of the bitmap

hash An encoded string representing the bitmap

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_bitmap is a synchronization function that waits for a specified bitmap to appear before continuing.

This function is typically used when a change occurs in a window but the window name remains the same. If the window name changes, ctrx_set_window is recorded instead of ctrx_sync_on_bitmap.

The function can be manually recorded by clicking on the rectangle icon in VuGen's Citrix recording toolbar. The mouse pointer changes to a precision shape, which you use to select a bitmap area.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_bitmap

The following example launches Microsoft's Internet Explorer after connecting to the Citrix server ludens. The script waits for the browser window to appear using ctrx_set_window.

The example then navigates to a URL that has a navigation frame. Every item in the frame loads another news story, but the title of the window ("News - Microsoft Internet Explorer") remains the same. Therefore, ctrx_set_window is not generated. In this case, a call to ctrx_sync_on_bitmap is inserted to wait for the change in the text that indicates that the new story has been loaded. If it loads successfully, the transaction news_item is a success.

Actions () {

int rc;

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on desktop IE icon */

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

/* Wait for browser window to appear */

ctrx_set_window("Nasdaq liveQUOTES - Microsoft Internet Explorer");

lr_think_time(8);

lr_start_transaction("news_item");

/* Go to the "NEWS" tab */

ctrx_mouse_click(133, 186, LEFT_BUTTON, 0,

"The Nasdaq Stock Market - Microsoft Internet Explorer");

ctrx_set_window("News - Microsoft Internet Explorer");

lr_think_time(7);

/* Click on a news item in the left frame */

ctrx_mouse_double_click(198, 320, LEFT_BUTTON, 0,

"News - Microsoft Internet Explorer");

/* Wait for news item to appear to appear */

rc = ctrx_sync_on_bitmap(137, 211, 51, 17,

"18d962dcbf373e948e83489a19419512");

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Welcome to MSN.com - Microsoft Internet Explorer");

lr_think_time(12);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_sync_on_obj_info

Wait until the specified object's attributes have the specified value

int ctrx_sync_on_obj_info( char *window_name, long xpos, long ypos,eObjAttribute attribute, char *value, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The window title.

xpos The horizontal distance, in pixels, from the left border of the specified window.

ypos The vertical distance, in pixels, from the upper border of the specified window.

attribute One of the Object Attributes constants.

value The value of the attribute.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

When ctrx_sync_on_obj_info is called, execution pauses until the attribute of the specified object has the specified value.

The attribute argument is an enumerated type, not a string. It is passed without quote marks.

The asterisk wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_obj_info

This example causes execution to pause until the window has focus.

ctrx_sync_on_obj_info("-2_572_805_31", 75, 6, FOCUSED, "TRUE", CTRX_LAST );

ctrx_sync_on_text

Waits until specified text is displayed around the specified position.

int ctrx_sync_on_text( long xpos, long ypos, const char *value, eObjAttribute textEvent, const char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

xpos The horizontal distance in pixels from the left border of the ICA client window.

ypos The vertical distance in pixels from the upper border of the ICA client window.

value The text to for which to wait.

textEvent TEXT to sync with object, CAPTURE to use saved text in box, or CAPTURE_LINE to use saved text in narrow box.

window_name The window title. The asterisk wildcard character (*) can be used in window_name.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_text is a synchronization function that waits for a specified string to appear at the specified position before continuing.

The xpos, ypos are relative to the window if defined or to the ICA client if window_name is null.

When ctrx_sync_on_text is recorded, the textEvent argument is set by the logic of the recording engine. Do not edit it.

If you wish to enter the function manually, run the script once using ctrx_get_text to find the exact string. Then, comment out the ctrx_get_text call and enter the string as the value argument in the ctrx_sync_on_text call. Use CAPTURE or CAPTURE_LINE as the textEvent argument.

When CAPTURE is used as the textEvent argument, ctrx_sync_on_text readsthe text within a rectangle of 80 by 80 pixels centered on the coordinates passed in the first 2 parameters. When CAPTURE_LINE is used, a rectangle of 80 by 10 pixels is read.

When TEXT is used as the textEvent argument, ctrx_sync_on_text waits for the appearance of an object at the given coodinates whose text property is the value. To use TEXT, you must know the properties of the underlying object. Therefore, TEXT is generally not used when manually enhancing a script.

ctrx_sync_on_text function is recorded automatically before each mouse click and double click.

Note: Under Windows XP, to correctly record menu entries during recording, give the window focus before clicking on the menu item.

This function is available only if the agent is installed on the Citrix server.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_text

In this example, ctrx_sync_on_text causes script execution to pause until the text "OK" appears at the location of the command button.

ctrx_sync_on_text(421, 368, "OK", TEXT, "NULL=snapshot67", CTRX_LAST );

ctrx_obj_mouse_click("<class=Button text=OK>", 421, 368, LEFT_BUTTON, 0, "NULL=snapshot67", CTRX_LAST );

ctrx_sync_on_text_ex

Waits until specified text is displayed in the specified area.

int ctrx_sync_on_text_ex( long xpos, long ypos, long width, long height, const char *value, const char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

xpos The horizontal distance in pixels of the search rectangle from the left border of the ICA client window.

ypos The vertical distance in pixels of the search rectangle from the upper border of the ICA client window.

width The width of the search rectangle in pixels.

height The height of the search rectangle in pixels.

value The text to for which to wait.

window_name The window title. The asterisk wildcard character (*) can be used in window_name.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_text_ex is a synchronization function that waits for a specified string to appear in the specified area before continuing.

When ctrx_sync_on_text_ex is recorded, the textEvent argument is set by the logic of the recording engine. Do not edit it.

ctrx_sync_on_text_ex can be inserted in a script during recording or after recording from the script tree view.

ctrx_sync_on_text_ex function is recorded automatically before each mouse click and double click.

Note: Under Windows XP, to correctly record menu entries during recording, give the window focus before clicking on the menu item.

This function is available only if the agent is installed on the Citrix server.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_text_ex

In this example, ctrx_sync_on_text_ex causes script execution to pause until the text "OK" appears at the location of the command button.

ctrx_sync_on_text_ex(410, 350, 180, 80, "OK", "NULL=snapshot67", CTRX_LAST );

ctrx_obj_mouse_click("<class=Button text=OK>", 421, 368, LEFT_BUTTON, 0, "NULL=snapshot67", CTRX_LAST );

ctrx_sync_on_text_ocr

Waits until specified text is displayed in the specified rectangle, using optical character recognition (OCR).

int ctrx_sync_on_text_ocr( long xpos, long ypos, long width, long height, const char *value, const char *filename, [CONTINUE_ON_ERROR,] CTRX_LAST );

xpos The horizontal distance in pixels from the left border of the ICA client window.

ypos The vertical distance in pixels from the upper border of the ICA client window.

width Of rectangle in pixels.

height Of rectangle in pixels.

value The text to for which to wait.

filename The snapshot file. Do not edit this value.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_text_ocr is a synchronization function that waits for a specified string to appear in the specified rectangle before continuing. This function uses optical character recognition to identify the string.

The xpos, ypos are relative to the ICA client .

ctrx_sync_on_text_ocr function is not recorded. You can enter it manually in your scripts.

Parameterization

No parameterization is available for this function.

Example

In this example, ctrx_sync_on_text_ocr causes script execution to pause until text "test" appears at the specified location in Notepad window.

ctrx_sync_on_text_ocr(304, 119, 30, 15, "test", "snapshot_109", CTRX_LAST);

ctrx_obj_mouse_click("<class=Notepad>", 310, 125,

LEFT_BUTTON, 0, "Untitled - Notepad=snapshot_110",

CTRX_LAST);

ctrx_sync_on_window

Waits until a window is created or becomes active.

int ctrx_sync_on_window( char *window_name, eWindowEvent event, long x_start, long y_start, long width, long height, char *filename, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The window title.

event The event indicating success: CREATE or ACTIVE.

x_start The horizontal distance in pixels of the window's left edge from the left edge of the ICA client window.

y_start The vertical distance in pixels of the window's top edge from the top edge of the ICA client window.

width The width in pixels of the window.

height The height in pixels of the window.

filename The name of the bitmap file containing a screen shot of the window. This file is located in the script directory under data/bitmap/.

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_sync_on_window is a synchronization function that waits for a window to become created or active.

For objects that are never truly active, such as menus, use the CREATE event to synchronize your actions. For regular windows, specify the ACTIVE event, which occurs after the CREATE event. This insures that the window is stable.

The asterisk wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_sync_on_window

In the following example, the test run waits for the ICA Administrator toolbar to become active.

ctrx_set_connect_opt(NETWORK_PROTOCOL, "TCP/IP + HTTP");

ctrx_connect_server("plato", "test", lr_decrypt("3de476be2c6b6455"), "plato");

ctrx_wait_for_event("LOGON");

ctrx_sync_on_window("ICA Administrator Toolbar", ACTIVATE, 768, 0, 33, 573, "129c54d64c9679ea1a0cb8bb02c2a981", CTRX_LAST );

ctrx_sync_on_window("2_233_205_344", CREATE, 2, 233, 205, 344, "060460d39afede68e26c5a8437a94a83", CTRX_LAST );

ctrx_wait_for_event

Waits for a specified event to occur.

int ctrx_wait_for_event( char *event, [CONTINUE_ON_ERROR,] CTRX_LAST );

event The name of the event to wait for. One of:

· LOGON_AND_AGENT

· LOGON

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_wait_for_event is a synchronization function that waits for an event to occur.

Session initialization and CitrixAgent initialization may take longer than LOGON. As a result, ctrx* functions that follow immediately after ctrx_wait_for_event(LOGON) may fail. To ensure that the agent is running before continuing to the next step, use ctrx_wait_for_event(LOGON_AND_AGENT).

Parameterization

Standard parameterization is not available for this function.

Example: ctrx_wait_for_event

In the following example, the function ctrx_wait_event waits for the connection to be established to the server ludens.

Actions () {

ctrx_connect_server("ludens", "test", "test", "ludens");

ctrx_wait_for_event("LOGON");

/* Launch the web browser by clicking on desktop IE icon*/

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Welcome to MSN.com - Microsoft Internet Explorer");

lr_think_time(13);

ctrx_disconnect_server("ludens");

return 0;

}

ctrx_win_exist

Checks if a window is visible on the screen.

int ctrx_win_exist( char *window_name, long waiting_time, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name The name of the window to check

waiting_time Indicates the timeout to wait, in seconds

CONTINUE_ON_ERROR A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.

CTRX_LAST A marker that indicates the end of the argument list.

ctrx_win_exist returns E_OK (zero) if the window exists. The wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_win_exist

In the following example, ctrx_win_exist checks if the web browser has launched. If it doesn't appear within the specified waiting_time , ctrx_mouse_double_click launches the web browser from the desktop.

/* If browser has not launched in nine seconds, click the desktop IE icon */

if (!ctrx_win_exist("Welcome to MSN.com - Microsoft Internet Explorer", 9))

ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);

lr_think_time(13);

ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

/* Exit the web browser by clicking on top left Exit check box */

ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,

"Welcome to MSN.com - Microsoft Internet Explorer");

Information Retrieval Functions

ctrx_button_get_info Retrieves information about a push button.

ctrx_edit_get_info Retrieves information about a text edit field.

ctrx_execute_on_window Specifies handler function on window appearance.

ctrx_get_bitmap_value Returns the value of a bitmap as a string

ctrx_get_server_name Retrieves the name of the active server the client is connected to.

ctrx_get_text Retrieves the text in a rectangle.

ctrx_get_text_ocr Retrieves the text in a rectangle using optical character recognition.

ctrx_get_text_location Searches for a text in a selected area and retrieves the text location.

ctrx_get_window_name Retrieves the name of the active window

ctrx_get_window_position Retrieves the position of a window

ctrx_logoff Closes the current session.

ctrx_list_get_info Retrieves information about a list box.

ctrx_<obj>_get_info Retrieves information about an object.

ctrx_get_waiting_time Gets current wait time.

ctrx_<obj>_get_info

ctrx_button_get_info

ctrx_edit_get_info

ctrx_list_get_info

Gets class information about the object.

int ctrx_obj_get_info( const char *window_name, long xpos, long ypos, eObjAttribute attribute, char *value, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name	The window title. NULL if not within an active window.
xpos	The horizontal distance of the object from the edge of the application window, or ICA client window
ypos	The vertical distance of the object from the edge of the application window, or ICA client window
attribute	The Object Attributes whose value is to be retrieved
value	An output buffer for the retrieved value. object_value_buffer is allocated automatically. You may use any buffer, but you must declare and allocate memory in the script.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

The ctrx_<obj>_get_info family of functions assign the value of the attribute to the value buffer. ctrx_obj_get_info is a generic function that can be entered on any object identified as such by the recorder.

If an object is outlined in yellow in the snapshot in the tree view, then it has been recognized as an object. Right click on the outlined object, and choose Insert Object Get Info. The call will be inserted in the script.

The asterisk wildcard character (*) can be used in window_name.

ctrx_button_get_info gets information on command buttons.

ctrx_edit_get_info gets information on text boxes.

ctrx_list_get_info gets information on list boxes.

Parameterization

All input string arguments (char type) can be parameterized using standard parameterization.

Example: ctrx_<obj>_get_info

To demonstrate the *get_info functions, we use a simple Windows application:

InfoRetrieval_EXE() {

long x, y, wd, ht;

/* Run a program with a push button, text edit box,

single select list and multiple select list */

/*Run the program*/

ctrx_obj_mouse_click("<class=SysListView32>",

258, 398, LEFT_BUTTON, 0,

"NULL=snapshot170", CTRX_LAST );

ctrx_sync_on_window("Desktop", ACTIVATE,

0, 0, 801, 601, "snapshot171", CTRX_LAST );

ctrx_obj_mouse_double_click("<class=SysListView32>",

259, 397, LEFT_BUTTON, 0, "Desktop=snapshot172", CTRX_LAST );

ctrx_get_window_name(object_value_buffer);

// Output: ctrx_get_window_name: Desktop

lr_message( "ctrx_get_window_name: %s",

object_value_buffer );

ctrx_get_window_position("Form1", &x, &y, &wd, &ht);

// Output: Window position is 0, 0, 0, 0

lr_message("Window position is %ld, %ld, %ld, %ld",

x, y, wd, ht);

/* The Command1 push button */

ctrx_sync_on_window("Form1", ACTIVATE,

7, 7, 596, 256, "snapshot173", CTRX_LAST );

// Confirm that the command button is in focus.

ctrx_button_get_info("Form1",41, 39,

FOCUSED, object_value_buffer, CTRX_LAST );

// Output: ctrx_button_get_info: TRUE

lr_message( "ctrx_button_get_info: %s",

object_value_buffer );

/* Clicking the button displays the "Have a nice day"

message box */

ctrx_obj_mouse_click(

"<text=Command1 class=ThunderRT6CommandButton>",

41, 39, LEFT_BUTTON, 0, "Form1=snapshot174", CTRX_LAST );

// The message box has focus, not the command button.

ctrx_button_get_info("Form1",41, 39,

FOCUSED, object_value_buffer, CTRX_LAST );

// Output: ctrx_button_get_info: FALSE

lr_message( "ctrx_button_get_info: %s",

object_value_buffer );

/*Acknowledge the message box*/

ctrx_sync_on_window("ObjectTest",

ACTIVATE, 302, 258, 171, 101,

"snapshot175", CTRX_LAST );

// Get the message box title and position

ctrx_get_window_name(object_value_buffer);

// Output: ctrx_get_window_name: ObjectTest

lr_message( "ctrx_get_window_name: %s",

object_value_buffer );

ctrx_get_window_position("Form1", &x, &y, &wd, &ht);

// Output: Window position is 7, 7, 596, 256

lr_message("Window position is %ld, %ld, %ld, %ld",

x, y, wd, ht);

// Click OK to acknowledge the message box

ctrx_obj_mouse_click("<text=OK class=Button>",

72, 71, LEFT_BUTTON, 0,

"ObjectTest=snapshot176", CTRX_LAST );

/*Tab to text box Text1*/

ctrx_sync_on_window("Form1", ACTIVATE,

7, 7, 596, 256, "snapshot177", CTRX_LAST );

ctrx_obj_mouse_click(

"<text=Form1 class=ThunderRT6FormDC>",

233, 12, LEFT_BUTTON, 0,

"Form1=snapshot178", CTRX_LAST );

ctrx_key("TAB_KEY", 0);

// Get the text

ctrx_edit_get_info("Form1",6, 65,

TEXT, object_value_buffer, CTRX_LAST );

// Output: ctrx_edit_get_info: Text1

lr_message( "ctrx_edit_get_info: %s",

object_value_buffer );

ctrx_sync_on_obj_info("Form1",

6, 65, FOCUSED, "TRUE", CTRX_LAST );

/*Change the text*/

/* Select the text: mouse down at beginning, and up at end */

ctrx_obj_mouse_down(

"<text=Text1 class=ThunderRT6TextBox>",

8, 71, LEFT_BUTTON, 0,

"Form1=snapshot179", CTRX_LAST );

ctrx_obj_mouse_up(

"<text=Text1 class=ThunderRT6TextBox>",

74, 72, LEFT_BUTTON, 0,

"Form1", CTRX_LAST );

ctrx_type("T1");

// Get the new text

ctrx_edit_get_info("Form1",

6, 65,TEXT,

object_value_buffer, CTRX_LAST );

// Output: ctrx_edit_get_info: T1

lr_message( "ctrx_edit_get_info: %s",

object_value_buffer );

/*Click title bar, then tab to Single Selection List*/

ctrx_obj_mouse_click(

"<text=Form1 class=ThunderRT6FormDC>",

191, 11, LEFT_BUTTON, 0,

"Form1=snapshot181", CTRX_LAST );

ctrx_key("TAB_KEY", 0);

// How many lines in the list?

ctrx_list_get_info("Form1",22, 89,

LINES, object_value_buffer, CTRX_LAST );

// Output: ctrx_list_get_info: 7

lr_message( "ctrx_list_get_info: %s", object_value_buffer );

ctrx_sync_on_obj_info("Form1", 22, 89,

FOCUSED, "TRUE", CTRX_LAST );

/*Select the 4th row of the list box */

ctrx_obj_mouse_click("<class=ThunderRT6ListBox>",

44, 131, LEFT_BUTTON, 0,

"Form1=snapshot182", CTRX_LAST );

// What item is selected?

ctrx_list_get_info("Form1",22, 89, ITEM, object_value_buffer, CTRX_LAST );

// Output: ctrx_list_get_info: Emma

lr_message( "ctrx_list_get_info: %s", object_value_buffer );

// Change the selection

ctrx_list_select_item("Form1",22,89, "HENRY", CTRX_LAST );

ctrx_list_get_info("Form1",22, 89,

ITEM, object_value_buffer, CTRX_LAST );

// Output: ctrx_list_get_info: Henry

lr_message( "ctrx_list_get_info: %s", object_value_buffer );

.......................

return 0;

}

ctrx_<obj>_get_info

ctrx_button_get_info

ctrx_edit_get_info

ctrx_list_get_info

Gets class information about the object.

int ctrx_obj_get_info( const char *window_name, long xpos, long ypos, eObjAttribute attribute, char *value, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name	The window title. NULL if not within an active window.
xpos	The horizontal distance of the object from the edge of the application window, or ICA client window
ypos	The vertical distance of the object from the edge of the application window, or ICA client window
attribute	The Object Attributes whose value is to be retrieved
value	An output buffer for the retrieved value. object_value_buffer is allocated automatically. You may use any buffer, but you must declare and allocate memory in the script.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

The asterisk wildcard character (*) can be used in window_name.

ctrx_button_get_info gets information on command buttons.

ctrx_edit_get_info gets information on text boxes.

ctrx_list_get_info gets information on list boxes.

Parameterization

All input string arguments (char type) can be parameterized using standard parameterization.

ctrx_execute_on_window

Specifies handler function on window appearance.

void ctrx_execute_on_window( char *window_name, long handler );

window_name	The name of the window that initiates the handler.
handler	The function to invoke when the window is displayed.

ctrx_execute_on_window specifies the function to call when a window appears. When a window with name window_name appears, the handler function is invoked. ctrx_execute_on_window is typically used to handle a popup dialog box.

The asterisk wildcard character (*) can be used in window_name.

Put the actions you wish to perform in the handler function, which must have the following prototype:

int handler( char *title);

The name of the window is passed to the handler as title argument..

Note: The lr_rendezvous function is not supported when a ctrx_execute_on_window function is pending.

Return Values

This function has no return value.

Parameterization

No parameterization is available for this function.

Example: ctrx_execute_on_window

This example shows the definition and use of an event handler function, close_unsaved_changes.

When exiting the Microsoft Word application with an open document containing unsaved changes, a Yes-No-Cancel message window with the title "Microsoft Word" appears prompting the user to save the document.

ctrx_execute_on_window specifies that when this dialog appears, the function close_unsaved_changes is invoked. This function tabs through to the dialog's "No" button and hits the "Enter" key, thereby exiting the application without saving.

int close_unsaved_changes(char win_title[]) {     /* Note: the parameter win_title is not used in the handler */
     ctrx_key("TAB_KEY", 0); /* tab through to "No" button */
     ctrx_key("ENTER_KEY", 0); /* hit the "No" button */

     return 0;
}

vuser_init () {

     /* If "Microsoft Word" popup appears then close it*/
     ctrx_execute_on_window("Microsoft Word", close_unsaved_changes);

     ctrx_set_connect_opt(APPLICATION, "#word");
     ctrx_set_connect_opt(NETWORK_PROTOCOL, "TCP/IP");
     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");
     ctrx_set_window("Document1 - Microsoft Word");
     ctrx_type("This is a test");
     lr_think_time(3);

     /* Close MS Word by clicking the X button of the title bar. This will cause
      * the "Microsoft Word" unsaved changes dialog window to appear */
     ctrx_mouse_click(28, 38, LEFT_BUTTON, 0, "Document1 - Microsoft Word");
     lr_think_time(1);
     ctrx_mouse_click(43, 404, LEFT_BUTTON, 0, "Document1 - Microsoft Word");
     lr_think_time(5);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_get_bitmap_value

Returns the value of a bitmap as a string.

int ctrx_get_bitmap_value( long x_start, long y_start, long width, long height, char *buffer, [filename,] [CONTINUE_ON_ERROR,] CTRX_LAST );

x_start	The horizontal distance of the left edge of the bitmap from the edge of the ICA client window
y_start	The vertical distance of the top edge of the bitmap from the edge of the ICA client window
width	The width of the bitmap, in pixels
height	The height of the bitmap, in pixels
buffer	The output parameter containing the hashed string representing the bitmap value
filename	The name of the bitmap file containing a screen shot of the window. This file is located in the script directory under data/bitmap/.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

Use ctrx_get_bitmap_value to retrieve the hashed string value of a bitmap for use in your custom synchronization functions. The coordinates of the bitmap are specified in the first four parameters.

buffer is usually about 32 characters long. It is up to the user to allocate memory space for buffer before ctrx_get_bitmap_value is invoked, and to de-allocate the memory after it.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_bitmap_value

The following code snippet uses ctrx_get_bitmap in custom synchronization code. A while loop waits for a bitmap with a specified hash string to appear. When the bitmap appears, the code exits the loop.

char buffer[50];
int ReadyFlag = 0;

ctrx_mouse_double_click(52, 265, LEFT_BUTTON, 0, NULL);

while(!ReadyFlag) {

     ctrx_get_bitmap_value(35, 120, 30, 50, buffer);

     if(!strcmp(buffer, "0dd68052ce0bbcb7e8f3914471e89004"))
          ReadyFlag = 1;
     else
          Sleep(20);
}

ctrx_get_server_name

Retrieves the name of the active server to which the client is connected.

int ctrx_get_server_name( LPSTR serverName, [CONTINUE_ON_ERROR,] CTRX_LAST );

serverName	The output argument for the name of the server.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_get_server_name retrieves the name of the server to which the client is connected.

The script must allocate memory space for the output buffer, serverName, before ctrx_get_server_name is invoked. Release the memory when it is no longer in use.

When working with a secured Citrix environment, such as Citrix Access Gateway, this function can only retrieve the server name from the Citrix Agent. Therefore, the agent must be installed and active in order to retrieve a valid name.

Parameterization

Standard parameterization is not available for this function.

Example: ctrx_get_server_name

In this example, ctrx_get_server_name retrieves the name of the connected server.

char buf[100];

ctrx_get_server_name( buf, CTRX_LAST );

lr_output_message("current server name is %s", buf);

ctrx_get_text

Retrieves the text in a rectangle.

int ctrx_get_text( char *window_name, long xpos, long ypos, long width, long height, char *filename, char *text_buffer, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name	The window title. NULL if not within an active window.
xpos	The output parameter containing the horizontal distance of the rectangle from the left edge of the window
ypos	The output parameter containing the vertical distance of the rectangle from the edge of the window
width	The width of the window, in pixels
height	The height of the window, in pixels
filename	The snapshot. Do not edit this field
text_buffer	Output for the text
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_get_text assigns the text in a rectangle into text_buffer. The text can later be used in correlation.

This function is available only if the agent is installed on the Citrix server.

The xpos, ypos are relative to the window if defined or to the ICA client if window_name is null.

The default text_buffer is named text_buffer. If you use text_buffer, there is no need to allocate memory for it. If you use your own buffer, you must allocate the space.

ctrx_get_text works only when the text is real text and not a bitmap. This function can be added manually or while recording, by using the rectangle button on the floating toolbar.

The asterisk wildcard character (*) can be used in window_name.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_text

This example gets text from the "About Notepad" dialog in the "text_buffer" parameter.

ctrx_obj_mouse_click("<text=Untitled - Notepad class=Notepad>", 15, 32, LEFT_BUTTON, 0, "Untitled - Notepad=snapshot3", CTRX_LAST );

ctrx_sync_on_window("104_37_118_50", CREATE, 104, 37, 118, 50, "snapshot4", CTRX_LAST );

ctrx_obj_mouse_click("<class=#32768>", 141, 82, LEFT_BUTTON, 0, "Untitled - Notepad=snapshot5", CTRX_LAST );

ctrx_sync_on_window("About Notepad", ACTIVATE, 30, 71, 420, 330, "snapshot6", CTRX_LAST );

ctrx_get_text("About Notepad", 93, 105, 219, 74, "snapshot8", text_buffer, CTRX_LAST );

ctrx_get_text_ocr

Retrieves the text in a rectangle using optical character recognition (OCR).

int ctrx_get_text_ocr( char *window_name, long xpos, long ypos, long width, long height, char *filename, char *text_buffer, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name	The window title. NULL if not within an active window. You can use the asterisk wildcard character (*) in window_name.
xpos	Output parameter. The horizontal distance of the rectangle from the left edge of the window if defined or relative to the ICA client if window_name is null.
ypos	Output parameter. The vertical distance of the rectangle from the top edge of the window if defined or relative to the ICA client if window_name is null.
width	The width of the window in pixels.
height	The height of the window in pixels
filename	The snapshot. Do not edit this argument.
text_buffer	Output for the text. The default text buffer, named text_buffer, is allocated automatically. If you do not use text_buffer, you must allocate the buffer. For example, char myBuffer[1000];
CONTINUE_ON_ERROR	A constant entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was CONTINUE ON ERROR.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_get_text_ocr assigns the text in a rectangle into text_buffer. The text can later be used in correlation. This function can be used without the Citrix Agent being installed on the Citrix server.

You can use ctrx_get_text_ocr to retrieve the text from a bitmap or from a character string.

This function is not recorded. You can insert it manually into your script.

Parameterization

Parameterization is available for all arguments of this function.

Example

This example shows the use of ctrx_get_text_ocr.

ctrx_sync_on_window("Start", CREATE, 2, 560, 53, 39, "snapshot4", CTRX_LAST);

ctrx_get_text_ocr(NULL, 6, 56, 65, 20, "snapshot_1", text_buffer, CTRX_LAST);

// Action.c(20): Retrieved Text "Recycle Bin" in region (6, 56, 65, 20) in the desktop window

ctrx_sync_on_obj_info("NULL=snapshot5", 29, 574, TEXT, "Start", CTRX_LAST);

ctrx_obj_mouse_click("<class=Button text=Start>", 29, 574, LEFT_BUTTON, 0, "NULL=snapshot5", CTRX_LAST);

ctrx_get_text_ocr(NULL, 20, 571, 30, 18, "snapshot_2", text_buffer, CTRX_LAST);

// Action.c(26): Retrieved Text "Start" in region (20, 571, 30, 18) in the desktop window

ctrx_get_text_location

Searches for a text in a selected area and retrieves the text location.

int ctrx_get_text_location( LPCSTR window_name, long *xpos, long *ypos, long *width, long *height, LPSTR text, long bMatchWholeWordOnly, LPCSTR filename, [CONTINUE_ON_ERROR,] CTRX_LAST );

window_name	The window title. NULL if not within an active window.
xpos, ypos	Input/output parameters that set the beginning of the search area and get the text location.
width, height	The extent of the search area that starts at xpos, ypos.
text	The string for which to search.
bMatchWholeWordOnly	A flag to indicate whether to search only for a whole word match only or not. The flag can be TRUE or FALSE. True = 1, False = 0.
filename	The snapshot filename or an empty string.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_get_text_location searches for the specified text in the area specified by xpos, ypos, width, and height. If the string is found, after the function returns, xpos, and ypos are the location at which the text was found. If the string is not found, xpos, and ypos are zero.

This function is available only if the agent is installed on the Citrix server.

The search text is a single word. A search for a phrase including spaces will always fail.

The xpos, and ypos arguments are relative to the window. If the window name is NULL, they are relative to the ICA client.

The asterisk wildcard character (*) can be used in window_name.

The easiest way to use ctrx_get_text_location is to record a script, then use the snapshot to insert a ctrx_get_text call. xpos, ypos, width, height, and the snapshot filename can all be taken from the ctrx_get_text call and used in the ctrx_get_text_location call.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_text_location

This example shows the use of ctrx_get_text_location.

long x_pos, y_pos, wid, ht;

ctrx_sync_on_window("Desktop", ACTIVATE, 0, 0, 801, 601, "snapshot6", CTRX_LAST );

/* ctrx_get_text used to get coordinates and snapshot file for later call to ctrx_get_text_location */

ctrx_get_text(NULL, 289, 70, 100, 70, "snapshot1", text_buffer, CTRX_LAST );

lr_message( "%s", text_buffer );

x_pos = 289;

y_pos = 70;

wid = 100;

ht = 70;

ctrx_get_text_location(NULL, &x_pos, &y_pos, &wid, &ht, "Documents", TRUE, "snapshot1", CTRX_LAST );

lr_message( "%ld, %ld, %ld, %ld ",x_pos,y_pos, wid, ht );

if (x_pos == 0 && y_pos == 0 && wid== 0 && wid == 0 )

lr_message("'Documents' not found");

else

lr_message("'Documents' found at %d, %d, %d, %d", x_pos, y_pos, wid, ht );

Output:
Starting action Action.
Action.c(7): ctrx_sync_on_window("Desktop")
Action.c(9): ctrx_get_text(".My Documents")
.My Documents
Action.c(18): ctrx_get_text_location(319 , 116 , 52 , 8)
319, 116, 52, 8
'Documents' found at 319, 116, 52, 8

ctrx_get_window_name

Retrieves the name of the active window.

int ctrx_get_window_name( LPSTR buffer, [CONTINUE_ON_ERROR,] CTRX_LAST );

buffer	The output parameter containing the name of the window
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

Use ctrx_get_window_name to retrieve the title of the window currently in focus.

It is up to the user to allocate memory space for buffer before ctrx_get_window_name is invoked and to de-allocate the memory when no longer in use.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_window_name

The following code snippet invokes ctrx_get_window_name to retrieve the name of the window currently in focus, and verifies, using strcmp(), that it is the required window. It then executes a mouse click within the window.

char window_name[100];
long xpos, ypos, width, height;

ctrx_mouse_double_click(41, 266, LEFT_BUTTON, 0, NULL);
ctrx_get_window_name(window_name);

if (!strcmp(window_name, "Welcome to MSN.com - Microsoft Internet Explorer"))
{
ctrx_get_window_position(window_name, &xpos, &ypos, &width, &height);
ctrx_mouse_click(xpos + 35, ypos +128, LEFT_BUTTON, 0, window_name);
}

ctrx_get_window_position

Retrieves the position of a window.

int ctrx_get_window_position( LPSTR title, long *xpos, long *ypos, long *width, long *height, [CONTINUE_ON_ERROR,] CTRX_LAST );

title	The name of the window.
xpos	The output parameter containing the horizontal distance of the left edge of the window from the edge of the ICA client window
ypos	The output parameter containing the vertical distance of the top edge of the window from the edge of the ICA client window
width	The width of the window, in pixels
height	The height of the window, in pixels
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

Use ctrx_get_window_position to retrieve the position of the window with the name title. If title is NULL then the function retrieves the position of the window currently in focus.

It is up to the user to allocate memory space for all output parameters before ctrx_get_window_position is invoked, and to de-allocate the memory after it.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_window_position

The following code snippet uses ctrx_get_window_name to retrieve the name of the window currently in focus, and verifies, using strcmp(), that it is the required window. It then calls ctrx_get_window_position to retrieve the window's position and execute a mouse click within it.

char window_name[100];
long xpos, ypos, width, height;

ctrx_mouse_double_click(41, 266, LEFT_BUTTON, 0, NULL);
ctrx_get_window_name(window_name);

if (!strcmp(window_name, "Welcome to MSN.com - Microsoft Internet Explorer"))
{
ctrx_get_window_position(window_name, &xpos, &ypos, &width, &height);
ctrx_mouse_click(xpos + 35, ypos +128, LEFT_BUTTON, 0, window_name);
}

ctrx_logoff

Closes the current session.

int ctrx_logoff( int force, [CONTINUE_ON_ERROR,] CTRX_LAST );

force	Use one of the following constants - CTRX_NORMAL_LOGOFF, CTRX_FORCED_LOGOFF or CTRX_FORCED_IF_NORMAL_FAILED, entered as shown without quotes, to specify behavior of the function
CONTINUE_ON_ERROR	A constant, entered without quotes. If CONTINUE_ON_ERROR is passed, the script continues to the next step if the logoff fails.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_logoff performs a normal logoff or a forced logoff, depending on the value of the force argument:

CTRX_NORMAL_LOGOFF — Emulates real user logoff. Unresponsive applications or applications with unsaved data may prevent successful logoff. These applications may display dialog boxes with requests for actions from user, for example, to continue waiting or to close applications.

CTRX_FORCED_LOGOFF — In this mode, all applications are closed, even if there is unsaved data. The session will be ended, but some data may be lost. CTRX_FORCED_LOGOFF has an effect only if the Citrix Agent is available. If the Agent is not available, ctrx_logoff acts the same as if CTRX_NORMAL_LOGOFF were passed.

CTRX_FORCED_IF_NORMAL_FAILED — Attempts normal logoff. If logoff fails or times out, logoff is forced.

Parameterization

Standard parameterization is not available for this function.

Example: ctrx_logoff

In this example, ctrx_logoff is used to attempt a normal logoff. A forced logoff is attempted if the first attempt fails.

/* Try to perform logoff allowing all

applications to exit gracefully */

ctrx_logoff(CTRX_NORMAL_LOGOFF, CONTINUE_ON_ERROR, CTRX_LAST);

/* If normal logoff timed out, next step executes

due to CONTINUE_ON_ERROR in previous call.

Second call forces all apps to close,

even if they lose data. */

ctrx_logoff(CTRX_FORCED_LOGOFF, CTRX_LAST);

ctrx_disconnect_server("", CTRX_LAST);

ctrx_get_waiting_time

Gets current wait time.

int ctrx_get_waiting_time( long * waitTime );

waitTime

Pointer to long variable to store the wait time.

ctrx_get_waiting_time gets the current waiting time from the run time settings, or the value set with ctrx_set_waiting_time.

Parameterization

No parameterization is available for this function.

Example: ctrx_get_waiting_time

This example shows the use of ctrx_get_waiting_time.

long wTime;

.....

ctrx_get_waiting_time( &wTime);

Connection Functions

ctrx_connect_server	Logs in to a Citrix server
ctrx_disconnect_server	Disconnects a Citrix client from a Citrix server
ctrx_set_connect_opt	Sets a connection option to a Citrix ICA server and logs in to a Citrix server
ctrx_nfuse_connect	Connects to a Citrix server via an NFUSE portal

ctrx_connect_server

Logs in to a Citrix server.

int ctrx_connect_server( char *server_name, char *user_name, char *password, char *domain, [CONTINUE_ON_ERROR,] CTRX_LAST );

server_name	The name of the Citrix ICA server to which you are connecting.
user_name	The name of the user used to login to server_name
password	The password of the user used to login to server_name
domain	The domain name of server_name to which you are performing a login.
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_connect_server connects a Citrix client to a Citrix server.

Parameterization

Parameterization is available for all arguments of this function.

Example: ctrx_connect_server

In the following example, the function ctrx_connect_server connects to the server ludens.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Launch the web browser by clicking on desktop IE icon*/
     ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);
     lr_think_time(13);
     ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

     /* Exit the web browser by clicking on top left Exit check box */
     ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,
               "Welcome to MSN.com - Microsoft Internet Explorer");
     lr_think_time(13);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_disconnect_server

Disconnects a Citrix client from a Citrix server.

int ctrx_disconnect_server( char *server_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

server_name	The name of the Citrix ICA server
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_disconnect_server disconnects a client from a Citrix server.

Note: The ICA server should also be configured to disconnect from the client on a broken or timed-out connection. Refer to the section "Server Configuration" in the Virtual User Generator User Guide.

Parameterization

No parameterization is available for this function.

Example: ctrx_disconnect_server

In the following example, after connecting to the server ludens and opening Microsoft's Internet Explorer application, the function ctrx_disconnect_server disconnects from the server.

Actions () {

     ctrx_connect_server("ludens", "test", "test", "ludens");
     ctrx_wait_for_event("LOGON");

     /* Launch the web browser by clicking on desktop IE icon */
     ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL);
     lr_think_time(13);
     ctrx_set_window("Welcome to MSN.com - Microsoft Internet Explorer");

     /* Exit the web browser by clicking on top left Exit check box */
     ctrx_mouse_click(573, 61, LEFT_BUTTON, 0,
               "Welcome to MSN.com - Microsoft Internet Explorer");
     lr_think_time(12);
     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_set_connect_opt

Sets a connection option to a Citrix ICA server and then connects to server.

int ctrx_set_connect_opt( eConnectionOption option, char *value);

option	eConnectionOption
value	The option's value

ctrx_set_connect_opt sets a connection option prior to establishing a connection from a Citrix client to a Citrix server, and then executes the connection to the server.

Pass one of the following as the option argument:

APPLICATION - Use this to launch an application automatically upon login to the Citrix server. ctrx_set_connect_opt is automatically generated with this option when the "Published Application" field in the "Login Info" Recording Options is set.

NETWORK_PROTOCOL - Use this option to change to the TCP/IP+HTTP protocol when using NFUSE. ctrx_set_connect_opt is automatically generated with this option when the "Network Protocol" field in the Connection Recording Options is set.

ICAFILE - Use this to indicate the path to the ICA initialization file. ctrx_set_connect_opt is automatically generated with this option when the "File" field in the "Use ICA file for login" Recording Options is set.

CLIENT_NAME - Use this option to indicate a Citrix client name. If you do not indicate a specific name, VuGen creates a default name during recording: server username VuserID (VuserID only in Controller).

Parameterization

The parameter value can be parameterized.

Example: ctrx_set_connect_opt

In the following example, the function ctrx_set_connect_opt is invoked to start the Microsoft Windows Calculator application immediately after login to the server ludens. A further call to ctrx_set_connect_opt with the ICAFILE option directs VuGen to the script to the ICA initialization file.

Action() {

     ctrx_set_connect_opt(APPLICATION, "#calc");
     ctrx_set_connect_opt(ICAFILE, "c:\\temp\\word.ica");
     ctrx_connect_server("ludens", "test10", "test", "ludens");
     lr_think_time(8);

     ctrx_wait_for_event("LOGON");
     ctrx_set_window("Calculator");

     ctrx_mouse_click(247, 9, LEFT_BUTTON, 0, "Calculator");
     ctrx_unset_window("Calculator");
     lr_think_time(2);

     ctrx_disconnect_server("ludens");

     return 0;
}

ctrx_nfuse_connect

Connects to a Citrix server via an NFUSE portal.

int ctrx_nfuse_connect( char *url , [CONTINUE_ON_ERROR,] CTRX_LAST );

url	The NFUSE ICA file's resource url
CONTINUE_ON_ERROR	A constant, entered as shown without quotes. Overrides the error behavior run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST	A marker that indicates the end of the argument list.

ctrx_nfuse_connect establishes a connection with the Citrix server using the NFUSE application portal. Specifications found in the ICA file defining the personalized specifications of the NFUSE portal are downloaded from the server, after which the connection is made.

ctrx_nfuse_connect is automatically generated by VuGen when recording an NFUSE session.

Note: Before recording NFUSE sessions, you must enable multi-protocol recording. See "About Creating Citrix Vuser Scripts" in the Virtual User Generator User Guide.

Parameterization

No parameterization is available for this function.

Example: ctrx_nfuse_connect

The following example uses ctrx_nfuse_connect to establish a connection to the Citrix server. After filling in the login information at the NFUSE portal, ctrx_nfuse_connect is automatically generated by VuGen to retrieve information from the server (found in the ICA file) on applications available to the client. In this case, Microsoft's Excel application is configured to launch automatically.

After ctrx_nfuse_connect connects to the server, the code waits for the Excel window to appear before continuing the session.

vuser_init () {

     /* Use browser to connect to NFUSE portal */
     web_url("login.asp",
          "URL=http://concept1.mercury.co.il:8080/login.asp", LAST );

     /* Send login information */
      web_submit_data("frameset.asp",
          "Action=http://concept1.mercury.co.il:8080/frameset.asp",
          "Method=POST", "EncType=application/x–www–form–urlencoded",
          ITEMDATA,
          "Name=user", "Value=test", ENDITEM,
          "Name=password", "Value=test", ENDITEM,
          "Name=loginPage", "Value=default", ENDITEM,
          "Name=domain", "Value=ludens", ENDITEM,
          "Name=logIn.x", "Value=46", ENDITEM,
          "Name=logIn.y", "Value=14", ENDITEM, LAST );

     web_url("blank.htm",
          "URL=http://concept1.mercury.co.il:8080/blank.htm", LAST );
     web_url("applist.asp",
          "URL=http://concept1.mercury.co.il:8080/applist.asp\?NFuse_currentFolder=", LAST );

     /* Connect to Citrix server - this is automatically generated by VuGen */
     ctrx_nfuse_connect("http://concept1.mercury.co.il:8080/launch.asp\?NFuse_Application=Ex0078cel&NFuse_MIMEExtension=.ica");

     ctrx_wait_for_event("LOGON");

     /* Now wait for Excel application defined in NFUSE ICA file */
     ctrx_set_window("Microsoft Excel");
     ctrx_mouse_click(249, 32, LEFT_BUTTON, 0, "Microsoft Excel");
     ctrx_mouse_click(508, 80, LEFT_BUTTON, 0, "Microsoft Excel");
     ctrx_set_window("Microsoft Excel_2");
     ctrx_mouse_click(416, 356, LEFT_BUTTON, 0, "Microsoft Excel");
     ctrx_unset_window("Microsoft Excel_2");
     lr_think_time(2);
     ctrx_mouse_click(158, 570, LEFT_BUTTON, 0, "Microsoft Excel");
     lr_think_time(1);

     ctrx_disconnect_server("");

     return 0;
}

Performance Testing : Tips n Tricks!

Peformance Testing with Citrix Protocol : Citrix ICA Vuser Functions (CTRX)

Mouse Functions

ctrx_mouse_click

ctrx_mouse_double_click

ctrx_mouse_down

ctrx_mouse_move

ctrx_mouse_up

Keyboard Functions

ctrx_key

ctrx_type

Selection Functions

ctrx_list_select_item

ctrx_menu_select_item

Synchronization Functions

ctrx_set_waiting_time

ctrx_set_window

ctrx_set_window_ex

ctrx_sync_on_bitmap_change

ctrx_sync_on_bitmap

ctrx_sync_on_obj_info

ctrx_sync_on_text

ctrx_sync_on_text_ex

ctrx_sync_on_text_ocr

ctrx_sync_on_window

ctrx_wait_for_event

ctrx_win_exist

Information Retrieval Functions

ctrx_<obj>_get_info

ctrx_<obj>_get_info

ctrx_execute_on_window

ctrx_get_bitmap_value

ctrx_get_server_name

ctrx_get_text

ctrx_get_text_ocr

ctrx_get_text_location

ctrx_get_window_name

ctrx_get_window_position

ctrx_logoff

ctrx_get_waiting_time

Connection Functions

ctrx_connect_server

ctrx_disconnect_server

ctrx_set_connect_opt

ctrx_nfuse_connect

Comments

Post a Comment

Popular posts from this blog

Loadrunner ~ Performance Testing with Citrix Protocol : Recording Tips n Tricks!

ATM API Loadtesting with Sybase ASE using LOADRUNNER 12.60