Citrix Scripting Best practices

-By NFT COE

 Version History:-

Version Date Prepared/Modified By Reviewed by Description

V 1.0 8th May Vijayasekar Mariappan Prakash Angamuthu The Document contains
2019 (443061) (230077) information on the
common best practices to
be followed for scripting
the Citrix hosted
application using
Microfocus Loadrunner.

2
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 Table of Contents
1. Introduction .................................................................................................................................................. 5

1.1 Components of CITRIX Server ....................................................................................................................... 5

1.1.1 Citrix XenApp ............................................................................................................................................ 5

1.1.2 Citrix server ............................................................................................................................................... 5

1.1.3 Citrix Client................................................................................................................................................ 5

1.2 Version compatibility.................................................................................................................................... 6

2. Principle of Working ...................................................................................................................................... 6

2.1. At Citrix Layer ............................................................................................................................................ 6

2.2. At LoadRunner .......................................................................................................................................... 6

3. Basic Recording guidelines............................................................................................................................. 7

4. Best Practices ................................................................................................................................................ 9

4.1. Citrix Agent to be used .............................................................................................................................. 9

4.2. DEP Settings .............................................................................................................................................. 9

4.3. Deletion the Citrix Cache ......................................................................................................................... 10

4.4. Citrix Presentation Server configuration for load testing ......................................................................... 10

4.5. Working with ICA files ............................................................................................................................. 11

4.6. Synchronization ...................................................................................................................................... 12

4.7. Synchronization during recording ............................................................................................................ 12

4.8. Synchronization after recording .............................................................................................................. 13

4.9. Wildcard while using ctrx_sync ............................................................................................................... 13

4.10. Recording Options ................................................................................................................................... 15

4.10.1. Windows size under the Configuration tab ......................................................................................... 15

3
© 2019 Cognizant Controlled Copy | Cognizant Confidential
4.10.2. Window name under Recorder tab ..................................................................................................... 15

4.10.3. Save snapshot under Recorder tab...................................................................................................... 15

4.11. Keyboard vs Mouse ................................................................................................................................. 16

4.12. Window resizing ...................................................................................................................................... 17

4.13. Display settings and color resolution ....................................................................................................... 18

4.14. Recording a complete session ................................................................................................................. 19

4.15. Timeout settings ..................................................................................................................................... 19

4.16. Continue on Error setting ........................................................................................................................ 19

4.17. GDI resources .......................................................................................................................................... 20

4.18. Scripting and Modifications ..................................................................................................................... 21

4.18.1. Verifying of response .......................................................................................................................... 21

4.18.2. Increasing the wait time for connections and timeouts ...................................................................... 21

4.18.3. Error handling in a script ..................................................................................................................... 22

4.18.4. Think-times between keystrokes ........................................................................................................ 23

4.18.5. Measuring accurate response times .................................................................................................... 23

4.18.6. Increasing readability for script ........................................................................................................... 27

4.18.7. Correlate Session ID ............................................................................................................................ 27

4.18.8. Toggle Keys ......................................................................................................................................... 27

4.18.9. Lost with Citrix Error ........................................................................................................................... 29

4.18.10. Handle unexpected windows .......................................................................................................... 29

5. CITRIX Presentation Server Configuration.................................................................................................... 30

6. Common Errors encountered while CITRIX Scripting ................................................................................... 31

6.1. Error 1: Failed to Create Agent Channel .................................................................................................. 31

6.2. Error 2: Internet Explorer disappears during a Multi-protocol when ICA Client Launched ....................... 31

4
© 2019 Cognizant Controlled Copy | Cognizant Confidential
6.3. Error 2: Internet Explorer disappears during a Multi-protocol when IE Launch ....................................... 32

6.4. Error 4: Failed to get window size, wrong format .................................................................................... 35

6.5. Error 5: Recording against a drop down menu does not work ................................................................. 36

Solution: .............................................................................................................................................................. 36

6.6. Error 6: replay Citrix script against a different window size ..................................................................... 36

Solution: .............................................................................................................................................................. 36

1. Introduction

Testing a citrix application with Loadrunner is a much more complicated and cumbersome than
a web application. The very fact that Loadrunner cannot understand the response sent by the
citrix servers makes scripting and executing a challenge.

Though not the ultimate compendium, this document has an exhaustive collection of guidelines
to be followed while scripting in the citrix protocol using Loadrunner.

1.1 Components of CITRIX Server

1.1.1 Citrix XenApp

Citrix XenApp provides application virtualization by delivering applications as services to users
who are accessing it from any device from anywhere in the world. Instead of deploying any
application to a PC, each application is packaged and stored in a centralized data center. When
a user requests an application, the XenApp delivers it instantly according to the rules provided
to the user.

