Using Functions to Create Expressions

Task Builder provides a group of functions for you to use when creating expressions. There are both screen and field functions. These functions are available only to those expressions and variables that access screen data.

Screen functions

Screen.CURSORPOSITION (int row, int column )

Screen.CURSORROW( )

Screen.CURSORCOLUMN( )

Screen.HOSTFIELDCOUNT (fieldtype)

Screen.INTEGERAT (startRow, startCol, len)

Screen.INTEGERAT (startRow, startCol, endRow, endCol)

Screen.STRINGAT (startRow, startCol, len)

Screen.STRINGAT (startRow, startCol, endRow, endCol)

Screen.TEXTFROMCURSOR (int length [, String direction = "left"] )

VT-specific

Screen.LASTTEXTRECEIVED ( [int maxLength = MAX_LENGTH] )

Screen or field name functions

You must preface each function with either screen.<function> or <fieldname>.<function>. If you use Screen.<function>, then the entire screen is viewed as a field.

<fieldname or Screen>.CONTAINSATTR (attribute)

<fieldname or Screen>.ENDCOL (textstring[,repeatcount[,startindex]])

<fieldname or Screen>.ENDROW (textstring[,repeatcount[,startindex]])

<fieldname or Screen>.LINEDATA (linenumber)

<fieldname or Screen>.STARTCOL (textstring[,repeatcount[,startindex]])

<fieldname or Screen>.STARTROW (textstring[,repeatcount[,startindex]])

<fieldname or Screen>.STRINGATPOSITION (textstring)

<fieldname or Screen>.STRINGNEAR (textstring,(offset))

Field only function

<fieldname>.FKEY( )

Additional global functions

These functions are not confined to a screen or a field, but are global in scope.

IF

ON

REFLECT

TRIM

<fieldname or screen>.CONTAINSATTR(attribute) where:

fieldname - the name of a field on the current screen. Use Screen.CONTAINSATTR to view the entire screen as a field.
attribute - an attribute as defined in IScreenDataConstants, which are equivalent to the INativeAccessConstants. Must be single-quoted. These are long values and can appear in one of three formats:
1. 'Oxnnn', where "nnn" is a hexadecimal number
2. 'nnn', where "nnn" is a standard base 10 number
3. An attribute name as defined in IScreenDataConstants. For example, 'FIELD_LIGHT_PEN', 'ATTR_HIGH_INTENSITY', and 'COLOR_FG_RED'.

For a list of all available constants, see Javadocs for Attachmate Interfaces.

Description

Return value is a Boolean object that is either true or false. The value is determined by looking at every data cell in the named field or screen. If any cell in the area contains the named attribute true is returned, otherwise false is returned. All attributes are evaluated as a bit value, if the given bit is set, the attribute is set.

Foreground and background color attributes, which are each fields 4 bits in length, are handled differently. If the attribute parameter has a bit in one of these color fields, then all 4 bits in that field must match for true to be returned.

Examples

`HostScreen1.CONTAINSATTR('COLOR_FG_RED')`	Returns true if the foreground color of HostScreen1 is red.
`UserField1.CONTAINSATTR('ATTR_HIGH_INTENSITY')`	Returns true if the high intensity bit is set in any part of UserField1.
`HostField4.CONTAINSATTR('FIELD_NUMERIC_ONLY')`	Returns true if the numeric only bit is set in HostField4.

Screen.CURSORPOSITION( )
Boolean CursorPos(int row, int column)

Description

Evaluates to true when the cursor position matches the given row and column, where:

row - The row on the screen to test for.
col - The column on the screen to test for.

Example

HostField7 like '*Enter Command:*' and CursorPos(21,8) A valid recognition rule matching some test on the screen and cursor position

Screen.CURSORCOLUMN( )

Description

Returns an Integer object representing the current column of the cursor.

Example

HostScreen1.CURSORCOLUMN == 5 Returns true if the cursor is column 5 of the current screen.

Screen.CURSORROW ( )

Description

Returns an Integer object representing the current row of the cursor.

Example

