Macro actions

Actions by function

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

How actions are performed

The runtime context

As you might 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 have ordered the actions in the Actions list.

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 goes 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 Using the value that the variable holds).

For information about specifying actions using the VME, see Working with actions, and using the AME, see Actions tab.

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 is completely connected.

This action can be specified using the Source tab in the VME, and using the Actions tab in the AME, see Comm wait action.

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 indicates 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 CONNECTION_WORKSTATION_ID_READY). In most situations you want to specify that persistent, ending state in the Comm wait action.

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.

Examples

Figure 14 shows an example of specifying a communication state that will wait until a Telnet session negotiation has begun or until 10 seconds have elapsed without a Telnet negotiation session, whichever occurs first.

Figure 14. Example of Comm wait action
<commwait value="CONNECTION_READY" timeout="10000" />

For more information, see <commwait> element.

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.

This action can be specified using the VME, see Evaluate (If) action, and using the AME, see Conditional action.

Conditional action not allowed within a Conditional action

The macro editor does not allow you to create a Conditional action inside another Conditional action. 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.

Example

The following code fragment prompts the user for input. If the input string is the string true, the code fragment writes the message You typed TRUE on the host screen. If the input string is any other string, the code fragment writes the message You typed FALSE. This example uses the following actions: Prompt action, Condition action, and Input action.

You can copy this code fragment from this document into the system clipboard, and then from the system clipboard into the source view. Because this code is a fragment, you must copy it into a macro screen in an existing macro script. You must also create a string variable named $strData$. To create the variable, add the follow lines after the <HAScript> begin tag and before the first <screen> element:

<vars>
   <create name="$strData$" type="string" value="" />
</vars>

After you save the script in the macro editor, you can edit it either with the macro editor or in the source view.

Notice the following facts about this example:

Figure 15. Sample code fragment showing a Condition action
<actions>
   <prompt name="’Type true or false’" description="" row="0" col="0"
               len="80" default="" clearfield="false" encrypted="false"
               movecursor="true" xlatehostkeys="true" assigntovar="$strData$"
               varupdateonly="true" />
   <if condition="$strData$" >
       <input value="'You typed TRUE'" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
   </if>
   <else>
       <input value="'You typed FALSE'" row="0" col="0" movecursor="true" xlatehostkeys="true" encrypted="false"/>
   </else>
</actions>

For more information, see <if> element.

Extract action (<extract> element)

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

This action can be specified using the VME, see Extract action, and using the AME, see Extract action.

Treatment of nulls and other characters that do not display

Text captured from the TEXT_PLANE does not contain any nulls (0x00) or other characters that do not display. 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 attribute 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
In addition,

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

Because the continuous attribute 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 attribute 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 attribute 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 attribute is set to false in this example, $strTmp$ would contain a string of 24 characters, 'Enter / on tline command'.

Unwrap attribute

You can use this option with the continuous attribute set to either false or true.

When you set the unwrap attribute 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 toolkit).

Do not confuse the unwrap attribute with the wrap attribute 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 attribute)).

When unwrap is true and continuous is false

When the continuous attribute is false, the row and column pairs represent the corners of a rectangular block of text. When you set the unwrap attribute 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 attribute 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:

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 is true and continuous is true

When the continuous attribute 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 the unwrap attribute to true, the macro runtime processes the continuous sequence of text as follows:

For more information, see <extract> element.

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 [enter] and others).

This action simulates keyboard input from an actual user.

This action can be specified using the VME, see Input action, and using the AME, see Input action.

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

Translate host action keys (xlatehostkeys attribute)