1.1.2 Citrix server

Citrix Server is a server where all the applications available for a particular user will be
published. The user will access the applications hosted on this server by means of a Citrix Client.
This server does all the processing and thereby letting the client act as a thin client. It provides
an illusion to the end user that the application the user accesses, is running on client. Citrix
Server allows multiple users to connect and access applications.

1.1.3 Citrix Client

Citrix client is a machine from which a user accesses the published application which is available
on a Citrix Server. The client will act as a thin client since the events such as mouse events and
key strokes are sent to the server for processing.
5
© 2019 Cognizant Controlled Copy | Cognizant Confidential
1.2 Version compatibility

The supported versions of Citrix Client/XenApp by the LR version:

LR 9.5 Citrix Server Citrix Client: Metaframe 3

Metaframe Client 9.0 Metaframe 4
Presentation Server Client 9.23 XenApp 4.5
Presentation Server Client 10 NFuse

LR11.x Citrix Server Citrix Client: Metaframe 4 NFuse

XenApp 4.5 ICA 10.2 XenApp 5.0 ICA 11 XenApp
6.0* Citrix online Plugin 12.1*

Note: Citrix Access Gateway environment is not supported on Citrix Client 12.1. But with older
client version 9, and possibly 10.2, Citrix Access Gateway environment should work fine with
these versions.

2. Principle of Working
2.1. At Citrix Layer

Citrix Presentation Server hosts the applications to users via Independent Computing
Architecture (ICA), a communication protocol develop by Citrix
 by which servers and client devices exchange data, and
 Separates an application’s logic from its user interface.
This ICA protocol encrypts and transports application’s screens from the server it is running
onto the user’s client device, and returns the user’s input to the application on the server. As an
application runs on a server, Presentation Server intercepts the application’s display data and
uses the ICA protocol to send this data to the ICA client software running on the user’s device,
increasing application performance.

2.2. At LoadRunner

Microfocus Load Runner records a Citrix script, by

 Capturing all key strokes,
 mouse clicks and
 other real interaction
 along with the screen coordinates
The objects within the Citrix session are recorded in a form of bitmap in the Microfocus
LoadRunner script.

6
© 2019 Cognizant Controlled Copy | Cognizant Confidential
Citrix scripts also require synchronization between the client and application to ensure that the
user is not ahead of the actual request. Synchronization also helps when running multiple users
and the application under test is stressed, thereby yielding slow response. It ensures that the
client and the server are always in sync.

3. Basic Recording guidelines

The following tips can make the recording streamlined:

1. When recording a session, make sure to perform the complete business process,
starting with the connection and ending with the cleanup. End your session at a
point from where you could start the entire process from the beginning
2. Always make sure that your script is able to run for multiple iterations.
e.g.
When you are done with the business flow, end up to home page or to the page
from where next user would start traversing from. Similarly, if your traversal flow
includes expanding a tree then retract it before leaving the page because
chances are likely that in next iteration the already expanded tree get retracted
on click event hence, resulting in replay failure
3. Record the connection process into the vuser_init section, and the closing
process in the vuser_end section. This will prevent you from performing
iterations on the connection process.
4. Whenever the application window pops up first time maximize it to avoid any
displacement of the same in second iteration
5. While recording sometimes, the application window might get out of focus, so
just do one mouse click anywhere in the application window title
6. Configure the Citrix server to completely close a session. Open the Citrix
Connection Configuration dialog box. Choose Start > Programs > Citrix >
MetaFrame XP > Citrix Connection Configuration. Double-click on the ica-tcp
connection name. The Edit Connection dialog box appears. Click on theAdvanced
button. In the bottom section of the dialog box, clear the inherit user config
check box adjacent to the On a broken or timed-out connection list box. Change
the entry for this list box to reset
7. After replay failure use different Login ID to login to the Citrix Server. Since each
login ID has some fixed specific session time span, logging in with the same ID
before the session time has expired would cause to take the user to same screen
where it had left when the error occurred
8. Avoid using ctrx_sync_on_bitmap() for synchronization. It is because
synchronization on bitmaps can lead to replay failure if different machine is
used.

7
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 If you still need to use ctrx_sync_on_bitmap(), then firstly, check for the
consistencies between the recorded and replay machines: Window Size
(resolution), Window Colors, System Font and the other default options settings
for the Citrix client. These settings affect the hash value of bitmaps, and
inconsistencies may cause replay to fail. To view the Citrix Client settings, select
an item from the Citrix program group and choose Application Set Settings or
Custom Connection Settings from the right-click menu. Select the Default
Options tab or make necessary changes as per your recorded machine settings.

