Macro actions

 

In general

 

The actions by function

Here is a list of all the actions, grouped according to function.

 

How actions are performed

The runtime context

As you may remember from How the macro runtime processes a macro screen, when the macro runtime has selected a new current macro screen, the macro runtime immediately begins to perform the actions in the <actions> element of that macro screen.

After the macro runtime has performed all the actions, it immediately goes on to the next step of determining the next macro screen to be processed.

The macro screen context

Within a single macro screen, the macro runtime performs the actions in the order in which they occur in the <actions> element. This is the same order in which you haved ordered the actions in the Action listbox.

You are not required to create any actions for a macro screen. If there is no <actions> element or if the <actions> element is empty, then the macro runtime will go straight to the next section of macro screen processing, which is selecting the next macro screen to be processed.

 

Specifying parameters for actions

In specifying the parameters of an action, remember that, in general, any context that accepts an immediate value of a particular standard data type also accepts any entity of the same data type. For example, if an input field accepts a string value, then it also accepts an expression that evaluates to a string, a value that converts to a string, a string variable, or a call to an imported method that returns a string (see Equivalents).

However, there are a few fields in which you cannot use variables (see Use the value that the variable holds).

 

Introduction to the Actions tab

 

Sample Actions tab

The Actions tab on the Screens tab of the Macro Editor allows you to create and edit actions. When you create an action in the Actions tab, the Macro Editor inserts the new action into the <actions> element of the currently selected screen. Figure 21 shows a sample Actions tab:

Figure 21. Actions tab
Actions tab of the Macro Editor

In the figure above, the Screens tab of the Macro Editor is selected. The name of the currently selected screen, Screen1, is displayed in the Screen Name field at the top of the Screens tab. Below the Screen Name field are the General, Description, and Actions subtabs. The Actions tab is selected.

As you look at the Actions tab in the figure above, you can see that, like the Description tab, it has an upper area and a lower area.

The upper area contains controls that operate on a single action element considered as a whole. In particular, the Action listbox situated in the upper left corner of the Actions tab contains the name of the currently selected action. In the figure above, there is no currently selected action, because no action has been created yet.

The lower area of the Actions tab displays the contents of the currently selected action, if any. If the currently selected descriptor is an Input action, then the lower area of the Actions tab presents the contents appropriate to that type of action. If the user creates or selects another type of action, such as an Extract action, then the lower area presents the contents appropriate to an Extract action.

 

Create a new action

Looking again at the Actions listbox in Figure 21, notice that it does not yet contain any actions. The selections, which are all enclosed in angle brackets and all begin with the word new, are for creating new actions. As you can see in Figure 21, the displayable part of the Actions listbox is not tall enough to show the whole list at once. Here is the entire list:

with no actions created 
<new input action>
<new extract action>
<new prompt action>
<new pause action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>

For example, if you clicked <new input action>, the Macro object would create a new Input action and place it at the top of the list. The lower area of the Actions tab would allow you to fill out the various fields that belong to an Input action (such as the input key sequence). The new Input item would be in the selected area of the Actions listbox, and the list part of the listbox would then look like this:

Input action1(0,0)
<new input action>
<new extract action>
<new prompt action>
<new pause action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>

When the macro runtime processes this macro screen, it will perform the actions in the same order in which they are listed in the Actions listbox. To change the order of the actual actions, click the Change Order button to the right of the Actions listbox.

 

The actions

 

Comm wait action (<commwait> element)

The Comm wait action waits until the communication status of the session changes to some state that you have specified in the action. For example, you might create a Comm wait action to wait until the session was completely connected.

How the action works

When the macro runtime starts to perform a Comm wait action, it looks at the communication status specified in the Comm wait action and compares it to the actual communication status of the session. If the two statuses match, then the macro runtime concludes that the Comm wait action is completed, and the macro runtime goes on to perform the next action.

However, if the two statuses do not match, then the macro runtime does no further processing, but just waits for the communication status that is specified in the Comm wait action to actually occur in the session.

You can specify in the Comm wait action a timeout value in milliseconds that causes the macro runtime to end the Comm wait action when the timeout value has expired. That is, the macro runtime terminates the action when the timeout value has expired, even if the communication status that the macro runtime has been looking for has not been reached.

