Macro actions
General macro
information
The next few sections provide general information about macros.
The actions by function
Here is a list of all the actions, grouped according to function.
- Interaction with the user:
- Input (keystrokes and key-activated functions, such as copy to clipboard)
- Mouse click
- Prompt
- Getting data from the application
- Extract
- SQLQuery
- Variable update
- Waits
- Comm wait
- Pause
- Programming
- Conditional
- Perform (call a Java method)
- Play macro (chain to another macro)
- Variable update
- Debug
- Trace
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 have 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 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).
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 23 shows a sample Actions tab:
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.
Creating a new action
Looking again at the Actions listbox in Figure 23, you should 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 23, the displayable part of the Actions listbox is not tall enough to show the whole list at once. Here is the entire list:
<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> <new sql query 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> <new sql query action>
When the macro runtime processes this macro screen, it performs 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 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 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 14 lists the name and significance of each state:
| 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:
- Connection Inactive - Here the session is completely disconnected.
- Connection Workstation ID Ready - Here the session is completely connected.
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
<commwait value="CONNECTION_READY" timeout="10000" />
Conditional action (<if> element and <else> element)
The Conditional action contains the following items:
- A conditional expression that the macro runtime evaluates to true or false.
- A list of actions that the macro runtime performs if the condition evaluates to true. (Optional)
- A list of actions that the macro runtime performs if the condition evaluates to false. (Optional)
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:
- The Action listbox on the Condition is True tab allows you to create and edit actions in the same way that the Action listbox on the Actions tab does.
- The Delete button and the Change Order button on the Condition is True tab allow you to delete or reorder actions in the same way that the Delete button and the Change Order button on the Actions tab do.
- The lower area of the Condition is True tab allows you to edit the values of the currently selected action in the same way that lower area of the Actions tab does.
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.
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.
Example
The following code fragment prompts the user for input. If the input string is the string true, the code fragment displays a message window with the message "You typed TRUE". If the input string is any other string, the code fragment displays a message window with the message "You typed FALSE". This example uses the following actions: Prompt action, Condition action, and Message 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, 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.
You should notice the following facts about this example:
- The example consists of one code fragment containing an <actions> element and the actions inside it.
- The first action is a Prompt action that displays a message window and copies the user's input into the variable $strData$, without writing the input into an input field in the session window.
- The first part of the condition action (the <if> element) contains the condition, which is simply $strData$.
- Because $strData$ is a string variable in a boolean context, the macro runtime tries to convert the string to a boolean value (see Automatic data type conversion). If the user's input is the string 'true' (in upper, lower, or mixed case), then the conversion is successful and the condition contains the boolean value true. If the user's input is any other string, then the conversion fails and the condition contains the boolean value false.
- If the condition is true, then the macro runtime performs the action inside the <if> element, which is a Message action displaying the message You typed TRUE. Then, having exhausted all the actions to be performed when the condition is true (just one action here), the macro runtime skips over the <else> action and continues as usual.
- In contrast, if the condition is false, then the macro runtime skips over the actions in the <if> element and begins performing the actions in the <else> element, which include one Message action that displays the message You typed FALSE. After performing all the actions in the <else> action, then the macro runtime continues as usual.
<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$" >
<message title="" value="'You typed TRUE'" />
</if>
<else>
<message title="" value="'You typed FALSE'" />
</else>
</actions>
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.
- Set the Continuous Extract option, if necessary
- Specify an area on the host terminal that you want to capture.
- Specify an extraction name.
- Specify TEXT_PLANE as the data plane.
- 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 interprets 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). You can 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 must 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 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 converts 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 terminates 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:
- Initializes the result string to an empty string.
- Reads the rectangular block of text row by row, concatenating each row to the result string.
- Stores the result string in the specified variable.
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:
- Continuous Extract is false.
- The row and column pairs are (16, 5) (the 'O' of Outlist) and (18, 12) (the 'd' of 'Reserved').
- The extraction name is 'Extract1'.
- The data plane is TEXT_PLANE.
- The string variable $strTmp$ is the variable in which the result string is to be stored.
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:
- Initializes the result string to an empty string.
- Reads the continuous sequence of text from beginning to end, wrapping around from the end of one line to the beginning of the next line if necessary.
- Stores the result string in the specified variable.
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:
- Continuous Extract is true.
- The row and column pairs are (21, 9) (the 'E' of 'Enter') and (22, 20) (the 'd' of 'command').
- The extraction name is 'Extract1'.
- The data plane is TEXT_PLANE.
- The string variable $strTmp$ is the variable in which the result string is to be stored.
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
You can 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:
- If the field begins outside the row and continues into the row, then the macro runtime ignores the field.
- If the field begins inside the row and ends inside the row, then the macro runtime includes the field's contents in the result.
- If the field begins inside the row and ends outside the row, then the macro runtime includes the contents of the entire field (including the part outside the rectangular block of text) in the result.
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:
Reset statistics Catalog or display information of an entire data set
Finally, suppose that:
- Continuous Extract is false (this is the default setting).
- Unwrap Text is true.
- The row and column pairs are (9,63) (the 'n' of 'print') and (11,73) (the ' ' after 'or').
- The extraction name is 'Extract1'.
- The data plane is TEXT_PLANE.
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:
- If the field begins outside the sequence and continues into the sequence, then the macro runtime ignores the field.
- If the field begins inside the sequence and ends inside the sequence, then the macro runtime includes the field's contents in the result.
- If the field begins inside the sequence and ends outside the sequence, then the macro runtime includes the contents of the entire field (including the part outside the continuous sequence) in the result.
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] 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 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 (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 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.
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]These keys are not supported by HATS since HATS does not create a Display Session (HOD Terminal).
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 moves 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 types [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.
Password
You can use the Password checkbox to encrypt the input key sequence contained in the String field. When you encrypt the contents of the String field, 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 28 shows an <input> element with an unencrypted input key sequence ('myPassword'):
input value="'myPassword'" row="20" col="16" movecursor="true"
xlatehostkeys="true" encrypted="false" />
In contrast, Figure 29 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:
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 displayable 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.
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, HATS automatically records a password input sequence as an Input action with an encrypted input key sequence.
Using the Password checkbox
If the input key sequence was automatically encrypted during macro recording, when you look at the Input action in the Macro Editor, the Password checkbox is selected (checked) 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 Password checkbox is cleared (not checked) and the String field contains some 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 (uncheck) the Password checkbox if it is not already cleared.
- 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.
- The input key sequence appears normally in the String field (for example, 'myPassWord').
- If you are using the advanced macro format, remember to enclose the input key sequence in single quotes ('myPassWord').
- Select the Password checkbox.
- The Macro Editor encrypts the input key sequence and displays it in the String field using asterisks (***********************).
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:
- Clear the String field if it is not already empty.
- Select the Password checkbox.
- Type the input key sequence into the String field.
- If you are using the advanced macro format, remember to enclose the input key sequence in single quotes ('myPassWord').
- As you type into the String field, the Macro Editor displays the characters using asterisks ('myPassword' is displayed as ************).
- When the input focus leaves the String field (that is, when you click some other field) then the Macro Editor encrypts the input key sequence.
After the input key sequence is encrypted, you may 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...
- Clear the Password checkbox.
- The Macro Editor discards the encrypted string and clears the String field.
- If for some reason the String field is not cleared, then delete the characters in it using the backspace key or the delete key.
- 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,...
- Clear the String field using the backspace key or the delete key.
- Delete the entire encrypted input key sequence, so that the field is empty.
- Type the revised input key sequence into the String field.
- If you are using the advanced macro format, remember to enclose the input key sequence in single quotes ('myPassWord').
- As you type into the String field, the Macro Editor displays the characters using asterisks ('myPassword' is displayed as ************).
- When the input focus leaves the String field (that is, when you click some other field) then the Macro Editor encrypts the input key sequence.
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:
- Type into the editable text area a new <input> element that encrypts the input key sequence.
- Paste from the system clipboard into the editable text area an <input> element that encrypts the input key sequence.
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.
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.
Copy and paste example
The following example shows how to mark a block of text in the session window, copy it to the system clipboard, and paste it back into the session window at a new location. This example uses the following action elements: Input action, Mouse click action, and Pause action.
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:
- The example consists of one entire macro script named COPY PASTE.
- The following actions occur in the <actions> element:
- A <pause> action waits one-half second so that when the macro is played back, the user can see what is happening.
- An <input> action types a [copy] action, which copies the marked area to the clipboard.
- A <mouseclick> action sets the cursor to the location where the paste will take place.
- An <input> action types a [paste] key, which pastes the contents of the clipboard to the new location on the session window.
- This macro is written to be run from the ISPF Primary Option Menu. The macro copies the text Spool Display and Search Facility from row 18 to the system clipboard, and then pastes the text from the clipboard to the Option ===> input field in line 4.
- If this example does not paste properly when you run it, make sure that the target area that you have specified lies within a 3270 or 5250 input field.
<HAScript name="COPY PASTE" description=" " timeout="60000" pausetime="300"
promptall="true" author="" creationdate="" supressclearevents="false"
usevars="false" >
<screen name="Screen1" entryscreen="true" exitscreen="true"
transient="false">
<description>
<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
</description>
<actions>
<pause value="500" />
<input value="[copy]" row="0" col="0" movecursor="true"
xlatehostkeys="true" encrypted="false" />
<mouseclick row="4" col="15" />
<input value="[paste]" row="0" col="0" movecursor="true"
xlatehostkeys="true" encrypted="false" />
</actions>
<nextscreens timeout="0" >
</nextscreens>
</screen>
</HAScript>
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:
- Any situation in which you want to insert a wait.
- Waiting for the host to update the host terminal. For more information see Screen completion.
- To add delay for debugging purposes.
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 Creating 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:
- You can invoke a method and assign the return value to a variable by using the Update variable action. The variable that receives the return value can be either a variable belonging to a standard type (boolean, integer, string, double) or a variable belonging to an imported type (for example, a variable named $objTmp$ that belongs to the imported type Object, based on the Java class Object).
- You can invoke a method and use the return value as a parameter in a macro action by specifying the method call in the field for the parameter. For example, in the Row parameter of an Extract action you can use a method call that returns an integer value. The macro runtime sees that the parameter is a method call , invokes the method, and uses the integer return value as the value of the Row parameter.
- You can invoke a method as part of any expression by using the method call as a term in the expression. When the macro runtime evaluates the expression, it sees that the term is a method call, invokes the method, and uses the value of the method (for example, a string) as the value of the term.
- You can invoke a method and use the return value as the initial value of a variable that you have just declared.
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 invokes 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:
- In Example 1, the Perform action calls the update() method on the variable
$importedVar$. Notice that:
- The entire method call is enclosed in dollar signs ($).
- In the context of a method call, the variable name itself (importedVar) is not enclosed in dollar signs ($).
- A variable passed as a parameter to a method must be enclosed in dollar signs ($) as usual ($str$).
- A string passed as a parameter to a method must be enclosed in single quotes as usual ('Application').
- In Example 2, the Perform action calls a static method.
- In Example 3, the Perform action calls the close() method belonging to the class to which the variable belongs, such as java.io.FileInputStream.
- In Example 4, the Perform action calls the createZipEntry() method belonging to the class to which the variable belongs, such as java.util.zip.ZipInputStream.
- In Example 5, the Perform action calls the clear() method belonging to the class to which the variable belongs, such as java.util.Hashtable.
<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:
- 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 add one PlayMacro action to the Condition is True branch (<if> element), and that PlayMacro action must be the last action in the branch (<if> element).
- You can also add one PlayMacro action to the Condition is False branch (<else> element), and that PlayMacro action must be the last action in the branch (<else> 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:
- If you want to start the target macro at its usual start screen, then select the *DEFAULT* entry in the Start Screen Name listbox, or provide an expression that evaluates to the value *DEFAULT*.
- If you want to start the target macro at some other screen, then select the name of that screen in the Start Screen Name listbox.
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 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
Please notice the following restriction on all types of transferred variables:
- You cannot use the transferred variable in the Initial Value field of the Variables tab of 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:
- Using the transferred variable as the value of an attribute.
- Calling a method on the transferred variable.
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:
- Declaring a new variable of the imported type.
- Creating a new instance of the imported type.
- Calling a static method of the imported 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 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:
- The Prompt action types the input into an input field of the host terminal.
- The Prompt action interprets the input as a string and stores the input into a variable.
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:
- The prompt window appears on top of the host terminal and is located in the center of the system's desktop window.
- The caption of the prompt window is always Prompt.
- The message that you typed into the Prompt Name field is displayed in the center of the prompt window, followed by an input field.
- A button row across the bottom of the prompt window contains three buttons:
- The OK button causes the macro runtime to process the contents of the input field.
- The Cancel button halts the macro.
- The Help button displays help text explaining how to use the prompt window.
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 can 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 select true in the Password Response listbox (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.
Require Response
If you select true in the Require Response listbox (the default is false) then:
- The macro runtime displays the text string (required) to the right of the input field, to indicate to the end user that input is required for this input field.
- The macro runtime disables the OK button of the prompt window until the
input field of the prompt window contains text.
- The input field can contain text either because you have specified a Default Response or because the user has typed text into the input field.
- When OK is enabled, the end user can click either OK or Cancel, as usual:
- Clicking OK causes the macro to process the Prompt action and continue processing the macro.
- Clicking Cancel terminates the macro playback.
- When OK is not enabled, the end user can click Cancel.
- Clicking Cancel terminates the macro playback.
Thus, setting Require Response to true has the effects of reminding the end user (by displaying (required) to the right of the input field) that a response is required before proceeding, and of requiring the end user to enter text in the input field before clicking OK (by disabling OK until the input field contains text). However, if the Prompt action contains a Default Response, then OK is enabled and the default response is displayed in the input field.
If you select false in the Require Response listbox then:
- The macro runtime does not display the text string (required)to the right of the input field.
- The macro runtime enables the OK button on the prompt window immediately
as soon as the prompt window is displayed, whether or not the input field
contains text.
- The user can click OK or Cancel, as usual:
- Clicking OK causes the macro runtime to process the Prompt action and then to continue processing the macro. In the Prompt action, if the input field is blank, the macro runtime does not send an input key sequence to session window.
- Clicking Cancel terminates the macro playback.
- The user can click OK or Cancel, as usual:
Thus, setting Require Response to false has the effect of allowing the user to continue processing the macro by clicking OK, even if the input field of the prompt is blank.
If the promptall attribute of the <HAScript> element (or of the <actions> element) is set to true, and you have several prompt actions in the macro (or in the macro screen) with Require Response set to true, then at the start of macro playback (or at the start of the playback of the macro screen), when the macro runtime displays all the prompt input fields in a single prompt window, the macro runtime does not enable the OK button in the prompt window until all required input fields contain text (see The promptall attributes ).
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 checking the Assign to a Variable checkbox.
Create a new variable by clicking the <New Variable> entry in the 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 could 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 tries 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).
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.
You can use the SQLQuery action in any type of session that supports macros (3270 Display, 5250 Display, VT Display, or CICS Gateway).
The database server to which you connect can be on a different host than the host running your emulator session.
You can create an SQL statement manually or compose and test an SQL statement using the SQL Wizard.
The SQLQuery action supports only SQL statements of type Select. It does not support SQL statements of type Insert, Update, or Delete.
Use of the SQLQuery action requires that a database driver be made accessible to both the HATS Studio environment and the specific HATS applications using the SQLQuery action. The database driver is specific to the database being accessed and must be obtained from the database administrator. For the SQL Wizard to function properly within the HATS Studio, the database driver file should be placed in the HATS_install_dir\eclipse\plugins\com.ibm.hats_6.0.0\lib directory.
The HATS plugin.xml file must also be updated to include a reference to this database driver file. The reference should be added to the plugin.xml file following the line that references habeansnlv2.jar (<library name="lib/habeansnlv2.jar" />. The plugin.xml file is located in the HATS_install_dir\eclipse\plugins\com.ibm.hats_6.0.0 directory.
After the changes are made, restart the Rational Studio using the -clean option (c:\radv6\rationalsdp -clean ) to ensure that the Studio cache is cleared and rebuilt. If these steps are not followed, you will receive SQL Assist exception errors when you try to connect to the database from the SQL Wizard.
The HATS application must also include the database driver file, so the application has access to it when it is deployed to an application server. The file can be added at the EAR level. Once the file is added to the EAR level, each WAR in the HATS application that uses the SQLQuery action must have its META-INF/MANIFEST.MF updated to include the database driver file. To ensure that the update to the MANIFEST.MF file is made properly, edit it using the JAR Dependency Editor.
Two sections: statement and results
The SQLQuery action window has two main sections: a statement section and a result section.
The statement section occupies the upper area of the window and includes the following fields: Database URL, Driver Identifier, Driver Class, User ID, Password, and Statement. You can modify the information in this section in two ways:
- By creating an SQL statement in the SQL Wizard.
- By typing the information into the fields.
You can also edit any of the fields at any time by typing into the field.
The result section occupies the lower area of the window and includes the remaining field: Output Result To (the $HMLSQLUtil$ macro variable).
Using the SQL Wizard
You can use the SQL Wizard to create an SQL statement and test it. The graphical user interface of the SQL Wizard makes it much easier to create an SQL statement, compared to typing in the entire text of the SQL statement into the Statement field of the Macro Editor. Also, in the SQL Wizard you can run an SQL statement that you are working on and view the results.
- Click SQL Wizard to start the SQL Wizard.
- If there is any information already in the fields of the statement section, then HATS uses this information to initialize the corresponding fields in the SQL Wizard.
- Use the SQL Wizard to create an SQL statement and test it.
- To close the SQL Wizard without changing your macro, click Cancel.
- To save the SQL statement to your macro, do one of the following actions:
- On the Review tab of the SQL Wizard, click Save; or
- On the Results tab of the SQL Wizard, click Save SQL.
The Macro Editor writes the information that you created in the SQL Wizard into the appropriate fields of the statement section. Any already existing information in the fields of the statement section is overwritten. If the information that the Macro Editor writes into a field is a string (for example, the information written into the Database URL field), then the Macro Editor also automatically correctly formats the string depending on the underlying macro type. The following fields are updated:
- Fields in the statement section:
- Database URL
- Driver Identifier
- Driver Class
- User ID
- Password
- Statement
- Click Cancel to close the SQL Wizad.
Using the fields in the statement section
Instead of creating an SQL statement with the SQL Wizard, you can type the information directly into the fields of the statement section. You can also type into any of the fields after you have created an SQL statement.
Database URL
In the Database URL field, type the database URL of the database server that provides access to the database. The format of the database URL depends on the type of Java Database Connectivity (JDBC) driver that you use to access the database (for more information on drivers see Driver Identifier and Driver Class).
The remote server can be located on a host other than the host to which the Host On-Demand emulator session is connected. For example, a SQLQuery action can specify an i5/OS(TM) host, even though the same SQLQuery action is part of a macro that is running in a 3270 Display session connected to a zSeries host.
Consult the documentation provided by the driver vendor for the proper format for the database URL.
Driver Identifier and Driver Class
The JDBC driver that the SLQQuery action uses to access the database is a Java client package used by the HATS application to communicate with a server program on a remote host. This server program on the remote host provides access to the database.
If you need a JDBC driver, contact the administrator of the remote database server to obtain the driver.
In the Driver Identifier listbox of the SQLQuery action window in the Macro Editor, select Other.
When you select Other in the Driver Identifier listbox, then type the fully qualified class name of the driver into the Driver Class field. If you do not know the fully qualified class name, contact the provider of the driver. When you type in the name, remember that case is significant (for example, com is different from COM).
User ID and Password
If the database connection requires a user id and a password, then type the user id into the User ID field and the password into the Password field.
HATS encrypts the key sequence that you type into the Password field. This encryption works exactly like the encryption used when the Password checkbox is selected in an Input action (see Password). Remember:
- When you type a password (such as mypass) into the Password field, the Macro Editor displays the password using asterisks (******).
- When you move the input focus to another input field, the Macro Editor:
- Generates an encrypted version of the password (such as q0eqOskTUBQ=).
- Displays the encrypted version of the password in the Password field using asterisks (************). (You can see the actual characters of the encrypted version of the password in the Macro Editor.)
- The password is a string. Therefore, if you are using the advanced macro format, remember to type the password enclosed in single quotes (for example, 'mypass'). The Macro Editor encrypts the entire string, including the single quotes.
- If you need to modify the password after the Macro Editor has encrypted it, be sure to completely delete all the characters in the field before typing in the new password.
Statement
Type or paste an SQL statement into the Statement field. If the Statement field already contains an SQL statement, you can edit it (even if the SQL statement was created using the SQL Wizard).
The Macro Editor does not check the format of the SQL statement for validity. If the format is invalid, a run-time error occurs when the macro runtime processes the SQLQuery action.
You can spread the SQL statement over several lines or write it all on one line. Figure 33 and Figure 34 show the same SQL statement written over several lines and written as one line. Either way is correct.
SELECT
*
FROM
SQLTEST.EX01
WHERE
(
( SQLTEST.EX01.DESCRIPT is not null )
)
SELECT * FROM SQLTEST.EX01 WHERE((SQLTEST.EX01.DESCRIPT is not null))
Remember that if you are using the advanced macro format enclose the SQL statement in single quotes and follow the rules for special characters. Below, Figure 35 and Figure 36 show the same SQL statement written for the basic macro format and for the advanced macro format:
select * from hodtest.ex01 where
((hodtest.ex01.descript='Edit Products'))
'select * from hodtest.ex01 where
((hodtest.ex01.descript=\'Edit Products\'))'
You can use either upper case or lower case for reserved words (such as select) and database names and fields (such as hodtest.ex01.descript), but use exact case for matching strings (such as 'Edit Products'). Thus the two SQL statements in Figure 37 are equivalent:
select * from hodtest.ex01 where
((hodtest.ex01.descript='Edit Products'))
SELECT * FROM HODTEST.EX01 WHERE
((HODTEST.EX01.DESCRIPT='Edit Products'))
Using the result section
The fields in the result section control how the SQLQuery action uses the data resulting from the SQL statement. You can write the data into a Host On-Demand macro variable.
Storing the data into a macro variable ($HMLSQLUtil$)
The default destination for the data resulting from an SQLQuery action is the Host On-Demand macro variable $HMLSQLUtil$. The Host On-Demand runtime always updates this variable with the results of a successful SQLQuery action.
To store data into $HMLSQLUtil$, expand the Output Result To listbox and click $HMLSQLUtil$.
To use the data stored in $HMLSQLUtil$ in a subsequent macro action, you must invoke methods from the Host On-Demand Macro Utility library (HML library) associated with $HMLSQLUtil$. See $HMLSQLUtil$.
Using the SQLQuery action with bidirectional languages
For bidirectional languages (Arabic and Hebrew), some specific properties must be set for SQLQuery to work correctly. An Advanced button appears in the Advanced Macro editor to access the options. The Advanced button is visible only if your workstation is configured for a bidirectional language.
The additional properties are:
- Host-File Type
- Specifies whether the host file should be saved in logical or visual format. The default is Visual.
- Local-File Type
- Specifies whether local files are in logical or visual format. The default is Logical.
- Host-File Orientation
- Specifies whether the host file should be saved in left-to-right or right-to-left format. The default is Left-to-Right.
- Lam-Alef Expansion
- Specifies the behavior of the Lam-Alef characters. When receiving Arabic data from the host through the SQL wizard statement, the character Lam-Alef is expanded into two characters, if there is space after the Lam-Alef character: Lam followed by Alef.
- Lam-Alef Compression
- Specifies the behavior of the Lam-Alef characters. When sending Arabic data to the host through the SQL wizard statement, the characters Lam followed by Alef are compressed into one character and space is added after the Lam-Alef character. This option is enabled for Arabic systems only. The default is on.
- Numerals Shape
- Specifies the shape of the numeral on the host file at the SQL wizard statement; the numeral shape could be NOMINAL, NATIONAL or CONTEXTUAL. This option is enabled for Arabic systems only. The default is NOMINAL.
- Round Trip
- Specifies the behavior of numerals, disabling the reversal of the numerals if preceded by Arabic/Hebrew characters. The default is on.
- Symmetric Swapping
- Specifies the behavior of the symmetric characters, such as brackets; the inversion of the screen causes directional characters to be replaced by their counterparts. The default is on.
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. In addition, HATS adds macro traces to the HATS runtime trace.
Use the Trace Handler listbox to specify the trace destination to which you want the trace message sent:
- Select trace facility to send the trace message to the trace facility.
- Select User trace event to send the trace message to a user trace handler.
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:
- The example consists of one entire macro script named TRACE.
- The <create> element creates a string variable named $strData$ and initializes it to an original value of 'Original value'.
- The first action is a Trace action with the Trace Text set to 'The value is' + $strData$.
- The second action is a Variable update action that sets the variable $strData$ to a new value of 'Updated value'.
- The third action is another Trace action identical with the first Trace action.
<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:
- The name of a variable
- The value that you want to store into the variable.
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:
| 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:
- The entity in the Value field can be an expression, and
- Expressions are not evaluated until the action is performed.
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 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:
- The name of the field variable, such as $fldTmp$.
- A location string, such as '5,11'. (A location string is a string containing two integers separated by a comma that represent a row and column location on the host terminal.)
When the macro runtime performs the Variable update action, the macro runtime:
- Recognizes that the variable is a field variable.
- Looks at the location string that is to be used to update the field variable.
- Finds in the current host terminal the row and column location specified by the location string.
- Finds in the current host terminal the 3270 or 5250 field in which the row and column location occurs.
- Reads the entire contents of the 3270 or 5250 field, including any leading and trailing blanks.
- 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:
- It begins at row 5, column 8.
- It ends at row 5, column 32.
- It contains the string 'Print VTOC information'.
You set up a Variable update action with the following values:
- In the Name field of the Variable update window you type the name of a field variable that you have just created, $fldData$.
- In the Value field you type a location string, '5,11'. Notice that you have to specify only one row and column location, and that it can be any row and column location that lies within the field.
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:
- The first location specifies the first position in the field to read from.
- The second location specifies the last position in the field to read from.
As an example, suppose that the host terminal contains a 3270 or 5250 field with the following characteristics:
- It begins at row 5, column 8.
- It ends at row 5, column 32.
- It contains the string 'Print VTOC information'.
and suppose that you set up a Variable update action with the following values:
- In the Name field of the Variable update window you type the name of a field variable that you have just created, $fldData$.
- In the Value field you type a location string, '5,14:5,17'. Here you are specifying both a beginning location and an ending location within the field.
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.