The xlatehostkeys attribute indicates whether the macro runtime is to interpret action key names (such as [copy], [enter], [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 xlatehostkeys attribute is true, then in performing this input sequence the macro runtime moves the text cursor up two rows and then types Hello world beginning at row 2, column 10. In contrast, if the xlatehostkeys attribute is false, then the macro runtime types [up][up]Hello world beginning at row 4, column 10.

Move cursor to end of input (movecursor attribute)

When the movecursor attribute 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 movecursor attribute 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.

Encrypted attribute

You can use the encrypted attribute to encrypt the input key sequence contained in the value attribute (the String field). When you encrypt the contents of the value attribute, Host On-Demand stores only the encrypted version of the input key sequence into the macro script (in the <input> element) and does not retain the plain text (unencrypted) version of the input key sequence.

For example, Figure 16 shows an <input> element with an unencrypted input key sequence ('myPassword'):

Figure 16. <input> element with unencrypted input key sequence
input value="’myPassword’" row="20" col="16" movecursor="true"
          xlatehostkeys="true" encrypted="false" />

In contrast, Figure 17 shows the same <input> element with the input key sequence encrypted (I7xae6rSVlVFF6qzhWRfKw==). Notice that in this example the encrypted attribute of the <input> element is set to true:

Figure 17. <input> element with encrypted input key sequence
input value="I7xae6rSVlVFF6qzhWRfKw==" row="20" col="16"
          movecursor="true" xlatehostkeys="true" encrypted="true" />

In the macro editor, an encrypted input key sequence is displayed with asterisks (for example, the encrypted version of 'myPassword' is displayed in the String field as ************************ rather than as I7xae6rSVlVFF6qzhWRfKw==).

Encryption allows you to include confidential data, such as a password, in an Input action without exposing the confidential data to casual view. An unauthorized person cannot discover the confidential data by viewing the macro script with a text editor, with the macro editor, or in the source view.

After you encrypt the input key sequence, Host On-Demand does not allow you or anyone else to use the macro editor or the source view to decrypt it. Host On-Demand does not decrypt an encrypted input key sequence of an Input action until the macro runtime processes the Input action during macro playback. When the macro runtime processes the Input action, the macro runtime decrypts the encrypted input key sequence and types the unencrypted version into the session window beginning at the specified row and column location.

Typically in a 3270 or a 5250 environment, for a confidential input key sequence such as a password, the host application creates a non-display input field as the destination of the input key sequence, so that blanks or asterisks (*) are displayed instead of the plain text.

However, a security exposure still exists if the macro script is exposed to more than casual view. A clever foe who gains access to a copy of the macro script can discover the original unencrypted input key sequence by editing the row and column fields of the Input action so that during macro playback the macro runtime types the decrypted input key sequence into a normal display field.

For greater security, you can use a Prompt action instead of an Input action. With a Prompt action, the input key sequence is not stored in the macro script, not even in encrypted form. Instead, during macro playback, when the macro runtime processes the Prompt action, the macro runtime pops up a window with an input field and a message prompting the end user to type an input key sequence. When the end user types the input key sequence and clicks OK, the macro runtime removes the popup window and directs the input key sequence into the session window at the specified row and column location.

Note:
The default values for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts in the macro editor. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.

Using an Input action does have this advantage, that the macro script runs automatically during macro playback without the end user having to intervene. However, if the confidential data changes (for example, if a password expires and a new and different password is required) then the Input action must be updated with the new input key sequence.

Automatic encryption during macro recording

During macro recording, for 3270 Display and 5250 Display sessions only, HCL ZIETrans automatically records a password input sequence as an Input action with an encrypted input key sequence.

Using the Encrypt string (VME) or Password (AME) check box

If the input key sequence was automatically encrypted during macro recording, when you look at the Input action in the macro editor, the Encrypt string (VME), or Password (AME), check box is selected, and the String field contains some number of asterisks (such as ******) representing the encrypted input key sequence.

In contrast, if the input key sequence was not automatically encrypted during macro recording (perhaps because the session was not a 3270 or 5250 display session, or perhaps because the input field was not a non-display input field) then the check box is cleared and the String field contains the unencrypted input key sequence.

If the input key sequence was not automatically encrypted during macro recording, you can encrypt it in the macro editor. Follow these steps to encrypt the input key sequence. Before you start, clear the check box if it is not already cleared.

  1. If the input key sequence that you want is not already present in the String field, type the input key sequence into the String field.
  2. Select the check box.

If you want to create an encrypted input key sequence, but you do not want the input key sequence to be displayed in unencrypted form as you type it into the String field, use the following method:

  1. Clear the String field if it is not already empty.
  2. Select the check box.
  3. Type the input key sequence into the String field.

After the input key sequence is encrypted, you might decide that you do not want it to be encrypted or that you want to revise it.

If the input key sequence is encrypted and you decide that you do not want it to be encrypted, then follow these steps:

  1. Clear the check box.
  2. Type the unencrypted input key sequence into the String field.

If the input key sequence is encrypted and you decide that you want to revise it, follow these steps:

  1. Clear the String field using the backspace key or the delete key.
  2. Type the revised input key sequence into the String field.

Do not try to revise an encrypted input key sequence by typing over or inserting characters into the string of asterisks in the String field (*******)! If you do, then you corrupt the encrypted input key sequence with your unencrypted revisions. Then the macro editor, believing that you have typed in an unencrypted string, re-encrypts the corrupted sequence. The result is that during macro playback, when the macro runtime processes the Input action, the decrypted sequence is not the input key sequence that you expected. (Also, if you are using the advanced macro format and you do not enclose the corrupted input key sequence with single quotes, the macro editor generates an error message).

Using the source view

The source view follows the same rules for encrypting an input key sequence as the macro editor.

The source view always allows you to do either of the following actions:

You can also, while using the source view, change the value of the encrypted attribute (which activates or deactivates encryption) from true to false, or false to true.

However, if you want to use the source view to modify the value of the value attribute (which contains the encrypted or unencrypted input key sequence), and the encrypted attribute is set to true, then completely delete the encrypted input key sequence (so that it reads value=""), then type in the new input key sequence that you want encrypted.

Do not try to revise an encrypted input key sequence by typing over or inserting characters into an encrypted input key sequence in the value attribute! If you do, then you corrupt the encrypted input key sequence with your unencrypted revisions.

Encrypting a variable name

Although you can type a variable name (such as $var1$) into the String field in the macro editor (or into the value part of the value attribute in the source view) and encrypt the name of the variable (using the same steps that you would use to encrypt a normal input key sequence) this normally is not a useful thing to do. The reason is that when you encrypt a variable name only the characters making up the variable name are encrypted. The contents of the variable itself are not encrypted.

During macro playback, the macro runtime decrypts the encrypted text to get the plain text (such as $var1$), sees that the plain text is a variable name, and then evaluates the variable in the usual way.

For more information, see <input> element.

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.

This action can be specified using the VME, see Set cursor position action, and using the AME, see Mouse click action.

For more information, see <mouseclick> element.

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:

This action can be specified using the VME, see Pause action, and using the AME, see Pause action.

For more information, see <pause> element.

Perform action (<perform> element)

The Perform action invokes a method belonging to a Java class that you have imported.

This action can be specified using the VME, see Perform action, and using the AME, see Perform action.

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.

Examples

The Figure 18 shows how to invoke a method using the Perform action. Notice the following facts about these examples:

Figure 18. Example of the Perform action
   <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>

For more information, see <perform> element.

PlayMacro action (<playmacro> element)

The PlayMacro action launches another macro.

This action can be specified using the VME, see Play macro action, and using the AME, see Playmacro action.

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 a Condition element, you can add only one PlayMacro action to a macro screen, and that PlayMacro action must be the last action in the Actions list (<actions> element) of the macro screen.

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 true branch and one PlayMacro action in its false branch.

The Macro Editor enforces these rules.

Using target macros with prompts

If a target macro requires a prompt value, prompt for the required value in the first macro of the chain. For example, if you chain from calling MacroA to target MacroB and MacroB needs an account number from the user, add the prompt action for the account number to MacroA. Assign the response to a macro variable using the assigntovar attribute of the <prompt> action. In the <playmacro> action in calling MacroA, specify that variables are transferred to the target macro by setting transferVars="Transfer". In the target macro, use the macro variable in the place where you would have used the prompt action. For example, use an <input> action with the macro variable as the input value instead of a prompt action. If there are several macros in the chain, all prompts must occur in the first macro. For example, if you chain from MacroA to MacroB to MacroC and MacroC requires a prompt value, prompt for the MacroC value in MacroA and pass it along the chain.

Any time that you use macro variables with prompts in macros, you must specify a value of promptall=true in the <HAScript> tag of the macro. This is the default value for the attribute. Ensure that your calling macro, which contains all of the prompts for the chain, is using a value of true for promptall.

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 transferVars attribute 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 starts 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

The following restriction applies to all types of transferred variables: You cannot use the transferred variable in the Initial Value field of a variable defined in the target macro.

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 you must import that type. Examples of operations where you must import the type:

The following example shows a PlayMacro action:

Figure 19. Example of the PlayMacro action
<actions>
   <playmacro name="TargetMacro" startscreen="*DEFAULT*"
            transferVars="Transfer" />
</actions>  

For more information, see <playmacro> element

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.

This action can be specified using the VME, see Prompt action, and using the AME, see Prompt action.

The Prompt action displays on top of the host terminal a prompt window that contains a message, an input field, and three buttons (OK, Cancel, Help). 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 [enter], so that if the user types MyPassword[enter] 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.)

Note:
The default values for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts in the macro editors. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.

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

For more information, see <prompt> element.

SQLQuery action (<sqlquery> element)

The SQLQuery action is a very useful and powerful action that allows you to send an SQL statement to a host database, retrieve any data resulting from the SQL statement, and then write the data into a Host On-Demand macro variable.

This action can be specified using the Source tab in the VME, and using the Actions tab in the AME, see SQLQuery action.

You can use the SQLQuery action in any type of session that supports macros (3270 Display, 5250 Display, or VT Display).

The database server to which you connect can be on a different host than the host running your application session.

The SQLQuery action supports only SQL statements of type Select. It does not support SQL statements of type Insert, Update, or Delete.

The SQLQuery action requires a database driver that is accessible to both the HCL ZIETrans Toolkit environment and the specific HCL ZIETrans applications using the SQLQuery action. The database driver is specific to the database being accessed; obtain this driver from the database administrator.

For the SQL Wizard to function correctly within the HCL ZIETrans Toolkit, the database driver file should be placed in the lib\ext directory of the Java Runtime Environment (JRE) being used by the Rational® Software Delivery Platform (for example, RAD_INSTALL_DIR\jre\lib\ext). You must restart the Rational Software Delivery Platform (if it was active) after copying the database driver to the JRE location.

The HCL ZIETrans application must also have access to the database driver file when it is deployed. For HCL ZIETrans Web applications, the database driver file should be added to the EAR level. After the file is added to the EAR level, each WAR in the HCL ZIETrans application that uses the SQLQuery action must have its META-INF/MANIFEST.MF file updated to include the database driver file. To ensure that the update to the MANIFEST.MF file is made correctly, edit it using the JAR Dependency Editor.

For more information, see <sqlquery> element.

Trace action (<trace> element)

The Trace action sends a trace message to a trace destination that you specify, such as the HCL ZIETrans Toolkit console or the WebSphere® console. In addition, HCL ZIETrans adds macro traces to the HCL ZIETrans runtime trace.

This action can be specified using the Source tab in the VME, and using the Actions tab in the AME, see Trace action.

Example

The example in Figure 20 shows how to send trace messages to the HCL ZIETrans Toolkit 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.

Notice the following facts about this example:

Figure 20. Sample code TRACE
<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 in Figure 20 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, notice that instead of just displaying the value of $strData$, the Debug action displays both the variable's name and its value inside braces.

For more information, see <trace> element.

Variable update action (<varupdate> element)

The <varupdate> element stores a value into a variable. During macro playback the macro runtime performs the action by storing the specified value into the specified variable.

You must specify:

This action can be specified using the VME, see Update macro variable action, and using the AME, see Variable update action.

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 variable name field in the macro editor and type the right side of the equation (the value) into the value field. To create the equivalents of the Java assignment statements above, you would use the values shown in Table 11:

Table 11. Example of variable names and values
In the variable name field: In the value 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 Variable update action is useful because:

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

Variable update action with a field variable

Using 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 is defined in the <vars> element of the macro script but does not take an initial value. The following contains an example of a field variable.

<vars>
<create name=$intUpdate$" type="integer" value="3"/>
<create name="$strData$" type="string" value="'hello'"/>
<create name="$fieldVar$" type="field" />
</vars>

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:

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:

In addition, 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.

For more information, see <varupdate> element.