Information Center

Editing macro screens: Description

Lists the descriptors that are used by the macro to identify a screen. More information about macro script syntax can be found in the Macro Programming Guide.

For any field except Screen Name, you can use a variable name or an arithmetic expression as the field value. You can enter these variable names and expressions directly into text areas or add them to lists by selecting a new descriptor or <Expression> from the list.

A variable name should have the following format: $var_name$, where var_name can be alphanumerics, the dash symbol, and the underscore symbol. Variable names must be enclosed in dollar signs. Variable names are case sensitive.

For more information see the Macro Programming Guide.

Descriptor
Lists all the descriptors defined for the selected screen. A descriptor is an attribute used by the macro to identify a screen. For each new screen that appears, the macro compares what is on the session window to the list of descriptors for each defined screen until a match is made. Descriptors should be as unique as possible to avoid multiple screens from matching one description. If this screen collision occurs, the wrong actions could be executed on the wrong screen. This could cause screen recognition failure at some point in the execution, resulting in a macro timeout error.

By default, when the Macro Manager records a macro, the OIA and field counts descriptors are defined to identify the screen. If this is adequate, you don't need to make any changes on this tab. However, we recommend that you add String descriptors for more strict and accurate screen recognition.

To modify a descriptor, select the descriptor from the Descriptor list. The name of each descriptor is created automatically based on the descriptor type and the contents of the descriptor. To create a new descriptor, choose the appropriate type of descriptor that you want to create (for example, <new string descriptor>). You can only have one Cursor and one Field Counts and OIA descriptor per screen. You can have multiple String and Attribute descriptors.

A screen is recognized by any of the following types of descriptors:

If you define more than one descriptor as optional, once the first optional descriptor is matched, the other optional descriptors are ignored.

To delete a defined descriptor, select it and click Delete.

Auto-Capture automatically creates descriptors based on the current values shown on the current session window. You can choose which descriptor types to define. Be sure that the correct session screen is showing when you use this option. If you type a value into the Host ID field, and if the session referred to by the Host ID is active, then you can Auto-Capture information from the session window of the session referred to by the Host ID. See Specifying a Host ID.

String

Identifies the screen based on a string displayed on the screen at a known position. Enter the row and column values or click the session screen and it is brought to the foreground. If the Macro Editor is open, you must move it for the session screen to be brought to the foreground. Select the string by drawing a rectangle around it. The start and end row and column fields will then be automatically filled in for you. Copy and paste the string in your selected area into the String field.

Start Row
Starting row position where the macro will look for the string starting from the top of the screen. A negative number starts the count from the bottom of the screen.
Start Column
Starting column position where the macro will look for the string, starting from the leftmost column. Using a negative number starts the count from the right side of the screen.
End Row
Ending row position where the macro will look for the string in a rectangle. If both end row and end column are specified then the macro will look for the string in a rectangle.
End Column
Ending column position where the macro will look for the string in a rectangle. If both end row and end column are specified, then the macro will look for the string in a rectangle.
String
The string that is used to identify the screen.
Ignore Case
String is case sensitive if you select false.
Optional
The string is not required to recognize the screen. At least one optional descriptor must match for the screen to be recognized. Use this option, for example, if one of two strings might appear on the screen. You can define both as optional descriptors. At least one optional descriptor has to match for this screen to be identified, however. This option assumes you have more than one descriptor specified as optional. If only one descriptor is specified as optional, then it will be required.
Inverse Descriptor
If you select true, the string defined by this descriptor must not appear in the area defined by Start Row, Start Column, End Row, and End Column.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.
You can enter negative numbers for rows and columns. Negative numbers are virtual positions from the bottom row. If End Row and End Column are not specified, then Start Row and Start Column are used as absolute position.

Cursor

Identifies the screen based on the position of the cursor. Specify the cursor position, or click the position on the screen and click Picture of arrow to use the cursor's current position on the session screen if you know it's correct.