After a Comm wait action, you probably want to use some other action, such as an Extract action, to check some characteristic of the application screen that will indicate to you whether the session has actually reached the communication status that you wanted, or whether the Comm wait action ended because of a timeout.

Specify a communication status that is persistent

As the session connects or disconnects, the communication status typically moves quickly through some states (such as pending active, then active, then ready) until it reaches a particular state at which it remains stable for some time (such as workstation id ready). In most situations you want to specify that persistent, ending state in the Comm wait action. See the next section for a list of persistent states.

(If instead you specified some transitional state such as pending active, then the session might pass through that state and go on to the next state before the macro runtime gets a chance to perform your Comm wait action. Therefore when the macro runtime does perform your Comm wait action it will be waiting interminably for some state that has already occurred.)

Communication states

You can specify any of the states listed in the Connection Status listbox. Table 12 lists the name and significance of each state:

Table 12. Communication states
Communication state: Significance:
Connection Initiated Initial state. Start Communications issued.
Connection Pending Active Request socket connect.
Connection Active Socket connected. Connection with host.
Connection Ready Telnet negotiation has begun.
Connection Device Name Ready Device name negotiated.
Connection Workstation ID Ready Workstation ID negotiated.
Connection Pending Inactive Stop Communications issued.
Connection Inactive Socket closed. No connection with host.

The stable states (that is, the ones that usually persist for more than a few seconds) are:

If you select <Expression> in the Connection Status listbox, then specify an expression that resolves to one of the keywords that the macro runtime expects to find in the value attribute of the <commwait> element (see <commwait> element). For example, you might specify a variable named $strCommState$) that resolves to CONNECTION_READY.

Examples

Comm wait action 
<commwait value="CONNECTION_READY" timeout="10000" />

 

Conditional action (<if> element and <else> element)

The Conditional action contains the following items:

The Conditional action provides the functions of an if-statement or of an if-else statement.

Specifying the condition

You should specify in the Condition field the conditional expression that you want the macro runtime to evaluate. The conditional expression can contain logical operators and conditional operators and can contain terms that include arithmetic expressions, immediate values, variables, and calls to Java methods (see Conditional and logical operators and expressions).

Condition is True (<if> element)

Use the Condition is True tab to specify the actions that you want to be performed if the condition evaluates to true.

The Condition is True tab contains controls that are almost identical to the controls for the Actions tab. Specifically:

Use these controls on the Condition is True tab to create and edit the actions that you want the macro runtime to perform if the condition is true.

For example, you might set the Condition field to the name of a variable, such as $boolResult$, into which a previous operation has stored its result. If the value of $boolResult$ is true, you might want to a perform another action. Therefore, in the Condition is True tab you would create the other action.

During macro playback the macro would evaluate the condition, $boolResult$. If the value is true then the macro runtime would perform the action that you had defined in the Condition is True tab. If the value is false then the macro runtime would skip over that action and over all the other actions (if any) that you had defined in the Condition is True tab.

Condition is false (<else> element)

Use the Condition is False tab to specify the actions that you want to be performed if the condition evaluates to false.

Like the Condition is True tab, the Condition is False tab contains controls that are almost identical to the controls for the Actions tab. Use these controls on the Condition is False tab to create and edit the actions that you want the macro runtime to perform if the condition is false.

Condition action not allowed within a Condition action

The Macro Editor does not allow you to create a Condition action inside the Condition is True tab or inside the Condition is False tab. Therefore you cannot have the equivalent of an if-statement nested inside another if-statement, or of an if-statement nested inside an else-statement.

 

Extract action (<extract> element)

The Extract action captures text from the host terminal and stores the text into a variable. This action is very useful and is the primary method that the Macro object provides for reading application data (short of using programming APIs from the toolkit).

Capturing text

The most common use of the Extract action is to capture text that is being displayed in the host terminal.

Here is an overview of the steps to follow. Each step is described in more detail in the following subsections.

  1. Set the Continuous Extract option, if necessary

  2. Specify an area on the host terminal that you want to capture.

  3. Specify an extraction name.

  4. Specify TEXT_PLANE as the data plane.

  5. Specify a variable in which you want the text to be stored.

Set the Continuous Extract option