8
© 2019 Cognizant Controlled Copy | Cognizant Confidential
4. Best Practices
4.1. Citrix Agent to be used
There are many benefits in employing Citrix agent that comes with Load Runner VUGen as a
plug-in.
Ease of scripting by making the script more readable and intuitive. This is attained by adding
object names to the new function library developed for the Citrix protocol that is used with the
Citrix Agent, i.e. ctrx_obj_mouse_click()
Provides detailed information on all objects recorded by using object names along with X,Y
coordinates, therefore making it easier for Microfocus LoadRunner to find objects during replay
Allows the visual display of the object within the snapshot to see what was selected during the
recording, which is known as the “Active Object Recognition” functionality.

4.2. DEP Settings

The following DEP settings should be considered for the Citrix protocol recording.

Disable the DEP

Validate the DEP under Performance of “Advanced” tab. Right click on My Computer, select
Properties and choose “Advanced” tab and click Edit under “Performance”. Select the “Data
Execution Prevention” tab
a. Enable the ‘Turn on DEP for essential Windows Programs and Services Only’
b. Uncheck ‘Turn on DEP for all programs and services except those I select’
Enabling the first option against the second is called as Disabling the DEP

Disable the DEP – 2nd part

a. Right click on My computer.
b. Select Properties.
c. Select the Advanced tab.
d. Click Settings under Startup and Recovery.
e. Click Edit.
f. The boot.ini file will open. It should look like the following:
=================
[boot loader]
timeout=5
default=multi(0)disk(0)rdisk(0)partition(1)WINDOWS
[operating systems]

9
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 multi(0)disk(0)rdisk(0)partition(1)WINDOWS="Microsoft Windows XP Professional" /noexecute=optin
/fastdetect
C:CMDCONSBOOTSECT.DAT="Microsoft Windows Recovery Console" /cmdcons

======================
g. Change the setting noexecute=optin TO noexecute=AlwaysOff
h. Reboot your machine.

4.3. Deletion the Citrix Cache

The Citrix cache has to be deleted both from the ‘Application Data’ folder and the Registry.

If the cache is not cleared, the following kind of error messages may occur:
 Error: Connect cannot be established - Last Error=70, Last client error=1030
 Error: Failed to create channel agent

4.4. Citrix Presentation Server configuration for load testing

Citrix Presentation Server must be configured to close the session when inactive or because of
an unexpected break in connectivity from the client. Terminating the session completely will
ensure that a new clean session is started each time the user fails or tries to reconnect to the
server.
If the setting to terminate the connection is not enabled, the user will connect to the last
session and be placed in the old workspace. This setting is critical to successful playback of the

10
© 2019 Cognizant Controlled Copy | Cognizant Confidential
script also, and the setting can be changed on the server by using the Citrix server console
illustrated below.

4.5. Working with ICA files

There two ways that LoadRunner establishes a connection with the Citrix server during
recording and playback.
 The recording options of VUGen provide an option to enter the server/user
details or
 the Citrix ICA to connect to the Citrix server. The ICA file contains
configuration information for the application accessed through the Citrix
client
The ICA file should conform to the following format:
[WFClient]
Version=2
11
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 TcpBrowserAddress=10.2.248.109
PersistentCachePath=C:\Documents and Settings\udhay\Application
Data\ICAClient\Cache
[ApplicationServers]
Team Status=
[Team Status]
Address=Team Status
InitialProgram=#Team Status
ClientAudio=On
AudioBandwidthLimit=2
Compress=On
TWIMode=On
DesiredHRES=800
DesiredVRES=600
DesiredColor=4
TransportDriver=TCP/IP
WinStationDriver=ICA 3.0
ScreenPercent=0
Username=administrator
Password=00054c3b122d15
Domain=corpdev1

4.6. Synchronization
During the script execution it is important to synchronize the user steps with the application
response to ensure successful playback of the script. Synchronization allows the virtual user to
wait for a certain event to occur before moving onto the next step.
Synchronization in the script will make sure that a window or object is returned by the Citrix
server, and available for the user to execute the next step.
For example, it is necessary to ensure that the “Create Customer” form window appears on the
screen before you can enter customer information.

4.7. Synchronization during recording

Synchronization can be added into the script during recording. It can be inserted for text on the
screen or the bitmap. The recording toolbar provides two buttons at the end. The first button
allows the synchronization function to be interested on the bitmap, and the second button for
the text. The snapshot is below:
12
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.8. Synchronization after recording
Synchronization can be added after the recording by going into the Tree view of the script and
clicking on the step with the object snapshot that needs to be synchronized. Once the snapshot
is displayed, right-click on the object and select the type of synchronization that needs to be
inserted.
 Insert Sync on Text – waits until the specified text is displayed on the screen
 Insert Sync on Object Info – waits until an objects attributes have the
