General & Logical Functions


  • IF Returns one value if a condition evaluates to TRUE, and another value if that condition evaluates to FALSE.
  • CHOOSE Uses index number to return a value from the list of value arguments.
  • EVAL Evaluates a string as an expression.
  • RAND Returns a pseudorandom number.

  • LICENSEHASH Gets the hash value of the license.
  • VER Gets the version number of Player.
  • ISDEMOVERSION Determines whether the current is trial copy.
  • ISSELFEXE Determines whether the macro is running in EXE mode.
  • DEBUGMODE Determines whether the macro is running in debug mode.
  • GET_PROGRESSWND Retrieves the window value of play progress window.

  • ISMACRORUNNING Tests if a macro is running.
  • MACRO_COUNT Counts the number of running instances of a macro.
  • ISADMIN Test if the current player process has the administrator privilege.
  • ISNUMBER Returns a boolean value indicating whether an expression can be converted to a number.
  • ISDATE Returns a boolean value indicating whether an expression can be converted to a datetime value.
  • ISBOOL Returns a boolean value indicating whether an expression can be converted to a boolean value.

  • TOSTRING Converts an expression into a string.
  • TONUMBER Converts an expression into a number.
  • TODATE Converts an expression into a date value.
  • TOBOOL Converts an expression into a boolean value.
  • TOHEXSTR Convert a number into hexadecimal representation.
  • XLSCOL_TONAME Converts an index number to the Microsoft Excel column name.
  • XLSCOL_TOINDEX Converts a Microsoft Excel column name to an index number.

  • UBOUND Returns the highest available subscript for the indicated dimension of an array.
  • KEY_ISPRESSED Retrieves if the specified key is pressed.
  • KEY_ISTOGGLED Retrieves if the specified key is toggled.

  • GETCARET_X Gets x-coordinate of the caret.
  • GETCARET_Y Gets y-coordinate of the caret.
  • GET_SCREEN_WIDTH Retrieves width of the screen.
  • GET_SCREEN_HEIGHT Retrieves height of the screen.
  • GETMOUSEPOINTER Gets the mouse pointer shape.
  • CLIPBOARD_GET Retrieves the content of clipboard.

  • GET_SHAREDATA Retrieves the shared data of running macro.
  • PUT_SHAREDATA Shares a data to other running macros.

  • The follow functions are only available in the enterprise edition.

  • OCR Recognizes and retrieves characters from an image by using Microsoft MODI component.
  • OCR2 Recognizes and retrieves characters from an image.

IF

Returns one value if a condition evaluates to TRUE, and another value if that condition evaluates to FALSE.

value IF( logical_exp, [value_if_true, value_if_false] )

Note: If the value_if_true argument or value_if_false is omitted, the boolean value TRUE or FALSE will be returned.

Examples:

IF( 20 > 10, "OK", "FALSE" ) //return the string "OK"
IF( 20 < 10, "OK", 100 ) //return the number 100
IF( 20 < 10 ) //return the boolean value FALSE because the parameter value_if_false is omitted.

CHOOSE

Uses index number to return a value from the list of value arguments.

value CHOOSE( exp_of_index_number, value1, [value2, ...] )

Note: If exp_of_index_number is 0, CHOOSE returns value1; if it is 1, CHOOSE returns value2; and so on. If exp_of_index_number is less than 0 or greater than the number of the last value in the list, CHOOSE causes an error.

Examples:

CHOOSE( 3 - 3, "One", "Two", "Three", "Four" ) //return the string "ONE"

EVAL

Evaluates a string as an expression.

EVAL( string_of_expression )

Example:

EVAL( "20+30*2" ) //Returns the number 80
EVAL( "#12/2/2015# + 1" ) //Returns the date value 12/2/2015
EVAL( "strlen(v_name)+2" ) //Returns the length of the variable "v_name" plus 2.

RAND

Returns a pseudorandom number.

number RAND( [num_min, num_max] )

Note: The default value of the optional parameter num_min is zero, and the num_max is 2147483647.

LICENSEHASH

Returns a pseudorandom number. The function will return an empty string if this copy is not licensed.

string LICENSEHASH()

VER

Gets the version number of Player.

number VER()

ISDEMOVERSION

Determines whether the current is trial copy.

boolean ISDEMOVERSION()

ISSELFEXE

Determines whether the macro is running in EXE mode.

boolean ISSELFEXE()