HostScreen1.CURSORROW == 23 Returns true if the cursor is in row 23 of the current screen.

<fieldname or screen>.ENDCOL
(textstring[,repeatcount[,startindex]]) where:

fieldname - the name of a field on the current screen. Use Screen.ENDCOL to view the entire screen as a field.
textstring - the case sensitive text that is searched in the field or screen. It must be single-quoted.
repeatcount - Optional argument, which occurrence of the textstring in the field or screen is of interest. A value of "1" (which is the default if the argument is not present) will find the first occurrence of the textstring. This argument must be present if startindex is present.
startindex - Optional argument indicating the index location in the field or screen where the search is to begin. Startindex views multi-line fields or screens as a single linear line. A value of "1" (which is the default if the argument is not present) will start at the first location.

Description

You must specify Start and End Col expressions when the Is Relative field property is set to true. A relative field is a user field of variable or relative size. The field size varies depending on the data contained in the field. For more information on the Is Relative field property, see Host and User Field Property Descriptions.

Returns an Integer object representing the column location of the end character in a text string or zero if a text string is not found. The return value is the column relative to screen. This is true even if a field name is used that does not start at the left edge of the screen.

Example

`HostScreen1.ENDCOL('STOP')`	Returns the column location of the string 'STOP'.
`HostScreen1.ENDCOL('STOP') == 3`	Returns true if the column location of the string 'STOP' is 3.

<fieldname or screen>.ENDROW
(textstring[,repeatcount[,startindex]]) where:

fieldname - the name of a field on the current screen. Use Screen.ENDROW to view the entire screen as a field.
textstring - the case sensitive text that is searched in the field or screen. It must be single-quoted.
repeatcount - Optional argument which occurrence of the textstring in the field or screen is of interest. A value of "1" (which is the default if the argument is not present) will find the first occurrence of the textstring. This argument must be present if startindex is present.
startindex - Optional argument indicating the index location in the field or screen where the search is to begin. Startindex views multi-line fields or screens as a single linear line. A value of "1" (which is the default if the argument is not present) will start at the first location.

Description

Returns an Integer object representing the row location of the first character of a text string, or zero if a text string was not found. The return value is the row relative to screen, even if "name" was a field that did not start at the left edge of the screen.

Example

`HostScreen1.ENDROW('STOP')`	Returns the row location of the string 'STOP'.
`HostScreen1.ENDROW('STOP') == 3`	Returns true if the row location of the string 'STOP' is 3.

<fieldname>.FKEY( ) where:

fieldname is the name of a field on the screen

Description

Returns an Integer object that matches the function key named in the field. The return value is the function key value from IScreenDataConstants. The data in the named field must be in one of the following formats:

Where n is an integer from 1 to 24. The field can contain padding spaces in front of or behind the text, but can contain no other text. If the field contents cannot be parsed (as defined here), zero is returned.

To use FKEY( ) in a table, use FKEY(name of table output field) not <fieldname or screen>.FKEY( ).

Example

HostField1.FKEY( ) Returns an integer that matches the function key in HostField 1.

Screen.HOSTFIELDCOUNT
(fieldtype) where:

fieldtype - Optional. Fieldtype is either protected or unprotected and is not case-sensitive. Must be single-quoted.

Description

Return value is an Integer object that contains field count. If fieldtype has a string in it, only the fields that match that attribute are counted. If fieldtype is not included or is a string that is not recognized, the return value is the total number of fields (if "allfields" was entered for the fieldtype, then a total field count would be returned). When fields are being counted, it is determined if there is a table defined on the screen. If a table is defined, ANY host field that has even a single cell overlapping the table, is not counted.

Example

`HostScreen1.HOSTFIELDCOUNT( )`	Returns the number of fields on HostScreen1.
`HostScreen1.HOSTFIELDCOUNT(unprotected)`	Returns the number of unprotected fields.

Screen.INTEGERAT
(startRow, startCol, len) where:

Description

Returns an integer at the specified location spanning a specified length. If no integer is found at the specified location, returns false.

Example