specified values
Depicted in the snapshot below.

Insert Sync on Object will display this:

4.9. Wildcard while using ctrx_sync

Wildcards, or asterisks (*), can be used in defining window names. This is very useful when the
window name is dynamic and changes during the replay. Depicted in the Snapshot below:

13
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 14
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.10.Recording Options
Few recording options listed below that were taken into consideration before recording the
script.

4.10.1. Windows size under the Configuration tab

The window sizing configuration should be identical to the display setting that is used for the
script recording machine (VUGen) and the load generator. This setting enables Microfocus
LoadRunner to display the windows in the size selected from the dropdown menu

4.10.2. Window name under Recorder tab

This option allows the script to be recorded with a pre-determined prefix or suffix for the
window name. This is especially useful when the window name returned by the Citrix server is
dynamic in nature. Use Wildcards also.

4.10.3. Save snapshot under Recorder tab

Saving snapshot during recording is a good practice and should be utilized whenever possible.
This setting slows the recording process and allows the user to correlate the user step within
the script with the visual snapshot.

15
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.11.Keyboard vs Mouse
LoadRunner captures mouse clicks and key strokes as they are emulated at the time of playback
to simulate users performing an action. The mouse clicks are recorded based on the object
name and the X,Y coordinates of the screen and accordingly, during the play back, LoadRunner
sends instructions to the Citrix server to emulate these mouse clicks based on the object name
and the X,Y coordinate. The emulation of the virtual user based on the X,Y coordinates can be
unreliable and if the coordinates do not match accurately, the script will fail!
e.g.
ctrx_obj_mouse_click ("<class=Button text=Close>", 331, 308, LEFT_BUTTON, 0, CTRX_LAST);
Proposed Solution:
Use the keyboard instead of the mouse whenever possible during the recording. This avoids the
recording of X,Y screen coordinates in the script and sends the key strokes directly to the Citrix
server.
This is well depicted in the snapshot below where mouse clicks are avoided as much as possible
and keystrokes are used.

16
© 2019 Cognizant Controlled Copy | Cognizant Confidential
A list of usable keys:

SHIFT_KEY PAGE_DOWN_KEY
CTRL_KEY END_KEY
ALT_KEY HOME_KEY
BACKSPACE_KEY LEFT_ARROW_KEY
TAB_KEY UP_ARROW_KEY
ENTER_KEY RIGHT_ARROW_KEY
PAUSE_KE DOWN_ARROW_KEY
ESC_KEY NUM_LOCK_KEY
CAPS_LOCK_KEY PRINT_SCREEN_KEY
PAGE_UP_KEY PAGE_DOWN_KEY
SHIFT_KEY

4.12.Window resizing
It is recommended to not resize the window during recording although it is supported by
LoadRunner. The resizing changes the screen coordinates of the objects that are contained in
the window.
Instead, the window can be resized after the recording by going into Tree view, selecting the
appropriate step, right-clicking and selecting Properties. The Properties window will be
displayed with the width and height coordinates that can be changed as needed.

17
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.13.Display settings and color resolution
The display setting of the load generators and the screen resolution should be exactly the same
as when the script was recorded.

18
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.14.Recording a complete session
When recording a script, it should be ensured to perform the complete business process from
beginning to end. The end should include the session clean up by logging out of the
application. This will make sure that the session is cleaned up upon exit, and all windows are
closed.
The start and end conditions should always be the same so that the script can start where it
ended.

4.15.Timeout settings
Connect time allows the user to wait idle after establishing the connection for the period
specified. This setting should be default unless the Citrix authentication is slow in response.
The Waiting time setting applies globally to all synchronizations within the script and can be
changed programmatically by using the ctrx_set_waiting_time() function. Depending on the
server response, the wait time should be adjusted on an “as needed” basis.

For our application, we changed the following

Connect time: 1000
Waiting time: 9999 (can be changed by editing default.cfg manually opening in notepad)
We found this working optimally.

4.16.Continue on Error setting

The Continue on Error option allows the script or individual functions within the script to
continue when the error occurs or the synchronization fails. This has helped us greatly.
Continue on Error can be used for individual functions by adding the lr_continue_on_error()
function prior to the synchronization function, allowing the virtual user to continue when the
19
© 2019 Cognizant Controlled Copy | Cognizant Confidential
specific steps fail while further action can be taken such as trapping the error or sending a
message to the log file for debugging purposes.