If you want to capture a rectangular block of text, then set the Continuous Extract option to false (this is the default value). For more information, see Capturing a rectangular area of the host terminal.

In contrast, if you want to capture a continuous sequence of text that wraps from line to line, then set the Continuous Extract option to true. For more information, see Capturing a sequence of text from the host terminal .

Specify the area of the host terminal

To specify the area of the host screen that you want to capture, type the row and column coordinates of the text area into the Row and Column fields on the Extract action window.

The macro runtime will interpret the values differently depending on whether the Continuous Extract option is set to false or true (see Set the Continuous Extract option).

Type the first set of row and column coordinates into the first pair of Row and Column values (labeled Top Corner on the Extract action window) and type the second set of coordinates into the second pair of Row and Column values (labeled Bottom Corner). Use the text cursor on the host screen as an aid to determine the coordinates that you want.

In the Row (Bottom Corner) input field you can enter -1 to signify the last row of the data area on the host screen. This feature is helpful if your users work with host screens of different heights (such as 25, 43, 50) and you want to capture data down to the last row. Similarly for the Column (Bottom Corner) input field you can enter -1 to signify the last column of the data on the host screen (see Significance of a negative value for a row or column).

Specify an extraction name

You can specify an extraction name, such as 'Extract1'.

Specify TEXT_PLANE as the data plane

In the Data Plane listbox click TEXT_PLANE. This is the default.

Specify the variable in which you want the text to be stored

Set the checkbox labeled Assign Text Plane to a Variable and enter the name of the variable into which you want the text to be stored. The text is returned as a string. In most cases you will probably want to store the string in a string variable, so that some other action in your macro can process the string.

However, if you specify a variable of some other standard data type (boolean, integer, double) then the macro runtime will convert the string to the format of the variable, if possible. For example, if the text on the screen is 1024 and the variable is an integer variable then the macro runtime will convert the string 1024 to the integer 1024 and store the value in the integer variable. If the format is not valid for converting the string to the data type of the variable then the macro runtime will terminate the macro with a run-time error. For more information about data conversion see Automatic data type conversion.

Treatment of nulls and other undisplayable characters

Text captured from the TEXT_PLANE does not contain any nulls (0x00) or other undisplayable characters. Any character cell on the display screen that appears to contain a blank space character will be captured as a blank space character.

Capturing a rectangular area of the host terminal

When the Continuous Extract option is false (this is the default value), the macro runtime treats the two pairs of Row and Column values as the upper left and lower right corners (inclusive) of a rectangular block of text. The rectangular block can be as small as one character or as large as the entire application window.

The macro runtime:

As an example, suppose that the first 40 characters of rows 16, 17, and 18 of the host terminal are as follows:

.8..Outlist.....Display, delete, or prin
.9..Commands....Create/change an applica
.10.Reserved....This option reserved for

and suppose that the macro runtime is about to perform an Extract action with the following settings:

Because the Continuous Extract option is false, the macro runtime treats the row and column pairs as marking a rectangular block of text, with the upper left corner at row 16 and column 5 and the lower right corner at row 18 and column 12.

The macro runtime initializes the result string to an empty string. Then the macro runtime reads the rectangular block of text one row at a time ('Outlist.', 'Commands', 'Reserved'), concatenating each row to the result string. Finally the macro runtime stores the entire result string into the result variable $strTmp$. The variable $strTmp$ now contains the following string:

'Outlist.CommandsReserved'

Capturing a sequence of text from the host terminal

When the Continuous Extract option is true, the macro runtime treats the two pairs of Row and Column values as the beginning and ending positions (inclusive) of a continuous sequence of text that wraps from line to line if necessary to get from the beginning position to the ending position. The sequence of text can be as small as one character or as large as the entire application window.

The macro runtime:

For example, suppose that rows 21 and 22 of the host terminal contain the following text (each row is 80 characters):

........Enter / on the data set list command field for the command prompt pop-up
or ISPF line command............................................................

and suppose that the macro runtime is about to perform an Extract action with the following settings:

Because the Continuous Extract option is true, the macro runtime treats the row and column pairs as marking the beginning and end of a sequence of text, with the beginning position at (21, 9) and the ending at (22, 20).