DEBUGMODE

Determines whether the macro is running in debug mode.

boolean DEBUGMODE()

GET_PROGRESSWND

Retrieves the window value of play progress window. This function is useful when an application needs to know if the player is running or not.

window_value GET_PROGRESSWND()

ISNUMBER

Returns a boolean value indicating whether an expression can be converted to a number.

boolean ISNUMBER( expression )

ISMACRORUNNING

Return TRUE if a macro is running. The default value of the parameter is_macro_file is FALSE.

boolean ISMACRORUNNING( macro_name_or_file [, is_macro_file] )

MACRO_COUNT

Counts the number of running instances of a macro. The default value of the parameter is_macro_file is FALSE.

number MACRO_COUNT( macro_name_or_file [, is_macro_file] )

ISADMIN

Returns a boolean value indicating whether the current player process has the administrator privilege.

boolean ISADMIN()

ISDATE

Returns a boolean value indicating whether an expression can be converted to a datetime value.

boolean ISDATE( expression )

ISBOOL

Returns a boolean value indicating whether an expression can be converted to a boolean value.

boolean ISBOOL( expression )

TOSTRING

Converts an expression into a string.

string TOSTRING( expression, [num_digits] )

Note: The optional parameter num_digits is only available when the first parameter is a number.

Examples:

TOSTRING( 20.4567 ) //return the string "20.4567"

TOSTRING( 20.4567, 2 ) //return the string "20.45"

TONUMBER

Converts an expression into a number.

number TONUMBER( expression )

TODATE

Converts an expression into a date value.

datetime TODATE( expression )

TOBOOL

Converts an expression into a boolean value.

boolean TOBOOL( expression )

TOHEXSTR

Convert a number into hexadecimal representation.

string TOHEXSTR( number, [bool_upper] )

Note: The default value of the optional parameter bool_upper is FALSE.

Examples:

TOHEXSTR( 106 ) //return the string "6a"

TOHEXSTR( 106, TRUE ) //return the string "6A"

XLSCOL_TONAME

Converts an index number to the Microsoft Excel column name.

string XLSCOL_TONAME( index_number )

Examples:

XLSCOL_TONAME( 0 ) //return the string "A"

XLSCOL_TONAME( 26 ) //return the string "AA"

XLSCOL_TOINDEX

Converts a Microsoft Excel column name to an index number.

number XLSCOL_TOINDEX( column_name )

Examples:

XLSCOL_TOINDEX( "A" ) //return the number 0

XLSCOL_TOINDEX( "AA" ) //return the number 26.

UBOUND

Returns the highest available subscript for the indicated dimension of an array.

number UBOUND( array_name, [rank] )

Examples:

For an array v_A[10, 5], the function UBOUND returns the following value. UBOUND( v_A ) //return the number 9
UBOUND( v_A, 2 ) //return the number 4.

You can use UBound to determine the total number of elements in an array, but you must adjust the value it returns by adding 1 since the subscripts start at 0. The following expression calculates the total size of the array v_A.

( UBOUND( v_A, 1 ) + 1 ) * ( UBOUND( v_A, 2 ) + 1 ) //return the number 50.

KEY_ISPRESSED

Retrieves if the specified key is pressed.

boolean KEY_ISPRESSED( key_value )

The parameter key_value specifies the virtual-key value or the key name (see Virtual-key values and names) . The key name should be quoted by the quotation marks.

Example:

KEY_ISPRESSED( 0x27 ) //Return TRUE if the key ESCAPE is pressed. 0x27 is the virtual-key value of ESCAPE key in the hexadecimal form.
KEY_ISPRESSED( 'ESCAPE' ) //Return TRUE if the key ESCAPE is pressed.
KEY_ISPRESSED( 'A' ) //Return TRUE if the key A pressed.

KEY_ISTOGGLED

Retrieves if the specified key is toggled.

boolean KEY_ISTOGGLED( key_value )

The parameter key_value specifies the virtual-key value or the key name (see Virtual-key values and names) . The key name should be quoted by the quotation marks.

Example:

KEY_ISPRESSED( 0x14 ) //Return TRUE if the CAPS LOCK is on.
KEY_ISPRESSED( 'CAPS LOCK' ) //Return TRUE if the CAPS LOCK is on.

GETCARET_X

Gets x-coordinate of the caret. If there is no caret showed on the screen, -1 will be returned.

number GETCARET_X()