4.17.GDI resources
Citrix virtual users use graphics device interface (GDI) resources on the load generators.
The GDI resources are limited on each machine, and are determined by the operating system.
GDI resources are also tied to the individual session running on the system.
The Microsoft Windows 2000 operating system has a maximum of 16,384 GDI resources
available. However, these resources are also used by other applications running on the
machine, so the numbers of users that can be executed are primarily determined by the
available GDI resources.
It is recommended to use 20-25 users max on a Load Generator.
Identified Tip:
In order to increase the number of citrix users on the load generator, a remote desktop
protocol (RDP) connection can be opened and connect to the individual RDP sessions as Load
Generator. This can be achieved by checking “Enabling Terminal Services” in Load Generator
Information from the LoadRunner Controller.
Each RDP session maintains its own GDI resources; if three RDP sessions are established on the
Load Generator, each can execute 25 users.

In LoadRunner Controller.

20
© 2019 Cognizant Controlled Copy | Cognizant Confidential
  Note: Starting an RDP session on the Load Generator will consume memory and CPU on that
machine, thus limiting the number of users in other areas.

4.18.Scripting and Modifications

4.18.1. Verifying of response
Similar to text checks in other protocols ctrx_sync_on_bitmap is used to verify if the correct
page is displayed.
The input parameters for this function are
 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
lower 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
This bitmap is actually a section of the screen and hash is an encoded string that represents the
bitmap
For eg:

Above image gets converted to “18d962dcbf373e948e83489a19419512” in the script.

This is precisely why we need to pre-set the color quality and the screen resolution. A single
change in either of these parameters and the hash value will change resulting in script failure
Even with these settings in place, there are chances that that the bitmap returned might not be
exactly as expected. To take care of this, use the following setting in the script:
Run-Time Setting -> Citrix -> Synchronization.

4.18.2. Increasing the wait time for connections and timeouts

As with most applications, as the load increases, the response time also shoots up. This implies
that the application under test takes longer to connect and might even respond slowly. To

21
© 2019 Cognizant Controlled Copy | Cognizant Confidential
make sure that we capture the proper response times and not terminate the script pre-
maturely, use the following setting for Run-time setting -> Citrix -> Synchronization.

4.18.3. Error handling in a script

Unlike web applications where a session is usually terminated when the client’s web browser
window is closed, citrix applications still retain the session until the user explicitly logs out from
the application.
This poses a new challenge in scripting, where-in one has to handle all the errors that come up
to make sure that the script ‘gracefully’ exits from the application under any circumstance and
be ready for the next iteration.
Error handling includes checking for
 Incorrect window names
 Incorrect pages
 Incorrect data retrieved
and then taking corrective action/steps to reach the initial state.

22
© 2019 Cognizant Controlled Copy | Cognizant Confidential
What makes the need for error handling even more pressing is that if a transaction fails in the
script and is not handled, the vuser assigned to the erring script might not be able to go ahead
the remaining iterations.

4.18.4. Think-times between keystrokes

Since all the hits in a citrix script are actual keystrokes, it is a good idea to give some think time
between key-strokes. The think-time need not be large. It can be as small as 1 sec between key
strokes.
For eg:

This ensures that the script does not traverse through the application too quickly and there by
reducing the chance of skipping a field or tab.
Another issue that might occur is typing too fast. This can be controlled by setting RTS -> Citrix -
> Synchronization
The value set is actually the delay (in milliseconds) between keystrokes

4.18.5. Measuring accurate response times

One of the main disadvantages of citrix is that, unlike other protocols, it does not give any way
to measure response times. So this calls for a little bit of coding to measure the response times.

 Type 1

23
© 2019 Cognizant Controlled Copy | Cognizant Confidential
Steps to follow
1. Create a parameter file called ‘timerVal’ with the following properties

Save this parameter to a variable called ‘etime’

This variable will now contain the current time that is offset by 2 min. This is the upper time-
limit to wait for before timing out.
2. In a Do-While loop place the condition to be checked for successful page
loading

24
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 3. Create another parameter called ‘stime’ which will contain the current time
4. Place an ‘if’ condition to check if stime = etime. If found equal, break and fail
the transaction, else break and continue
This can be done every time a response time has to be measured.

 Type 2
Another way to capture accurate response time is by using ctrx_sync_on_bitmap_change.
For eg:

As seen in the above code snippet, after the ‘Enter Key’ is pressed, the script will wait for the
bitmap to change in the input coordinates before continuing forward. This is also another
effective way to measure response times.

25
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 26
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.18.6. Increasing readability for script
Since citrix works on mouse clicks and key strokes, there will be many occasions where the
script has to traverse through multiple fields to reach the target field by tabbing. Instead of
writing each and every ‘TAB’ command in a new line, group them in a for loop as shown below