The macro runtime initializes the result string to an empty string. Then the macro runtime reads the sequence of text from beginning to end, wrapping around from the last character of row 21 to the first character of row 22. Finally the macro runtime stores the entire result string into the result variable $strTmp$. The variable $strTmp$ now contains the following string of 92 characters (the following text is hyphenated to fit on the page of this document, but actually represents one string without a hyphen):

'Enter / on the data set list command field for the com-
mand prompt pop-up or ISPF line command'

In contrast, if the Continuous Extract option is set to false in this example, $strTmp$ would contain a string of 24 characters, 'Enter / on tline command'.

Unwrap Text option

Use this option with the Continuous Extract option set either to false or true.

When you set Unwrap Text to true, the macro runtime uses not only the row and column pairs in the Extract window but also the field boundaries in the host terminal in determining the data to collect. The macro runtime returns an array of strings (if you are using the toolkit) or a single string of concatenated strings (if you are not using the the toolkit).

Do not confuse the Unwrap Text option with the Wrap option of the String descriptor, which is based on a rectangular block of text rather than fields (see How the macro runtime searches the rectangular area (Wrap option)).

When Unwrap Text is true and Continuous Extract is false

When Continuous Extract is false, the row and column pairs represent the corners of a rectangular block of text. When you set Unwrap Text to true, the macro runtime reads each row of the rectangular block of text and processes each field in the row as follows:

The intent of the Unwrap Text option is to capture the entire contents of a field as one string even if the field wraps from one line to the next.

For example, suppose that the host terminal is 80 characters wide and that rows 9, 10, 11, and 12 of the host terminal are as follows:

...............................................Compress or print data set.......
..............................................................Reset statistics..
..............................................................Catalog or display
information of an entire data set...............................................

Suppose also that the following text areas in the lines above are fields:

Compress or print data set
Reset statistics
Catalog or display information of an entire data set

Finally, suppose that:

The macro runtime concatenates the individual strings and stores them as a single string into the variable that you specified in the Extract window. In this example the macro runtime stores the string 'Reset statisticsCatalog or display information of an entire data set' into the variable.

When Unwrap Text is true and Continuous Extract is true

When Continuous Extract is true, the row and column pairs represent the beginning and ending locations of a continuous sequence of text that wraps from line to line if necessary. When you then set Unwrap Text to true, the macro runtime processes the continuous sequence of text as follows:

 

Input action (<input> element)