GETCARET_Y

Gets y-coordinate of the caret. If there is no caret showed on the screen, -1 will be returned.

number GETCARET_Y()

GET_SCREEN_WIDTH

Retrieves width of the screen.

number GET_SCREEN_WIDTH( [is_desktop_width] )

The parameter is_desktop_width is an optional, TRUE indicates to return the desktop width, and FALSE to return the width of the primary display monitor.

GET_SCREEN_HEIGHT

Retrieves height of the screen.

number GET_SCREEN_HEIGHT( [is_desktop_height] )

The parameter is_desktop_height is an optional, TRUE indicates to return the desktop height, and FALSE to return the height of the primary display monitor.

GETMOUSEPOINTER

Gets the mouse pointer shape. If the mouse pointer is a custom shape by application, the function will return an empty string.

string GETMOUSEPOINTER()

The return value may be one of the following:

  • ARROW Standard arrow
  • IBEAM I-beam
  • WAIT Hourglass
  • CROSS Crosshair
  • UPARROW Vertical arrow
  • SIZEALL Four-pointed arrow pointing north, south, east, and west
  • SIZENWSE Double-pointed arrow pointing northwest and southeast
  • SIZENESW Double-pointed arrow pointing northeast and southwest
  • SIZEWE Double-pointed arrow pointing west and east
  • SIZENS Double-pointed arrow pointing north and south
  • NO Slashed circle
  • HAND Hand
  • HELP Arrow and question mark
  • APPSTARTING Standard arrow and small hourglass

OCR

Recognizes and retrieves characters from an image by using Microsoft MODI component. This function is only available in the enterprise edition.

string OCR( img_file [, language_id] )

This function invokes the feature of Microsoft MODI comonment which is available in Microsoft Office 2010.

OCR2

Recognizes and retrieves characters from an image. This function is only available in the enterprise edition.

string OCR2( img_file, trained_data_file_name [, trained_data_path, white_list_of_characters] )

If the parameter trained_data_file specifies a path, be sure to use an empty string for the parameter trained_data_path.

The traineddata files can be downloaded at https://github.com/tesseract-ocr/tessdata

Examples:

%=OCR2( "1.bmp", "f:\\eng.traineddata")%

%=OCR2( "1.bmp", "f:\\eng.traineddata", "", "1234567890")% //the parameter white list of characters is used for filtering the decimal-digit character.

%=OCR2( "1.bmp", "eng.traineddata", "F:\\trained_data\\")%

%=OCR2( "1.bmp", "eng.traineddata", "F:\\trained_data\\", "1234567890")%

CLIPBOARD_GET

Retrieves the content of clipboard.

value CLIPBOARD_GET( [clipboard_format] )

The parameter clipboard_format specifies data format, it can be the string "TEXT", "IMG", or "AUTO". This parameter is optional, and default value is "AUTO".

Example:

CLIPBOARD_GET()

CLIPBOARD_GET( "TEXT" ) //Return text from the clipboard.
CLIPBOARD_GET( "IMG" ) //Return the image data from the clipboard.

GET_SHAREDATA

Opens the shared data and retrieves the value in it. The shared data is a memory space for multiple running macros transfer data each other. A macro uses function PUT_SHAREDATA to creates a shared data and place the value in it, a second macro can access the data by using the function GET_SHAREDATA.

data GET_SHAREDATA( name_of_shared_data )

Parameters:

name_of_shared_data Specifies the name of the shared data. The function PUT_SHAREDATA is responsible for creating and naming a shared data. If the shared data does not exist, the function returns an empty string.

PUT_SHAREDATA

Shares a data between all running macros. This function will create a named shared data and place the data on it. If the named shared data existed before the function call, the function opens it.

The player closes the shared data automatically when it terminates, and a shared data does not destroy until all running macros that use it are closed.

number PUT_SHAREDATA( name_of_shared_data, value, [bytes_to_space_size] )

Parameters:

name_of_shared_data Specifies the name of the shared data. The shared data will be created automatically if it's not existed.

value Specifies the value to place into the shared data space. If the shared data is existed before the function call. Any additional data in the value are lost if the value is larger than the size of the shared data space.

bytes_to_space_size The number of bytes to be allocated in the memory for the shared data. The parameter will be ignored if the shared data is existed before the function call.

The bytes_to_space_size will change to the new size if the value is larger than the specified number of bytes when creating the shared data.