Not only does this increase the readability of the script but also makes any script changes easier
and more importantly reduces the length of the script

4.18.7. Correlate Session ID

Ensure that the Session Token is CORRELATED – So the script looks as below
ctrx_nfuse_connect("https://myapps.mhf2.mhf.mhc/Citrix/XenApp/site/launch.ica?CTX_Applic
ation=Citrix.MPS.App.Xen5Farm.TM1%20S%26P%20-%20QA%20-
%20FP3&CTX_Token={SessionToken}&LaunchId=1300870075822", CTRX_LAST);
The correlation has to happen just before logging in to the Citrix Interface

4.18.8. Toggle Keys

Another important thing to remember is that while a test execution is in progress; do not toggle
the Num Lock, Caps Lock or the Scroll Lock key as it will affect the script execution.

Pre-execution validation
Ensure that the below in the Registry at the mentioned path or set the value accordingly

27
© 2019 Cognizant Controlled Copy | Cognizant Confidential
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All
Regions\Lockdown\Virtual Channels\Third Party\CustomVC
"VirtualChannels"=""

Execution guidelines
During execution of multi user executions in loadrunner with Citrix, follow the below guide lines
1. Before running any test execution, debug critical scripts in the controller with the
following setting. This option may be set at Script (in controller) -> Details ->
More
In the command line, enter”-lr_citrix_vuser_view

2. Other run time settings should be enforced are “Generate snapshot on error”
3. To prevent overloading by multiple vusers while connecting, set an initialization
quota or use a ramp up schedule from the Controller’s scheduler
4. For best results, do not disable think time in the Run-Time settings. Think time is
especially relevant before the ctrx_sync_on_window and ctrx_sync_on_bitmap
functions, which require time to stabilize
5. Use the function ctrx_set_waiting_time before wait functions to set the desired
waiting time as shown in below snapshot. The parameters connect and waiting
timeout in runtime settings apply only for connection event and synchronization
functions, respectively and not for wait functions

28
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 4.18.9. Lost with Citrix Error
Following code is helpful when you are lost in a Citrix error where expected windows are not
appearing where they are supposed to, or they are not the right ones. Many times this will help
you expose just what the window and X/Y coordinates are that are causing a problem. At the
top of the script initialize the variables, and when you get to a portion of the code where a
problematic window has been stopping the script, place the ctrx_get_window_name and
ctrx_get_window_position right before it.
charwindow_name[100];

long xpos, ypos, width, height;

ctrx_get_window_name(window_name);

ctrx_get_window_position(window_name, &xpos, &ypos, &width, &height);
lr_output_message("Window = %s. x= %ld, y= %ld, width= %ld, height = %ld",
window_name, xpos, ypos, width, height);

4.18.10. Handle unexpected windows

The ctrx_execute_on_window is a great way to handle unexpected screens that might appear
anywhere in your script. If you know there is a chance you will get hung on an unexpected
screen, you can always code a separate function to use some known key sequence that can be
used to get out safely (the example below uses the ENTER key). A function called
enterkey_form_handler has been created and put into vuser_init section of the script in the
VERY TOP before the vuser_init() is made:
Intenterkey_form_handler(char win_title[]) {


ctrx_key("ENTER_KEY", 0, "snapshot130", CTRX_LAST);


return 0;
}
Then, this line of code is added in the action section just under the variable declaration:
ctrx_execute_on_window("Window Title One", enterkey_form_handler);
If you know what the window titles are for the majority of your application, and you have the
time, you can begin to "object orient" your code by creating a header file with a bunch of your
29
© 2019 Cognizant Controlled Copy | Cognizant Confidential
own custom functions to handle the window forms with their various key strokes and mouse
clicks. This header can then be included and referred to with every new script.
It could make more maintainable scripts for long term projects when things are still changing.
Only handler functions would need modification for a specific form without having to redo the
entire script.

5. CITRIX Presentation Server Configuration

Citrix Presentation Server must be configured to close the session when inactive or because of
an unexpected break in connectivity from the client. Terminating the session completely will
ensure that a new clean session is started each time the user fails or tries to reconnect to the
server. If the setting to terminate the connection is not enabled, the user will connect to the
last session and be placed in the old workspace. This setting is critical to successful playback of
the script, and the Citrix administrator can change the setting on the server by using the Citrix
server console illustrated below.

30
© 2019 Cognizant Controlled Copy | Cognizant Confidential
6. Common Errors encountered while CITRIX Scripting
6.1. Error 1: Failed to Create Agent Channel

Solution:
If you receive this error while recording or while replaying with Citrix Client 10.x, then we might
need to update the registry with the following patch. Please double click on this patch file and
then click OK to update the registry content.

Content:
The content of the above Citrix.reg file if we open it in notepad is as follows.

**********************

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All

Regions\Lockdown\Virtual Channels\Third Party\CustomVC]