HostScreen7.INTEGERAT(1,5,1) Returns one integer at row 1, column 5 on HostScreen7.

Screen.INTEGERAT
(startRow, startCol, endRow, endCol) where:

Description

Returns an Integer object at the specified location from the specified window. If no integer is found at the specified location, returns NULL.

Example

HostScreen7.INTEGERAT(1,5,2,6) Returns the integers between row 1, column 5 to row 2 column 6 on HostScreen7.

Screen.TEXTFROMCURSOR( )
String TextFromCursor(int length [, String direction = "left"]), where:

length - The number of characters to return.
direction - (Optional). The direction to go from the cursor to return text. This can be either 'left', 'right', 'up', or 'down'. The default is 'left', if not specified.

Description

Returns the given number of characters from the immediate location of the cursor.

If there are not enough characters on the screen, the returned data will be truncated at the screen boundary. The character directly below the cursor is not included in the returned results.

Example

TextFromCursor (10) like '*Choice: ' and HostField2 like '*Menu*'

TextFromCursor (5, 'right') like '<---'

<fieldname or screen>.LINEDATA(linenumber) where:

fieldname - the name of the current screen or the name of the field in the current screen. Use Screen.LINEDATA to view the entire screen as a field.
linenumber - the line to be returned.
- Positive values - "1" will cause the first line to be returned. Values greater than 1 will cause the indexed line (as counted from the top) to be returned.
- Zero value - "0" returns the last line of data on the screen. Specifically, a zero value causes the line just before the first blank line to be returned. If there are no blank lines on the host screen, data from the last line of the screen will be returned. A zero value can be useful if the host screen returns a variable and unknown number of lines.
- Negative values - "-1" returns the line that is one above the last line of data on the host screen. Negative values cause the lines to be counted up from the bottom. The count starts from the line that would be returned if zero were entered.

Description

Return value is a String object containing the indicated line. If linenumber did not point to a valid line, the returned String object will contain a zero length string.

Example

`HostScreen5.LINEDATA(3)`	Returns a string containing what is on line 3 of HostScreen5.
`HostScreen7.LINEDATA(0)`	Returns a string containing what is on the last line of HostScreen7.
`HostScreen7.LINEDATA(-2)`	Returns a string containing what is on the line that is 2 lines above the last line of data on HostScreen7.

<fieldname or screen>.STARTCOL
(textstring[,repeatcount[,startindex]]) where:

fieldname - the name of a field in the current screen. Use Screen.STARTCOL to view the entire screen as a field.
textstring - the case-sensitive text that is searched in the field or screen. It must be single-quoted.
repeatcount - Optional argument, which occurrence of the textstring in the field or screen is of interest. A value of "1" (which is the default if the argument is not present) will find the first occurrence of the textstring. This argument must be present if startindex is present.
startindex - Optional argument indicating the index location in the field or screen where the search is to begin. Startindex views multi-line fields or screens as a single linear line. A value of "1" (which is the default if the argument is not present) will start at the first location.

Description

Returns an Integer object representing the column where the first character of a textstring was found, or zero if a textstring was not found. The return value is the column relative to the screen, even if "name" was a field that did not start at the left edge of the screen.

Example

HostScreen1.STARTCOL('SAVINGS MENU')	Returns the column position of the S in SAVINGS MENU on HostScreen1.
HostScreen1.STARTCOL('DATA',2)	Returns the column position of the D for the second occurrence of DATA on HostScreen1.
HostScreen1.STARTCOL('CUSTID', 1,25)	Returns the column position of the C for the first occurrence of CUSTID on HostScreen1, starting from the 25th column of Row 1. Columns 1 - 24 of Row 1 will not be searched.
HostScreen1.STARTCOL('FINDME', 1,81)	Returns the column position of the F for the first occurrence of FINDME on HostScreen1, starting from the first column of Row 2. Columns 1 - 80 of Row 1 will not be searched.

<fieldname or screen>.STARTROW
(textstring[,repeatcount[,startindex]]) where:

fieldname - the name of a field in the current screen. Use Screen.STARTROW to view the entire screen as a field.
textstring - the case sensitive text that is searched in the field or screen. It must be single-quoted.
repeatcount - Optional argument, which occurrence of the textstring in the field or screen is of interest. A value of "1" (which is the default if the argument is not present) will find the first occurrence of the textstring. This argument must be present if startindex is present.
startindex - Optional argument indicating the index location in the field or screen where the search is to begin. Startindex views multi-line fields or screens as a single linear line. A value of "1" (which is the default if the argument is not present) will start at the first location.

Description

You must specify Start and End Row rules when the Is Relative field property is set to true. A relative field is a user field of variable or relative size. The field size varies depending on the data contained in the field. For more information on the Is Relative field property, see Host and User Field Property Descriptions.

Returns an Integer object representing the row where the first character of a textstring was found, or zero if a textstring was not found. The return value is the row relative to screen.

Example

HostScreen1.STARTROW('SAVINGS MENU')	Returns the row position of the S in SAVINGS MENU on HostScreen1.
HostScreen1.STARTROW('DATA',2)	Returns the row position of the D for the second occurrence of DATA on HostScreen1.
HostScreen1.STARTROW('CUSTID', 1,105)	Returns the row position of the C for the first occurrence of CUSTID on HostScreen1, starting from the 25th column of row 2. Row 1 and columns 1 - 24 of row 2 will not be searched.
HostScreen1.STARTROW('FINDME', 1,161)	Returns the column position of the F for the first occurrence of FINDME on HostScreen1, starting from the first column of Row 3. Row 1 and Row 2 will not be searched.

<fieldname>.STRINGATPOSITION ( )

Description

Commonly used for screens that contain variable length fields. Both the field position and string must match in order to validate the recognition rule and verify the screen.

Example

HostField1.STRINGATPOSITION ( ) like 'SAVINGS MENU'

Returns true if HostField 1 matches the field position and contains the string, SAVINGS MENU.

<fieldname>.STRINGNEAR(offset)

Description

Verifies the text matches in each field that has a start position in the range determined by the value specified by the offset value. This function is commonly used for screens that contain fields with variable start positions or of variable lengths.

Example

HostField1.STRINGNEAR (5) like 'SAVINGS MENU'

Returns true if HostField 1, whose position can vary by 5 positions, contains the string, SAVINGS MENU.

Screen.STRINGAT
(startRow, startCol, len)

	Description Returns a String object representing the host data starting at the specified row and column and spanning the specified length. Used to extract data from a location where no field has been defined.

Example

HostScreen12.STRINGAT(10,20,4) == 'TEST'

Checks to see if the string at row 10, column 20 is equal to "TEST".

Screen.STRINGAT
(startRow, startCol, endRow, endCol)

	Description Returns a String object representing the host data starting at the specified row and column and ending where specified. Used to extract data from a location where no field has been defined.

Example

HostScreen12.STRINGAT(10,20,10.23) == 'TEST'	Checks to see if the string at row 10, column 20 is equal to "TEST".
HostScreen2.STRINGAT(20,1,21,80)	Returns a text string containing the text on HostScreen2 starting at row 20, column 1 and ending at row 21, column 80.

Screen.LASTTEXTRECEIVED
String LastTextRecv ( [int maxLength = MAX_LENGTH] )

Description

VT host - specific. Because VT screens are unformatted, text can be written to any location on the screen simply by sending out an escape screen. Also, the scrolling nature of VT terminals makes screens difficult to match using standard recognition rules. Using the LastTextReceived method, you can match the last data written regardless of its location.

Although, the LastTextRecv( ) method is fairly reliable in determining when a screen has settled, it won't help you distinguish between two similar screens. Use user fields and CursorPosition ( ) to make your recognition rules more specific in order to accomplish this.

Returns a string containing the last characters ( up to 255) written to the screen from the host. For example, if you make the method call LastTextRecv( ), 255 characters will be returned, all of which have made visible changes on the screen. If you specify a maxLength, such as LastTextRecv(15), then only the last 15 characters will be returned. If the host doesn't write 255 characters to the host, then only the characters written will be returned. This method is used by default to build recognition rules when creating VT tasks.
Where:

maxLength - (Optional). The maximum number of characters to return. If not specified, the entire buffer is returned to a maximum size of 255 characters.

The last text received characters are accumulated from the last time the user hits a key when recording. When running the task, the last text received characters are accumulated after the inputs and aid key are sent to the host. Escape sequences and unprintable characters are excluded from the returned data.

Example

HostField1 like '*Attachmate*' and LastTextRecv() like '*Option*'

LastTextRecv(10) like '*bash$'

IF
(bool-expr, expr1, expr2)

Description

Returns expr1 if the bool-expr evaluates to true, else returns expr2. Used in the Start or End Row rule of List Tables.

Example

IF(Screen1.INTEGERAT(2,75,1)==1, STARTROW('list')+1,2)

IF((((Size-Line)+1)>TABLE_HEIGHT), TABLE_HEIGHT, (Size-Line)+1)

Return to list of functions

ON
(int-expr, val1, val2, val3...)

Description

Returns val1 if int-expr evaluates to 0, val2 if it evaluates to 1, and so on. There can be any number of arguments. Used in an AID Key expression in a path between two screens if there is more than one AID key.

Val1, val2 and val3 refer to strings, which are returned from this method.

Example

ON (IntegerAt(12,15,1), 'x', 'y', 'z')

If the integer at screen location 12,15 with a length of 1 is 0, then return x; if it is 1, then return y; if it is 2 then return z.

Return to list of functions

REFLECT (staticMethodName, [arg1, arg2, arg3,...])

The first argument to the REFLECT method is a static method with the complete <fieldname or screen>. The other arguments to the REFLECT method should be in expression form and are optional, depending whether or not the static method takes any arguments, and if so, the number of arguments it takes.

Description

Calls the given static method (must be a fully qualified name) with the given arguments, if applicable, using reflection. Returns the return value of the given static method. This function can be used any place where the user wants to add a customized rule.

The REFLECT method is a meta-function. It calls the static method given as the first argument. The subsequent arguments to the REFLECT method, (which are themselves expressions), are passed as arguments to this static method. The user can define custom functions that can be called from the expression. The functions must be defined as static methods in a class accessible from the VM running the Java VM, and the method reference in the expression must contain the complete name, including the full package name and the class <fieldname or screen>.

Example:

Screen Recognition Rule: REFLECT(com.mycompany.mypackage.MyClass.MyRule,Screen2.STRINGAT(10,10,5))

To implement this, the user has to define a method MyRule.


package "com.mycompany.mypackage"

 public class MyClass {

  public static Boolean MyRule(String string){

   //Code of MyRule method should go here.  The method returns a boolean value.

  }

 }

When defining custom functions, it's necessary to provide access to the custom classes generated. To provide this access to the Task Builder and the Runtime Service, manually copy all custom classes into the attachmate/eai/Common/config directory on every Task Builder or Runtime Service machine where the custom rule will be used.

To have your custom method return true or false, verify that the return type is Boolean and that either Boolean.TRUE or Boolean.FALSE is returned.
REFLECT expressions that will be used for bean-based task outputs must return a String data type.

Example

REFLECT('java.lang.Integer.parseInt',STRINGAT(10,10,5)) Integer	Uses the static Java method parseInt() to parse out the integer in the form of a string at row 10, column 10, with a length of 5.
REFLECT('mypackage.MyClass.MyMethod',{param1, param2, param3})	An abstract example of how to use a custom function.

Return to list of functions

TRIM
(string)

Description

Returns a string after removal of spaces at the beginning and the end. Used in recognition rules.

Example

If HostField1 contains ' *VM/ESA* '

TRIM(HostField1)=='VM/ESA'	Returns true
HostField1=='VM/ESA'	Returns false


	Modifying Screen Recognition Rules, Overview
	Javadocs for Attachmate Interfaces
	Defining Rules with Expressions
	Host and User Field Property Descriptions