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:

• String
  Identifies the screen by text that appears on the screen
• Cursor
  Identifies the screen by the cursor position
• Attribute
  Identifies the screen by plane attributes (for example, color)
• Field Counts and OIA
  Identifies the screen by number of fields, number of input fields, and OIA state
• Condition
  Specifies a condition which evaluates to either true or false.
• Variable Update
  Updates a variable with a new value

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 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.

• FIELD_PLANE - represents the field positions and their attributes as they appear on the screen.
• COLOR_PLANE - contains color information for each character on the screen.
• EXFIELD_PLANE - extended character attribute data, for example, reverse image, underline, blink, double-byte characters, or character color.

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:

• During macro playback, if the input inhibited indicator in the session window is cleared (that is, input is not inhibited) then the macro runtime evaluates this descriptor as true.
• Otherwise the macro runtime evaluates this descriptor as false.

If you set this option to false:

• During macro playback, the macro runtime always evaluates this descriptor as true.

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.

• An expression can contain the following logical comparison operators and arithmetic comparison operators:

  Symbol	Definition
  ==	equal to
  !=	not equal to
  <	less than
  >	greater than
  <=	less than or equal to
  >=	greater than or equal to
  ||	or
  &&	and
  !	not

  Some examples of valid conditional expressions are:
  
  $strA$ == 'abc'
$intB$ != 0
$boolC$ && $boolD$
!$boolE$

• You can use parentheses to indicate the priority of operations in a conditional expression. For example,
  
  (($strA$ == 'abc') && ($intB$ != 0)) || (!$boolE$)


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.