In HATS, there are two main types of variables: global variables and macro variables. The differences between them are outlined here.
Global variables are variables created in HATS Toolkit and used by HATS projects. Global variables are stored outside of the macro script. They are maintained and updated by HATS runtime. There are two types of global variables:
Whether a global variable is considered local or shared depends on whether the shared check box in the GUI is checked when the global variable is created, or whether the value of the shared attribute of a set, prompt, or extract tag is specified as yes or no in the HATS .hma source file.
Unlike global variables, macro variables are used and stored within macros in the HATS .hma source file. The macro editors can be used to create macro variables. To create macro variables using the VME, see Variables and Types tab, and using the AME, see Variables tab. The macro variables are created, stored, and used by the macro engine, and listed in the macro script.
In a HATS macro (.hma) file source using HATS prompts and extracts for global variables, the prompts and extracts appear in the file before the macro script syntax. The macro script, which contains the macro variables, is enclosed by the begin <HAScript> and the end </HAScript> tags.
Macro variables help you to add programming intelligence to macros. With a variable you can store a value, save a result, keep a count, save a text string, remember an outcome, or do any number of other programming essentials.
You can create a variable that belongs to any of the standard data types (string, integer, double, boolean, and field).
You can also create a variable that belongs to an imported type representing a Java™ class. You can then create an instance of the class and call a method on the instance. This capability opens the door to the abundant variety of functionality available through Java class libraries, including libraries in the Java Runtime Environment (JRE) libraries, classes or libraries that you implement yourself, or Java classes and libraries from other sources.
Using variables requires that you use the advanced macro format for your macro (see Basic and advanced macro format). Therefore, if you want to add variables to a macro that is in the basic macro format, you must decide whether to convert the macro to the advanced macro format. If you have an old macro in the basic macro format that many users rely on and that works perfectly, you might want to leave the macro as it is.
However, remember that all recorded macros are recorded in the basic macro format. So, if you have recently recorded a macro and are beginning to develop it further, then you might simply not have gotten around to switching to the advanced macro format.
The macro editors address both these situations by popping up a window with the following message when you start to define a variable in a macro that is still in the basic macro format:
You are attempting to use an advanced macro feature. If you choose to continue,
your macro will automatically be converted to advanced macro format. Would you
like to continue?Click Yes if you are building a macro in which you plan to use variables, or No if you have a macro in the basic macro format that you do not want to convert.
The scope of every variable is global with respect to the macro in which the variable is created. That is, every variable in a macro is accessible from any macro screen in the macro. All that an action or a descriptor in a macro screen has to do to access the variable is just to use the variable name.
For example, suppose that you have a variable named $intPartsComplete$ that you initialize to 0. You might use the variable in the following ways as the macro proceeds:
In this example, actions in several different macro screens were able to read from or write to the variable $intPartsComplete$.
In the Source view, you create a variable using a <create> element. There is a containing element called <vars> that contains all the variables in the macro script, and there is a <create> element for each variable. Figure 24 shows a <vars> element that contains five <create> elements:
<vars>
<create name="$strAccountName$" type="string" value="" />
<create name="$intAmount$" type="integer" value="0" />
<create name="$dblDistance$" type="double" value="0.0" />
<create name="$boolSignedUp$" type="boolean" value="false" />
<create name="$fldFunction$" type="field" />
</vars>In Figure 24, the <vars> element creates one variable from each of the standard data types (string, integer, double, boolean, and field).
You must put all variable creations (<create> elements) inside the <vars> element. The <vars> element itself must appear after the <import> element, if any (see the next section), and before the first macro screen (<screen> element).
In the Source view, you create an imported type using a <type> element. There is a containing element called <import> that contains all the imported types in the macro script, and there is a <type> element for each imported type. Figure 25 shows an <import> element that declares an imported type, followed by a <vars> element that creates and initializes a variable belonging to the imported type:
<import>
<type class="java.util.Hashtable" name="Hashtable" />
</import>
<vars>
<create name=$ht$ type="Hashtable" value="$new Hashtable(40)$" />
</vars>In the figure above the <import> element contains one <type> element, which has a class attribute (containing the fully qualified class name, java.util.Hashtable) and a name attribute (containing the short name, Hashtable). The <vars> element contains one <create> element, which as usual specifies a name ($ht$), a type (Hashtable), and an initial value (which here is not null but rather is a call to a constructor that returns an instance of the class, $new Hashtable(40)$).
If you are using the source view, you must put all imported types (<type> elements) inside the <import> element. The <import> element itself must appear inside the <HAScript> element (see <HAScript> element) and before the <vars> element.
During macro playback, when the macro runtime processes a call to a Java method, the macro runtime searches all the available Java library files and class files for the class to which the method belongs. The search does not stop until it finds the class.
Deploying a Java library or class consists of placing the library file or class file containing the class in a location where the macro runtime can find it during macro playback. The following Java classes are automatically available for use and do not need to be deployed by you:
All other Java classes containing methods invoked by a macro script must be deployed by you to a location where the macro runtime can find them. Depending on the environment, you can deploy the Java classes as class files or as libraries containing Java classes.
When using Java classes in a WebSphere® Application Server runtime environment (not portal), be aware that the macro runtime is packaged in a Java EE Enterprise Application (.ear) file. If the Java classes are packaged in a HATS Web project, you must update the Web archive (WAR) class loader policy to Single class loader for application to ensure that the macro runtime can access them when the macro runs. If this configuration is not done, ClassNotFoundExceptions will occur when the macro invokes the Java classes. To learn how to configure the class loader policy, see Configuring application class loaders in the documentation for the version of WebSphere Application Server that you are using .
The rules for variable names are as follows:
The rules for type names are as follows:
The PlayMacro action, in which one macro "chains to" another macro (a call without return), allows you to transfer all the variables and their values belonging to the calling macro to the target macro. The target macro has access both to its own variables and to the transferred variables (see PlayMacro action (<playmacro> element)).
A field variable is a type of string variable. It holds a string, just as a string variable does, and you can use it 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 reads from a 3270 or 5250 field in the current host terminal. To get the macro runtime to read this string from the 3270 or 5250 field, you have to create a Variable update action that specifies:
When the macro runtime performs the Variable update action it takes the following steps:
For more information, see Variable update action with a field variable.
The macro runtime assigns initial values to variables at the start of the macro playback, before processing any macro screen. The sections that follow describe the usage of those initial values for both standard and imported variable types.
A variable that belongs to a standard type (string, integer, double, boolean) can be used in much the same way as an immediate value of the same type (such as 'Elm Street', 10, 4.6e-2, true):
However, you cannot use a variable in certain contexts. In the AME, you cannot use a variable in the following contexts:
In the source view, you cannot use a variable in the following contexts:
You can write a value into a variable belonging to a standard type in the following ways:
You cannot assign one of the following values to a variable of standard type:
If you write a Java object into a variable of standard type, then the macro runtime calls the toString() method of the imported type and then attempts to assign the resulting string to the variable.
You can use the value contained in a variable belonging to an imported type in the following ways:
You cannot assign the following types of data to a variable of imported type:
If your macro attempts to assign one of these invalid types of values to a variable of imported type, then the Macro runtime generates a runtime error and halts the macro.
You can write a value into a variable of imported type in the following ways:
You can assign the following types of values to a variable belonging to an imported type:
<create name=$ht$ type="Hashtable" value="" />In any conditional expression (for example, in the Condition field of a conditional action) in which you are comparing two variables of the same imported type, you should implement a comparison method (such as equals()) in the underlying class rather than using the variables themselves. For example,
$htUserData.equals($htPortData$)$If instead, you compare the variables themselves (for example $htUserData$ == $htPortData$), then:
This will probably not yield the outcome that you expect from comparing the two variables.
You can call a method in any context in which the value returned by the method is valid. For example, in an Input action you can set the Row value to the integer value returned by a method, such as:
$importedVar.calculateRow()$Also, you can use the Perform action to call a method when you do not need the return variable of the method or when the method has no return value (void) (see Perform action (<perform> element)).
To call a method belonging to an imported class, use the same syntax that you would use in Java. However, in addition, you must also enclose a method call in dollar signs ($), just as you would a variable. Examples:
$new FileInputStream('filename')$
$fis.read()$ An immediate string value (such as 'Elm Street', or 'myFileName' in the first example above) passed as a parameter to a method must be enclosed in single quotes, as usual (see Advanced macro format rules).
When you add a method call (such as $prp.get('Group Name')$) to a macro script, the macro editor does not verify that a called method or constructor exists in the class to which the variable belongs. That check is done by the macro runtime when the call occurs.
The method must be a public method of the underlying Java class.
When the macro runtime searches in the Java class for a method to match the method that you have called, the macro runtime maps macro data types (boolean, integer, string, field, double, imported type) to Java data types as shown in Table 12:
| If the method parameter belongs to this macro data type: | Then the macro runtime looks for a Java method with a parameter of this Java data type: |
|---|---|
| boolean | boolean |
| integer | int |
| string | String |
| field | String |
| double | double |
| imported type | underlying class of the imported type |
The macro runtime searches for a called method as follows:
The Host On-Demand Macro Utility Libraries (HML libraries) are utility libraries that are packaged with the HATS code. You can invoke a method from one of these libraries without:
In fact, you are not allowed to import a class contained in an HML Java library, or to create a variable belonging to an HML class, or to create an instance of an HML object.
The reason is that the macro runtime, during the initializing that goes on when macro playback is started:
The following table shows for each HML variable the variable name and the types of methods in the underlying class.
| HML variable: | Description of methods: |
|---|---|
| $HMLFormatUtil$ | Methods for formatting strings. |
| $HMLPSUtil$ | Methods that access the presentation space of the session window. |
| $HMLSessionUtil$ | Methods that return session values. |
| $HMLSQLUtil$ | Methods that return information about the results of the most recent SQLQuery action. |
To invoke a method belonging to an HML library, specify the variable name, method name, and input parameters in the usual way:
$HMLFormatUtil.numberToString(1.44)$
$HMLPSUtil.getCursorPos()$
$HMLSessionUtil.getHost()$To prevent confusion between normal variables and HML variables, variable names beginning with HML are reserved. If you try to create a variable beginning with HML, Host On-Demand generates an error message.
The methods invoked with $HMLFormatUtil$ are formatting methods. Table 14 summarizes these methods:
| METHOD SUMMARY: $HMLFormatUtil$ | |
|---|---|
| String |
|
| int or double |
|
A locale is a set of formatting conventions associated with a particular national language and geographic area. For example, depending on the locale with which a client workstation is configured, a decimal value such as 1111.22 can be represented with any of the following strings:
'1111.22'
'1,111.22'
'1111,22'As another example, a negative number such as -78 can be represented as:
'-78'
'78-'The methods numberToString() and stringToNumber() perform conversions between a number (that is, a variable or immediate value of type integer or type double, such as 1111.22) and its representation in the current locale (a string, such as '1111.22', '1,111.22', or '1111,22').
public String numberToString(Object obj)This method converts a number (integer or double) to a string formatted according to the currently configured locale. The input parameter can be of type integer or of type double.
This method replaces the standalone method $FormatNumberToString()$, which is deprecated.
<input value="$HMLFormatUtil.numberToString(1111.44)$"
row="20" col="16" movecursor="true"
xlatehostkeys="true" encrypted="false" />public int stringToNumber(String str)
public double stringToNumber(String str)This method converts a numeric string formatted according to the currently configured locale to a number. The number returned is either of type integer or of type double, depending on the input string.
This method replaces the standalone method $FormatStringToNumber()$, which is deprecated.
<value="’1111.33’" />
<extract name="'Extract'" planetype="TEXT_PLANE"
srow="1" scol="1"
erow="1" ecol="10" unwrap="false"
assigntovar="$value$" />
<if condition="$HMLFormatUtil.stringToNumber($value$)$ < 0 "
...
</if>The methods invoked with $HMLPSUtil$ affect the presentation space of the session window or return information about the presentation space of the session window. Table 15 summarizes these methods:
| METHOD SUMMARY: $HMLPSUtil$ | |
|---|---|
| int |
|
| int |
|
| void |
|
| int |
|
| int |
|
| int |
|
| int |
|
| int |
|
| int |
|
| String |
|
| int |
|
The presentation space is a data structure that contains an element for each row and column position in the session window (but not including the last row of the session window, which is used for the Operator Information Area). The size of the presentation space depends on the size of the session window. For example, if the session window has 24 rows and 80 columns, then the size of the presentation space is 24 * 80 = 1920.
The position of the elements in the presentation space corresponds serially to the row and column positions in the session window, reading from left to right, top to bottom. For example, if the session window has 80 rows and 25 columns, then row and column positions are as shown in Figure 29:
Row of Column of Corresponds to
Session Session element at this
Window: Window: position in PS:
1 1 1
1 2 2
1 3 3
...
1 80 80
2 1 81
2 2 82
2 3 83
...
24 79 1919
24 80 1920Host On-Demand uses the presentation space to store the characters that are to be displayed in the session window. Each element in the presentation space is used to store one character (and information about that character, such as intensity). For example, if the string Message appears at row 1 and column 1 of the session window, then rows and columns correspond to the positions shown in Figure 30:
Row of Column of Corresponds Character
Session Session to element stored in
Window: Window: at this pos- this element:
ition in PS:
1 1 1 M
1 2 2 e
1 3 3 s
1 4 4 s
1 5 5 a
1 6 6 g
1 7 7 eAlthough you normally will not need to use them, Table 16 shows the formulas for calculating various values. The meanings of the symbols used in these formulas are as follows:
| Value: | Formula for calculating: |
|---|---|
| Size of the PS |
|
| row |
|
| col |
|
| pos |
|
public int convertPosToCol(int pos)This method returns the column number associated with the specified position in the presentation space.
<varupdate name="$cursor_col$ value="$HMLPSUtil.convertPosToCol($HMLPSUtil.getCursorPos()$) $" />public int convertPosToRow(int pos)This method returns the row number associated with the specified position in the presentation space.
<varupdate name="$cursor_row$" value=$HMLPSUtil.convertPosToRow($HMLPSUtil.getCursorPos()$)$" />public void enableRoundTrip(boolean flag)This method is for bidirectional languages only (Arabic and Hebrew). Assume that A, B, and C are bidirectional characters. Normally, when a string contains a series of bidirectional characters followed by a series of numerals (for example, ABC 123), and the entire string is stored, the Host On-Demand client exchanges the positions of the bidirectional characters and the numerals. For example, normally, if you read the string ABC 123 from the presentation space and store the string into a variable, and then subsequently write the value of the variable back into the presentation space, the Host On-Demand client writes 123 ABC back into the presentation space.
To turn off this technique of forced reversal, call enableRoundTrip() with a value of true. To restore this technique of forced reversal, call enableRoundTrip() with a value of false.
<perform value="$HMLPSUtil.enableRoundTrip(true)$" />public int getCursorCol()This method returns the column location of the text cursor in the presentation space.
<input value="$HMLSessionUtil.getHost()$"
row="$HMLPSUtil.getCursorRow()$"
col="$HMLPSUtil.getCursorCol()$+2"
movecursor="true" xlatehostkeys="true"
encrypted="false" />public int getCursorPos()This method returns the position of the text cursor in the presentation space.
<varupdate name="$cursor_pos$" value="$HMLPSUtil.getCursorPos()$" />
public int getCursorRow()This method returns the row location of the text cursor in the presentation space.
<input value="$HMLSessionUtil.getHost()$"
row="$HMLPSUtil.getCursorRow()$"
col="$HMLPSUtil.getCursorCol()$+2"
movecursor="true" xlatehostkeys="true"
encrypted="false" />public int getSize()This method returns the size of the presentation space, that is, the number of character positions in the presentation space. For example, if the session window has 25 rows and 80 columns, then the size of the presentation space is 24 * 80 = 1920.
<varupdate name="$size$" value="HMLPSUtil.getSize()$" />public int getSizeCols()This method returns the number of columns in the presentation space. The presentation space has the same number of columns as the session window. For example, if the session window has 25 rows and 80 columns, then the number of columns in the presentation space is 80.
<varupdate name="$size_cols$" value="$HMLPSUtil.getSizeCols()$" />public int getSizeRows()This method returns the number of rows in the presentation space. The presentation space has one row less than the session window (because the last line of the session window, which contains the Operator Information Area, is not included in the presentation space). For example, if the session window has 25 rows and 80 columns, then the number of rows in the presentation space is 24.
<varupdate name="$size_rows$" value="$HMLPSUtil.getSizeRows()$" />public String getString(int pos, int len)This method returns the text string beginning at the specified position in the presentation space and continuing for the specified number of characters.
<varupdate name="$text_of_row_18$"
value="$HMLPSUtil.getString(
$HMLPSUtil.getSizeCols()$*17+1,
$HMLPSUtil.getSizeCols()$)$" />public int searchString(String str)This method returns the position in the presentation space of the specified string. This method returns 0 if the string is not found in the presentation space.
<varupdate name="$pos_ofIBM$" value="$HMLPSUtil.searchString('IBM')$" />The methods invoked with $HMLSessionUtil$ return values associated with the session. Table 17 summarizes these methods:
| METHOD SUMMARY: $HMLSessionUtil$ | |
|---|---|
| String |
|
| String |
|
| String |
|
public String getHost()This method returns the host name or the host address that you typed into the Destination Address field of the Connection section of the session configuration (such as myhost.myloc.mycompany.com or 9.27.63.45).
<varupdate name="$host$" value="$HMLSessionUtil.getHost()$" />public String getLabel()This method returns the session name that you typed into the Session Name field of the Connection section of the session configuration (a name such as 3270 Display or 5250 Display).
<varupdate name="$label$" value="$HMLSessionUtil.getLabel()$" />public String getName()This method returns the identifying name that the host assigns to the session (such as A , B, or C). When you start a session, the host assigns a name to the session to distinguish it from other instances of the same session that might be started.
<varupdate name="$name$" value="$HMLSessionUtil.getName()$" />The methods invoked on $HMLSQLUtil$ return information about the results of the most recent SQLQuery action. Table 18 summarizes these methods:
| METHOD SUMMARY: $HMLSQLUtil$ | |
|---|---|
| int |
|
| String |
|
| String |
|
| int |
|
The results of the SQLQuery action are stored as a two-dimensional array that is one column wider and one row taller than the size of the block of data returned. Row 0 is used to store the names of the columns (the field names from the database), and Column 0 is used to store a zero-based index (see Table 19 below). The entry at Row 0, Column 0 contains an empty string. The remainder of the array contains the actual data. All values are strings.
Table 19 shows as an example the results of a query, a 3 x 5 block of data, stored in a 4 x 6 array:
| (empty string) | TOPICID | EXMPLID | DESCRIPT |
| 0 | 4 | 18 | Create a toolbar with custom buttons. |
| 1 | 9 | 54 | Attach tables at startup. |
| 2 | 11 | 74 | Edit Products. |
| 3 | 11 | 75 | Enter or Edit Products |
| 4 | 11 | 76 | Find Customers |
In the table above, the entry at Row 0, Column 0 contains an empty string. The remainder of Row 0 contains the field names from the database (TOPICID, EXMPLID, DESCRIPT). The remainder of Column 0 contains index numbers for the rows (0, 1, 2, 3, 4). The actual data is contained in the remainder of the array. All values are strings.
public int getColumnSize()This method returns the actual number of columns of data in the array, including the added Column 0. For example, for the array in Table 19 this method returns 4.
<varupdate name="$col_size$" value="$HMLSessionUtil.getColumnSize()$" />public int getDataByIndex(int row, int column)This method returns the entry at the specified row and column index. The following list shows the values returned for the data shown in Table 19:
<varupdate name="$data$" value="$HMLSessionUtil.getDataByIndex(3,3)$" />public int getDataByName(int row, String fieldName)This method returns the entry at the specified row and field name. The following list shows the values returned for the data shown in Table 19:
<varupdate name="$data$" value="$HMLSessionUtil.getDataByName(3,'DESCRIPT')$" />public int getRowSize()This method returns the actual number of rows of data in the array, including the added Row 0. For example, for the array in Table 19 this method returns 6.
<varupdate name="$row_size$" value="$HMLSessionUtil.getRowSize()$" />$FormatNumberToString()$ is deprecated in favor of $HMLFormatUtil.numberToString()$. The former has the same input parameters and return type as the latter (see numberToString()).
$FormatStringToNumber()$ is deprecated in favor of $HMLFormatUtil.stringToNumber()$. The former has the same input parameters and return type as the latter (see stringToNumber()).