"VirtualChannels"=""

[HKEY_CURRENT_USER\SOFTWARE\Citrix\ICA Client\Engine\Lockdown Profiles\All

Regions\Lockdown\Virtual Channels\Third Party\CustomVC]

"VirtualChannels"=""

************************************

6.2. Error 2: Internet Explorer disappears during a Multi-protocol when ICA Client
Launched

Internet Explorer disappears during a Multi-protocol Nfuse recording as soon as the Citrix ICA
client is launched.

Solution:
Check to see if the machine has been set up to record against multiple processes. Go to the
registry editor to

31
© 2019 Cognizant Controlled Copy | Cognizant Confidential
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Windows\AppInit_DLLs

and check to see if it’s pointing to bbhook.dll. If it is then remove the entry and then reboot the
machine.

6.3. Error 2: Internet Explorer disappears during a Multi-protocol when IE Launch

Internet Explorer disappears or crashes during a Multi protocol Nfuse recording as soon as the
browser is launched.

Solution:
Check to see if the machine has any Anti-Virus software running. Try shutting down the Anti-
Virus services. If you have McAfee Anti-Virus installed, shut down the following services:

 AVSyncManager
 McShield

If you have Norton Anti-Virus installed, shut down the Norton Antivirus service from the
services menu.

For Windows 2000 machine, go to Start  Settings  Control Panel  Administrative

Tools  Services.

For Windows NT machine, go to Start  Settings  Control Panel  Services.

Frequently used Scenario:

On facing any of the above 2 errors, Error 2 and Error 3; and if the given solution could not be
applied due to organizations security policies, the below mentioned steps can be followed to
create a multi protocol script:

1. Create a Web http/html script, and record the business process to the click on the icon of the
published Citrix application. Since this script does not include Citrix_ICA, the Citrix AUT will not
launch.

2. Stop the recording, and add these two variable declarations at the top of the Action() block:

32
© 2019 Cognizant Controlled Copy | Cognizant Confidential
Action()
{
int fp;
char * icafile;

3. In the recorded script, near the end, you should find a statement similar to this which is the
result of your click on the application icon (note: this script used URL-mode, yours may be
different):

web_url("launcher.aspx",
"URL=http://myCitrixServer.com/Citrix/AccessPlatform/site/launcher.aspx?NFuse_Application=
Citrix.MPS.App.PCFARM.Calc_Virtpc1&LaunchId=1259608978284",
"TargetFrame=",
"Resource=1",
"RecContentType=application/x-ica",
"Referer=http://myCitrixServer.com/Citrix/AccessPlatform/site/applist.aspx",
"Snapshot=t6.inf",
LAST);

4. Add this code above the web_url() in step 3 above, to capture the ICA file resulting from the
request:

web_reg_save_param("icadata", "LB=WFClient", "RB=", LAST);

5.Add this code below the web_url()in step 3 above , to save the ICA file to a local disk:

icafile = (char *)malloc(strlen(lr_eval_string(" {icadata}")) + 100);

sprintf(icafile,"[WFClient%s",lr_eval_string("{icadata}"));
fp = fopen("C:\\\icafile.ica", "w");
fprintf(fp, icafile);
fclose(fp);

6. The completed code should look like this:

Action()
{
int fp;
char * icafile;

// …
// … Other recorded code removed to improve clarity of this KB
// …

33
© 2019 Cognizant Controlled Copy | Cognizant Confidential
web_reg_save_param("icadata", "LB=WFClient", "RB=", LAST); // Added: will save the returned
ICA file data in a parameter

web_url("launcher.aspx", // As-recorded ; this results from clicking the application icon

"URL=http://myCitrixServer.com/Citrix/AccessPlatform/site/launcher.aspx?NFuse_Application=
Citrix.MPS.App.FARM.Calc&LaunchId=1259608978284",
"TargetFrame=",
"Resource=1",
"RecContentType=application/x-ica",
"Referer=http://myCitrixServer.com/Citrix/AccessPlatform/site/applist.aspx",
"Snapshot=t6.inf",
LAST);

// code below saves the parameter data onto the local C:\ drive, as an ICA file.

icafile = (char *)malloc(strlen(lr_eval_string(" {icadata}")) + 100);

sprintf(icafile,"[WFClient%s",lr_eval_string("{icadata}"));
fp = fopen("C:\\\icafile.ica", "w");
fprintf(fp, icafile);
fclose(fp);

return 0;
}

7. Replay the modified script, which will save the ICA file to the local disk.

NOTE:
You will next use this ICA file to record the Citrix ICA portion of your script. Ensure any
errors are resolved before moving on.

8. Edit the saved ICA file with a text editor, removing the line "RemoveICAFile=yes" from the
ICA file, if it is present. Save the ICA file, exit the editor.

9. Ensure you can use this ICA file to launch your Citrix AUT (outside of VuGen). If your Citrix
Program Neighborhood ICA client is installed properly, you should be able to double-click on
this ICA file with Windows Explorer to launch this Citrix application.

10. Next, create a new, single-protocol Citrix ICA script. In the recording options, use this ICA
file saved earlier, and record the complete Citrix portion of your Business Process.

11. After recording the Citrix ICA portion, stop recording and examine the script. In the Action()
block, you will see reference to the ICA file in the ctrx_set_connect_opt() call:

34
© 2019 Cognizant Controlled Copy | Cognizant Confidential
ctrx_set_connect_opt(ICAFILE,"C:\\\icafile.ica"); // this is the ICA file you captured to disk.
ctrx_wait_for_event("LOGON", CTRX_LAST);
lr_think_time(5);

//The code below is just a simple example, an AUT being launched and exited.
//Your Citrix Business Process recording may produce more code.

ctrx_sync_on_window("Calculator", ACTIVATE, 88, 88, 261, 253, "snapshot1", CTRX_LAST);

ctrx_obj_mouse_click("<class=SciCalc >", 249, 8, LEFT_BUTTON, 0, "Calculator=snapshot2",
CTRX_LAST);
ctrx_disconnect_server("”ô\x12", CTRX_LAST);
return 0;
}