Row
Row position of the cursor.
Column
Column position of the cursor.
Optional
The cursor position is not required to recognize the screen. At least one optional descriptor must match for the screen to be recognized. Use this option, for example, if one of two cursor positions might appear on the screen. You can define both as optional descriptors. At least one optional descriptor has to match for this screen to be identified. This option assumes you have more than one descriptor specified as optional. If only one descriptor is specified as optional, then it will be required.
Inverse Descriptor
If you select true, the cursor defined by this descriptor must not be at the specified cursor Row and Column.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.

Attributes

Identifies the screen by plane attributes (color, field, or extended field) at a specified row and column position. Specify the attribute position or click Current to use the cursor's current position on the session screen if you know it's correct.

Row
Row position of the attribute.
Column
Column position of the attribute.
Data Plane
Specifies the plane associated with the Attribute Value.
Attribute Value
Hexadecimal value defining the attribute for this data plane. Click Edit Attributes to graphically choose the value.

Note: You do not need to enclose the Attribute Value in single quotes. For more information, see Use Variables and Arithmetic Expressions in Macro.

Optional
The plane attribute is not required to recognize the screen. At least one optional descriptor must match for the screen to be recognized. Use this option, for example, if more than one attribute might appear on the screen. You can define both as optional descriptors. At least one optional descriptor has to match for this screen to be identified. This option assumes you have more than one descriptor specified as optional. If only one descriptor is specified as optional, then it will be required.
Inverse Descriptor
If you select true, the attribute defined by this descriptor must not appear on the session screen.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.

Field Counts and OIA

Identifies the screen by any of the following:

Number of Fields
The total number of fields on the screen.
Optional
Specifies whether the descriptor must evaluate to true in order for the combined boolean results of all the descriptors to be evaluated as true. See Evaluation of descriptors in the Macro Programming Guide.
Inverse Descriptor
Setting this option to true causes the macro runtime to invert the result when the descriptor is evaluated:
  • If the descriptor evaluates to true, then the macro runtime changes the result to false.
  • If the descriptor evaluates to false, then the macro runtime changes the result to true.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.
Number of Input Fields
The total number of fields on the screen that are input fields.
Optional
Specifies whether the descriptor must evaluate to true in order for the combined boolean results of all the descriptors to be evaluated as true. See Evaluation of descriptors in the Macro Programming Guide.
Inverse Descriptor
Setting this option to true causes the macro runtime to invert the result when the descriptor is evaluated:
  • If the descriptor evaluates to true, then the macro runtime changes the result to false.
  • If the descriptor evaluates to false, then the macro runtime changes the result to true.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.
Wait for OIA to Become Uninhibited.
If you set this option to true: If you set this option to false:
Optional
Specifies whether the descriptor must evaluate to true in order for the combined boolean results of all the descriptors to be evaluated as true. See Evaluation of descriptors in the Macro Programming Guide.
Inverse Descriptor
Setting this option to true causes the macro runtime to invert the result when the descriptor is evaluated:
  • If the descriptor evaluates to true, then the macro runtime changes the result to false.
  • If the descriptor evaluates to false, then the macro runtime changes the result to true.
Host ID
The session to which this descriptor applies. Leave the Host ID field blank to have the descriptor apply to the session that launches the macro. See Specifying a Host ID.

Condition

Specifies an expression that evaluates to either true or false. If the expression is true then (assuming that this is the only descriptor and that the Inverse Descriptor and Optional checkboxes are not set) the macro screen to which this condition belongs is recognized as the next screen to be processed. If the expression is false then (with the same assumptions) the macro screen is not recognized.

The syntax of the expression follows the same rules as the syntax of an expression in a conditional action (see Actions). Specifically:

Variable update

Updates a variable with a new value.

Name
Select the name of the variable to update.
Type
Displays the type of the currently selected variable. If the variable is not defined in the current macro, no type appears.
Value
Any valid expression, for example, 'hello', 5, or $var$ + 1.
Current Cursor Position
Click Current to assign the content of the screen at the current cursor position to a variable. When the macro runs, the content of the screen at the cursor position you specify becomes the value for the variable. Current is enabled only for field variables.