ExampleInformation Retrieval Functions

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

Important: OCR might consume a substantial amount of the hardware resources for the load generator machine, causing high CPU consumption warnings and/or limiting the amount of Vusers that can run in parallel.

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_nameThe 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.
widthThe width of the window in pixels.
heightThe height of the window in pixels
filenameThe snapshot. Do not edit this argument.
text_bufferOutput 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_ERRORA constant entered as shown without quotes. Overrides the error behavior runtime setting for this step so that script behaves as though the runtime 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.


  • OCR should not be used for text that is small.

  • Known issue: The OCR engine removes the spaces from the recognized text.

Return Values

Citrix ICA Return Values


Parameterization is available for all arguments of this function.


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