12. Ensure this Citrix portion of your business process replays properly before proceeding.

13. Now, create a new Citrix ICA + Web http/html multi-protocol script.

14. Copy the Web HTTP/HTML script you replayed to capture the ICA file — into the top of the
Action block.

15. Copy the Citrix ICA script code you recorded in the Citrix part, appending it to the end of the
Action block (note : the full example not included here for simplicity).

16. Replay this script ensuring it replays successfully. Each time the script runs, it should
dynamically download the ICA file to disk.

NOTE: If the merged Web+Citrix ICA script fails during replay with the following error
immediately:

6.4. Error 4: Failed to get window size, wrong format

Error: Failed to get window size, wrong format.

Citrix client replay version 11.0.0.5357 , record version
Warning: Extension CitrixClientImpl.dll reports error -1 on call to function ExtPerThreadInitialize
Error: Vuser failed to initialize extension CitrixClientImpl.dll.
Vuser Terminated.

Solution:

Open the problematic Web+Citrix ICA script's default.cfg file (in the root of the Script directory)
in a text editor (like notepad).

35
© 2019 Cognizant Controlled Copy | Cognizant Confidential
Search in the default.cfg file for a section starting with "[Citrix]" similar to this:

[Citrix]
Latency=Use Server Default
Compression=1
Cache=0
Queue=0
Sound=Use Server Default
BitmapSyncLevel=Exact

NOTE: Notice above that the Citrix section is all lower case. The above section is incorrect.
Replace the entire citrix section with the following:

[CITRIX]
DesktopColors=16
Colors=High Color (16 bit) // can be modified based on the setting during recording
Enctyption=Use Server Default
Window=800 x 600 // can be modified based on the resolution settings used for recording

NOTE: Ensure there is not both a "[CITRIX]" and "[Citrix]" section! The only section that should
be present is the above "[CITRIX]" section!

Save the script. This should enable the script to replay without the error.

6.5. Error 5: Recording against a drop down menu does not work

During replay it fails on the ctrx_mouse_click when it is supposed to select an item from the
drop down.

Solution:
Use arrow keys or if the item is known you can type the text in the box of the drop-down
instead of mouse click to select an item from the drop down during recording.

6.6. Error 6: replay Citrix script against a different window size

Replying Citrix script against a different window size

Solution:
Go to the script directory in Windows Explorer. Open the default.cfg file located inside the
script directory and change the window= value under the [CITRIX] section to a valid value that
can be seen in the recording options (640 x 480, 800 x 600, 1024 x 768, 1280 x 1024 and 1600 x
1200). Please note that if you have any ctrx_sync_on_bitmap functions recorded it will not
replay in the new window setting because the hash value will be different.
36
© 2019 Cognizant Controlled Copy | Cognizant Confidential
 Thank You

37
© 2019 Cognizant Controlled Copy | Cognizant Confidential