The Input action sends a sequence of keystrokes to the host terminal. The sequence can include keys that display a character (such as a, b, c, #, &, and so on) and also action keys (such as [enterreset], [copy], [paste], and others).

This action simulates keyboard input from an actual user.

Location at which typing begins

Use the Row and Column fields to specify the row and column location in the host terminal at which you want the input sequence to begin. For example, if you specify row 23 and column 17 in the Input action, and you specify Hello world as the String value of the Input action, then (assuming that the location you have specified lies within an input field) the macro runtime will type the key sequence Hello world on the host terminal starting at row 23 and column 17.

If you specify a row or column location of 0, then the macro runtime will type the key sequence beginning at the actual row and column location of the text cursor on the host terminal when the Input action is performed. You should not specify a row or column of 0 unless the context is one in which the location of the text cursor does not matter (for example, with a [copy] action key) or unless you can predict where the text cursor will be located (for example, if a Mouse click action has just moved the text cursor to a specific location, or if the application has positioned the text cursor as part of displaying the application screen).

Input errors

During macro playback, the host terminal reacts to a key input error in the same way as it would react if an actual user had typed the key.

For example, if an Input action sends a key that displays a character (such as a, b, c, #, & and so on) to the session when the text cursor is not located in a 3270 or 5250 input field, then the session will respond by inhibiting the key input and displaying an error symbol in the Operator Information Area, just as it would with a keystroke typed by an actual user.

Input string

The String field is an input field in which you specify the key sequence that you want the action to perform.

To specify a key that causes a character to be displayed (such as a, b, c, #, &, and so on), type the key itself.

To specify a key from the Actions Keys listbox, scroll the list to the key you want (such as [backspace]) and click Insert Action Key. The name of the key enclosed by square brackets appears at the next input position in the String field. Please notice that the keys in the Action Keys listbox are not listed alphabetically throughout. You might have to keep scrolling down the list to find the key you want.

Another way to specify an action key is just to type the name itself into the String input field, surrounded by square brackets (for example, [backspace]).

The following copy/paste keys occur in the Action Keys list for a 3270 Display Session:

[copy]                  [mark right]
[copyappend]            [mark up]
[cut]                   [paste]
[mark down]             [pastenext]
[mark left]             [unmark]

For other keys see Mnemonic keywords for the Input action.

Translate Host Action Keys

The Translate Host Action Keys field indicates whether the macro runtime is to interpret action key names (such as [copy], [enterreset], [tab], and so on) in the input sequence as action keys or as literal sequences of characters. The default is true (interpret the action key names as action keys).

For example, suppose that the input key sequence is '[up][up]Hello world' and that the text cursor is at row 4, column 10. If the Translate Host Actions Keys value is true, then in performing this input sequence the macro runtime will move the text cursor up two rows and then type Hello world beginning at row 2, column 10. In contrast, if the Translate Host Actions Keys value is false, then the macro runtime will type [up][up]Hello World beginning at row 4, column 10.

Move Cursor to End of Input

When the Translate Host Action Keys field is set to true (the default), then the Macro Editor also sets the Move Cursor to End of Input listbox to true and disables it. Even though the listbox is disabled, its value is still set to true.

If you set the Translate Host Action Keys listbox to false, then the Move Cursor to End of Input listbox is enabled and you can set it to false, true, or an expression that is evaluated at runtime.

When the value of this listbox is true (the default), then the macro runtime moves the text cursor in the same way that it would be moved if an actual user were entering keyboard input. For example, if the key is a text character, such as 'a', then the macro runtime types the character on the host terminal and then moves the text cursor to the first character position after the 'a'. Similarly, if the key is [tab], then the macro runtime moves the text cursor to the next tab location.

In contrast, if the value of the Move Cursor to End of Input listbox is false, then the macro runtime does not move the text cursor at all. The text cursor remains in the same position as it occupied before the macro runtime performed the Input action.

 

Mouse click action (<mouseclick> element)

The Mouse click action simulates a user mouse click on the host terminal. As with a real mouse click, the text cursor jumps to the row and column position where the mouse icon was pointing when the click occurred.

Specifying row and column

In the lower area of the Actions window, specify the row and column location on the host terminal where you want the mouse click to occur. Or, you can click on the host terminal itself, and the Macro Editor updates the values in the Row and Column fields to reflect the new location of the text cursor.

 

Pause action (<pause> element)

The Pause action waits for a specified number of milliseconds and then terminates.

More specifically, the macro runtime finds the <pause> element, reads the duration value, and waits for the specified number of milliseconds. Then the macro runtime goes on to perform the next item.

Uses for this action are:

You should type the number of milliseconds in the Duration input field. The default is 10000 milliseconds (10 seconds).

 

Perform action (<perform> element)

The Perform action invokes a method belonging to a Java class that you have imported (see Create an imported type for a Java class).

You can invoke a method in many other contexts besides the Perform action. However, the Perform action is useful in certain scenarios, for example, when you want to invoke a method that does not return a value.

Some of the contexts, other than the Perform action, in which you can invoke a method are as follows:

In general, outside the Perform action, you can invoke a method in any context in which the value returned by the method is valid.

Invoking the method

Type the method call into the Action to Perform field. You must enclose a method call in dollar signs ($), just as you would a variable (see Syntax of a method call). The macro runtime will invoke the method. See also How the macro runtime searches for a called method.

Examples

The following examples show how to invoke a method using the Perform action. You should notice the following facts about these examples:

   <actions>
      <!-- Example 1 -->
      <perform value="$importedVar.update( 5, 'Application', $str$)$" />

      <!-- Example 2 -->
      <perform value="$MyClass.myInit('all')$" />

      <!-- Example 3 -->
      <perform value="$fip.close()$" />

      <!-- Example 4 -->
      <perform value="$zis.createZipEntry( $name$ )$" />

      <!-- Example 5 -->
      <perform value="$ht.clear()$" />
   </actions>

 

PlayMacro action (<playmacro> element)

The PlayMacro action launches another macro.

When the macro runtime performs a PlayMacro action, it terminates the current macro (the one in which the PlayMacro action occurs) and begins to process the specified macro screen of the target macro. This process is called chaining. The calling macro is said to "chain to" the target macro. There is no return to the calling macro.

You must specify in the PlayMacro action the name of the target macro and, optionally, the name of the macro screen in the target macro that you want the macro runtime to process first.

You can have the macro runtime transfer all of the variables with their contents from the calling macro to the target macro.

Adding a PlayMacro action

Outside of a Condition element:

Inside a Condition element:

You can have as many Condition elements in the macro as you like, with each Condition element containing one PlayMacro action in its Condition is True branch and one PlayMacro action in its Condition is False branch.

The Macro Editor enforces these rules.

Target macro file name and starting screen

Use the Macro Name field to specify the name of the target macro.

Use the Start Screen Name listbox to select the macro screen in the target macro that you want the macro runtime to process first:

Transferring variables

You can have the macro runtime transfer to the target macro all the variables that belong to the calling macro, including the contents of those variables, by setting the Variable Transfer listbox to Transfer (the default is No Transfer).

This transferring of variables and their contents allows you to use variables to pass parameters from the calling macro to the target macro.

After the target macro gets control, it can read from and write to the transferred variables in the same way that it reads from and writes to variables that it has declared itself.

For example, if MacroA currently has two integer variables named StartRow and StartCol, with values of 12 and 2, and then MacroA launches MacroB with a PlayMacro action, then MacroB will start out having variables StartRow and StartCol with values of 12 and 2.

Even if the transferred variable belongs to an imported type and contains a Java object, the target macro can still refer to the transferred variable and call methods on the Java object, or can write some other object into that transferred variable.

Requirements for transferring variables

The target macro must have selected the advanced macro format (see Basic and advanced macro format).

Restriction

Please notice the following restriction on all types of transferred variables:

Additional information

If the target macro creates a variable with the same name and type as a transferred variable, then the macro runtime uses the created variable rather than the transferred variable.

When the target macro needs to import a type

In the target macro, if you want to use a transferred variable that belongs to an imported type, then you do not need to import that same type in the target macro. Examples of operations where you do not need to import the type are as follows:

However, in the target macro, if you want to use the name of an imported type, then import that type. Examples of operations where import the type:

Examples

The following example shows a PlayMacro action:

<actions>
   <playmacro name="TargetMacro" startscreen="*DEFAULT*"
            transfervars="Transfer" />
</actions>

 

Prompt action (<prompt> element)

The Prompt action provides a powerful way to send immediate user keyboard input into the 3270 or 5250 application or into a variable.

The Prompt action displays on top of the host terminal a prompt window that contains a message, an input field, and an OK button. After the user types text into the input field and clicks OK, the Prompt action uses the input in one or both of the following ways:

A typical use of this action, but by no means the only use, is to permit the user to provide a password. Many scenarios require that a macro log on to a host or start an application that requires a password for access. Because a password is sensitive data and also typically changes from time to time, you probably do not want to code the password as an immediate value into the macro.

With the Prompt action, you can display a message that prompts the user for a password and that lets the user type the password into the input field. After the user clicks OK, the macro runtime types the input into the host terminal at the row and column location that you specify. The input sequence can include action keys such as [enterreset], so that if the user types MyPassword[enterreset] the macro runtime not only can type the password into the password field but also can type the key that completes the logon or access action. (Or, you can put the action key into an Input action that immediately follows the Prompt action.)

Displaying the prompt window

Parts of the prompt window

You should type the prompt text (such as 'Please type your password:') into the Prompt Name field, not into the Prompt Text field. (The Prompt Text field is an optional field than you can use to store a note containing details about the particular Prompt action.)

The macro runtime displays a prompt window with the following characteristics:

Default Response

In the Default Response field, which is optional, you can type the text of a default response that you want to appear in the input field of the prompt window when the prompt window is displayed. If the user does not type any keyboard input into the input field of the prompt window, but rather just clicks OK to indicate that input is complete, then the macro runtime processes the default response that is contained in the input field.

For example, if the user normally uses ApplicationA but sometimes uses ApplicationB, you could type ApplicationA into the Default Response field. When the macro runtime performs the Prompt action, the prompt window appears with the text ApplicationA already displayed in the input field. The user either can click OK (in which case the macro processes ApplicationA as the contents of the input field) or else type ApplicationB into the input field and then click OK (in which case the macro processes ApplicationB as the contents of the input field).

Password Response

If you set the Password Response listbox to true (the default is false) then when the user types each key into the input field of the prompt window, the macro runtime displays an asterisk (*) instead of the character associated with the key.

For example, with the Password Response listbox set to true (or resolving to true at runtime) then if the user types 'Romeo' the macro runtime displays ***** in the input field.

Processing the contents of the input field

Response Length

The value in the Response Length field specifies not the size of the input field, but the number of characters that the macro runtime allows the user to type into the input field.

For example, if you set the Response Length field to 10, then the macro runtime allows the user to type only 10 characters into the input field.

Action keys and Translate Host Action Keys

Both you (in the Default Response input field) and the user (in the input field of the Prompt window) can use action keys (such as [enterreset], [copy], and so on) as you would in the String field of an Input action (see Input string).

The Translate Host Action Keys listbox and its effect are exactly like the Translate Host Action Keys listbox in the Input action (see Translate Host Action Keys). If you set this listbox to true, which is the default value, then the macro runtime interprets an action key string (such as [copy]) as an action key rather than as a literal string.

Handling the input sequence in the host terminal

Use the Row and Column fields to specify the row and column position on the host terminal at which you want the macro runtime to start typing the input sequence. To have the macro runtime start typing the input sequence at the current position of the text cursor, you can set either or both of the Row and Column fields to 0. As with the Input action, the row and column position must lie within a 3270 or 5250 input field at runtime, or else the host terminal responds by inhibiting the input and displaying an error symbol in the Operator Information Area, just as it responds to keyboard input from an actual user.

You can have the macro runtime clear the contents of the input field before typing begins, by setting the Clear Host Field listbox to true.

The Move Cursor to End of Input field has the same function and effects as the button of the same name in the Input action (see Move Cursor to End of Input).

You can have the macro runtime not display the input sequence in the input field by setting the Don't Write to Screen listbox to true. This field is enabled only when the Assign to a Variable checkbox is selected.

Assigning the input sequence to a variable

You can have macro runtime store the input sequence into a variable by selecting the Assign to a Variable listbox.

In the popup window for specifying a new variable, you can specify the name of a variable that the current macro inherits from another macro, or you can specify the name of a new variable that you want to create in the current macro. If you want to create a new variable in the current macro, select the Create variable in this macro checkbox and select the type of the new variable.

The macro runtime stores the input sequence as a string, and consequently you might want to specify a string variable as the variable to receive the input. However, if the variable is of some other type than string, then the macro runtime will try to convert the input to the data type of the target variable according to the usual rules (see Automatic data type conversion).

The promptall attributes

You can have the macro runtime combine the popup windows from all <prompt> elements into one large prompt window and display this large prompt window at the beginning of the macro playback, by setting the promptall attribute of the <HAScript> element to true (see <HAScript> element).

The promptall attribute in the <actions> element works similarly (see <actions> element).

 

Trace action (<trace> element)

The Trace action sends a trace message to a trace destination that you specify, such as the HATS Studio console or the WebSphere console.

Use the Trace Handler listbox to specify the trace destination to which you want the trace message sent:

Use the Trace Text input field to specify the string that you want to send to the trace destination.

Example

The following example shows how to send trace messages to the HATS Studio console. This example uses the following action elements: Trace and Variable update.

You can copy the text of this macro script from this document into the system clipboard, and then from the system clipboard into the source view (see Samples). After you save this script in the Macro Editor, you can edit it either with the Macro Editor or in the source view.

You should notice the following facts about this example:

<HAScript name="TRACE" description=" " timeout="60000" pausetime="300"
            promptall="true" author="" creationdate="" supressclearevents="false"
             usevars="true" ignorepauseforenhancedtn="false"
             delayifnotenhancedtn="0">
   <vars>
      <create name="$strData$" type="string" value="'Original value'" />
   </vars>
   <screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">
      <description>
          <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
      </description>
      <actions>
         <trace type="SYSOUT" value="'The value is '+$strData$"  />
         <varupdate name="$strData$" value="'Updated value'" />
         <trace type="SYSOUT" value="'The value is '+$strData$"  />
      </actions>
      <nextscreens timeout="0" >
      </nextscreens>
  </screen>

This script causes the macro runtime to send the following data:

The value is +{$strData$ = Original value}
The value is +{$strData$ = Updated value}

In the trace output above you should notice that instead of just displaying the value of $strData$, the Debug action displays both the variable's name and its value inside curly braces {}.

 

Variable update action (<varupdate> element)

The <varupdate> element stores a value into a variable. You must specify:

During macro playback the macro runtime performs the Variable update action by storing the specified value into the specified variable.

You can also use the Variable update action in a <description> element (see Processing a Variable update action in a description).

The value can be an arithmetic expression and can contain variables and calls to imported methods. If the value is an expression, then during macro playback the macro runtime evaluates the expression and stores the resulting value into the specified variable.

The Variable update action works like an assignment statement in a programming language. In a Java program you could write assignment statements such as:

boolVisitedThisScreen = true;
intVisitCount = intVisitCount + 1;
dblLength = 32.4;
strAddress ="123 Hampton Court";

With the Variable update action you type the left side of the equation (the variable) into the Name field on the Variable Update window and type the right side of the equation (the value) into the Value field on the same window. To create the equivalents of the Java assignment statements above, you would write:

Table 13. Examples of variable names and values
In the Name input field: In the Value input field:
$boolVisitedThisScreen$ true
$intVisitCount$ $intVisitCount$+1
$dblLength$ 32.4
$strAddress$ '123 Hampton Court'

The value that you provide must belong to the correct data type for the context or be convertible to that type (see Automatic data type conversion).

The great usefulness of the Variable update action is due to the facts that:

For more information on expressions see Data types, operators, and expressions.

Variable update action with a field variable

Use a Variable update action to update a field variable is a convenient way of reading the contents of a 3270 or 5250 field in the host terminal and storing the field's contents as a string into a variable.

A field variable is a type of string variable. A field variable contains a string, just as a string variable does, and you can use a field variable in any context in which a string variable is valid. However, a field variable differs from a string variable in the way in which a string is stored into the field variable. The string that a field variable contains is always a string that the macro runtime has read from a 3270 or 5250 field in the current host terminal.

When you use the Variable update action to update a string variable, you specify the following information in the Variable update window:

When the macro runtime performs the Variable update action, the macro runtime:

  1. Recognizes that the variable is a field variable.

  2. Looks at the location string that is to be used to update the field variable.

  3. Finds in the current host terminal the row and column location specified by the location string.

  4. Finds in the current host terminal the 3270 or 5250 field in which the row and column location occurs.

  5. Reads the entire contents of the 3270 or 5250 field, including any leading and trailing blanks.

  6. Stores the entire contents of the field as a string into the field variable.

You can then use the field variable in any context in which a string is valid. For example, you can concatenate the field variable with another string, as in the following:

'The field\'s contents are'+ $fldPrintOption$

As an example, suppose that the host terminal contains a 3270 or 5250 field with the following characteristics:

You set up a Variable update action with the following values:

When the macro runtime performs this Variable update action, the macro runtime reads the entire contents of the field and stores the contents as a string into $fldData$. The field variable $fldData$ now contains the string 'Print VTOC information'.

Reading part of a field

When you are using a field variable in a Variable update action, you can specify a location string that contains two locations. Use this feature if you want to read only part of the contents of a field.

Type the first and second locations into the Value field with a colon (:) between them. For example, if the first location is 5,14 and the second location is 5,17, then you would type '5,14:5,17'.

When you specify two locations:

As an example, suppose that the host terminal contains a 3270 or 5250 field with the following characteristics:

and suppose that you set up a Variable update action with the following values:

When the macro runtime performs this Variable update action, the macro runtime reads the string 'VTOC' from the field (beginning at the position specified by the first location string and continuing until the position specified by the second location string) and stores the string 'VTOC' into $fldData$.

If the second location lies beyond the end of the field, the macro runtime reads the string beginning at the first location and continuing until the end of the field. The macro runtime then stores this string into the field variable.

 

Home