The Visual Macro Editor (VME) gives you the ability to visually develop HATS macros. The VME combines many of the features of the HATS host terminal, basic Macro Editor, and Advanced Macro Editor, and allows for offline development of macros. It also allows flows to be copied between macros and provides drag-and-drop support for adding new screens.
The VME is the default editor for HATS macros.
The Macro Editor can still be opened by right-clicking on the macro and selecting Open With -> Macro Editor. The Advanced Macro Editor can still be opened from the Macro Editor Overview page. Prompts and Extracts can also still be edited from the Macro Editor.
In addition to using the host terminal, you can use the VME to create a new macro using the New Macro wizard.
In the HATS perspective, use any of the following procedures to start the New Macro wizard:
The wizard includes one panel where you can:
The VME is the default editor for HATS macros. When you double-click on a macro object (.hma file), the VME opens.
The VME is composed of the following parts:
The design tab, or canvas, is the primary work area in the VME. It shows the macro objects graphically (macro screens, actions, and next screen connections) and allows you to make modifications to each object as well as change global macro properties.
For each object, different actions are enabled using the object's pop-up menu (right-click on the object). All actions can be undone by selecting Undo from the pop-up menu or from the Edit menu on the menu bar. All actions can be redone by selecting Redo from the pop-up menu or from the Edit menu. Once the macro is saved, changes cannot be undone. Once a change is made in the Source tab, previous actions made in the Design tab cannot be undone. Changes made on the Design tab are reflected in the Source tab and vice versa.
The following actions are enabled on the macro's pop-up menu (right-click on the white macro canvas):
The following actions can be performed on a screen's pop-up menu (right-click a macro screen object):
The following actions can be performed on a screen action's pop-up menu (right-click a screen action):
The following actions can be performed on a next screen connection's pop-up menu (right-click a next screen connection object):
The Palette allows you to:
The integrated terminal toolbar allows for the following actions:
The Source tab enables you to modify the macro XML source. It is required for advanced editing, such as adding custom screen recognition criteria.
The VME uses the Host On-Demand <comment> tag to keep information like location of the macro screen on the canvas and the associated screen capture.
The <comment> tag can also be used by developers to add a comment to a screen. Another way to add a comment is to use the format : <!- this is a comment->. To avoid losing a developer's pre-existing comments, the VME converts text found in the <comment> tag that it does not recognize, for example, that does not contain any of the keywords like visualinfo, into a comment for the screen using the <!- -> format.
If there are syntax errors in the macro, then error markers appear when the macro is saved. Markers appear in the source and in the Problems view. Source errors prevent the macro canvas from showing, and an error message is displayed instead. If this occurs, switch to the Source tab and correct the errors.
All macro-level settings are contained in the macro properties panel. To edit the macro-level properties, double-click on the macro canvas or right-click and select Properties.
The Properties panel includes a General tab and a Variables and Types tab.
The General tab allows you to view and modify the following macro properties:
The Variables and Types tab allows you to define macro variables and user-defined (imported) types.
The Enable support for variables and arithmetic expressions check box is cleared by default, can only be selected once, and is disabled afterwards. When the check box is selected, the macro is converted into the advanced macro format. Because this operation cannot be undone, a warning message is issued.
After the warning message is cleared by clicking Yes, the Variables and User-Defined Types tables are enabled and you can Add, Edit, and Remove items from the tables.
The VME does not require you to include the variable name between dollar signs ($). The editor adds the dollar signs ($) to the beginning and the end of the variable name in the macro source and removes them to display the variable name.
For more information, see Data types, operators, and expressions and Variables and imported Java classes.
The Play Macro button of the integrated terminal allows you to test the macro. As the macro is played in the terminal, the path is highlighted in the canvas. The macro is always started from the beginning regardless of the screen currently selected on the canvas.
To edit the properties of a macro screen, double-click on the object in the macro canvas or right-click and select Properties.
The Screen Properties panel includes a General tab, a Screen Recognition Tab, and an Actions Tab.
The General tab allows you to modify the following properties:
You can use the Browse button to select a new screen capture and the Clear button to remove the association to a screen capture. For more information, see Associating a macro screen with a screen capture.
The Screen Recognition tab is only enabled if a screen capture is associated with the macro screen. For more information about screen description in the macro facility, see Screen description.
The Actions tab allows you to configure the actions to perform when the screen is recognized.
You can Add, Edit, Remove, and change the order of the actions using the Up and Down buttons. For more information, see Adding and editing actions.
A new screen can be added to the canvas by dragging a screen capture from any project.
When dragging from a project different than the one that contains the macro, you are prompted to select whether to import the screen capture file into the target project. If you click Yes, then the file is copied into the project's main Screen Capture folder, not the macro specific folder, and associated with the new macro screen on the canvas. If you click No, then the file is not imported, and no screen capture is associated with the new macro screen on the canvas.
If the default recognition criteria is defined, see Default screen recognition criteria, it is applied to the new screen's recognition criteria and adjusted to the selected screen capture.
You can double-click on the new screen to fully configure it and use the Next Screen Connection tool on the palette to wire it with the other screens in the macro.
The Add Screen button of the integrated terminal allows you add the terminal's current screen to the macro and configure it appropriately.
The Add Screen wizard allows you to:
The Screen tool of the palette allows you to add a new screen to the macro.
To add a screen, click Screen in the palette, then click on the canvas. This action will start the Add Screen wizard as described in Adding a screen from the integrated terminal. The wizard forces you to select a screen capture using the Screen Capture panel described in Associating a macro screen with a screen capture before proceeding to allow you to configure the screen.
The Browse button on the General tab of the Screen Properties panel, see Editing macro screen properties, is used to select a screen capture from the project to associate with the macro screen. The Screen Capture panel displays a preview of all the screen captures in the project, inside or outside the screen capture macro folder.
The Screen Capture panel is also displayed when the user adds a screen from the Palette.
Hovering the mouse over a screen on the canvas shows a preview of the screen capture associated with it, if any.
When the Add Screen wizard is used to add a screen to the macro, using the palette or the integrated terminal, you have the option to save the screen recognition criteria as the default recognition criteria for all screens added to the macro using the palette, the integrated terminal, or by dragging a screen capture. To specify this option, select the Remember criteria for next time check box on the Screen Recognition Criteria panel.
This feature is useful when many screens share the same recognition criteria. For example, if all your screens have a five character name or code at the upper left corner that uniquely identifies the screen, you can configure default recognition criteria so that every new screen recorded or added to the macro uses string recognition at that area of the screen. This saves time by not requiring you to configure recognition criteria on every screen.
There is only one default recognition criteria saved for the whole project, and it applies to all macros in the project.
The default recognition criteria is overridden by the last screen recognition criteria defined with the Remember criteria for next time check box selected.
When a default recognition criteria is defined, it is applied every time the Add Screen wizard is started and is also adjusted to the screen capture associated with the new screen.
One or more screens can be cut, or copied, and pasted in the same macro or another macro. The operation can be undone.
When one or more screens are selected and either Cut or Delete is executed, then all of the selected screens and incoming and outgoing next screen connections are removed from the macro canvas. This operation could force a reordering of the next screen connections originating from screens not removed. In the example below, the CelDialCommunications screen has next screen connections from the DisplayProgramMessages screen and to the MainMenu screen. It is also the second in order of next screen connections from the SignOn screen.
After cutting or deleting the CelDialCommunications screen, all of the next screen connections from and to it are removed, and the MainMenu screen becomes the second (instead of the third) in order of next screen connections from the SignOn screen.
When Paste is executed, after a Copy or a Cut, then the internal next screen connections (next screen connections to other selected screens) are retained during the operation. In the example below the SignOn, DisplayProgramMessages, and MainMenu screens are selected to copy.
After pasting the copied screens back onto the same macro canvas, notice that all of the next screen connections among the three selected screens are also copied. Only the next screen connection from the MainMenu screen to the CelDialCommunications screen is not copied.
Some considerations must be made when pasting one or more screens from or to a macro in advanced macro format.
Actions can be added to macro screens from the Actions tab of the macro screen properties, see Editing macro screen properties. The Add Action wizard shows the list of actions that can be added and edited for a macro screen.
The Actions tool of the palette allows you to add a new action to a macro screen.
To add an action, click the action in the palette, then click on the macro screen to add the action.
A panel, applicable to the selected action type, appears so you can edit the properties of the action.
Screen actions can be hidden or shown by clicking the toggle on the upper right corner of the screen figure.
If a screen has more actions than are permitted to be displayed, see Working with VME preferences, a line that reads nnn more actions is shown.
The following sections describe all the actions that can be added or edited using the VME. For more information about macro actions and more details about each action, see Macro actions.
A Custom action allows you to invoke a Java™ program as a macro action and optionally pass arguments to the program.
The fields you can specify are:
For more information see <custom> element.
The Evaluate (If) action provides the functions of an if-statement or of an if-else statement.
You can Add, Edit, Remove, move Up, or move Down, actions to perform for each case.
Even if many actions are defined for the If True and If False conditions, only the Evaluate condition is listed as an action on the screen object on the macro canvas.
For more information see Conditional action (<if> element and <else> element).
The Extract action captures data from the host terminal and optionally stores the data into a variable. This action is very useful and is the primary method that the Macro object provides for reading application data (instead of using programming APIs from the toolkit).
If an extract already exists with the same name, a warning message displays to notify you that proceeding will override the settings for the existing extract.
Use the Region section to specify the region of the host screen to extract.
Use the Extraction Format section to specify the format of the extracted data. Data extracted from the text plane is returned by storing a single string or lists of strings based on the extraction format chosen. Data extracted from the other (non-text) planes is returned in the form of a character array based on the extraction format chosen.
When extracting from the other (non-text) planes, specifies that the extracted data should be saved in a global variable as a single object in the form of a 2-dimensional character array. This option is supported only for global variables.
When extracting from the other (non-text) planes, specifies that the data extracted as a 2-dimensional character array should be broken up into individual 1-dimensional arrays, each one representing a single row that was extracted, and each row stored in an index in the global variable. This option is supported only for global variables.
Click Define to define the table.
Use this field to change the heading of the selected column.
Expanding a column moves characters between columns. When you highlight a column, the Left button moves the last character on each line of the column to the left of the highlighted column to become the first character on each line in the highlighted column. The Right button moves the first character from each line of the column to the right of the highlighted column to become the last character on each line in the highlighted column.
Reducing a column moves characters between columns. When you highlight a column, the Left button moves the first character from each line of the highlighted column to become the last character on each line in the column to the left of the highlighted column. The Right button moves the last character from each line of the highlighted column to become the first character on each line in the column to the right of the highlighted column.
Use this button to merge two highlighted columns into a single column. The characters in the highlighted columns are joined into one column.
Use this button to divide a highlighted column into two separate columns. The characters in the highlighted column are divided equally between the two new columns. If there are an uneven number of characters, the left column will contain one more character than the right column.
When you click Divide, HATS divides the selected column. If the column contains double-byte (DBCS) characters, the division can split a character between the two columns. In this case, the character will not appear in either column. If you see this happen while editing an extract action, use the Right and Left buttons to adjust the columns. The divided character will reappear when it is contained in a single column.
Use the Handler section to specify how text extracted from the text plane is processed.
For HATS rich client projects, you can specify a custom macro handler, or browse to select from the list of custom macro handlers defined in the rich client project, to prompt the user for the necessary information, and include a button for the user to submit the information. A default macro handler is shipped with HATS, and it is named DefaultMacroHandler. You can find this file in the HATS Projects view, expanding the project name, and expanding Rich Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime by calling the createButtonArea() and createButtons() methods in the render() method of your custom macro handler. These methods are called in the default implementation of the RcpMacroHandler.render() method. For more information about RcpMacroHandler, see the HATS RCP API Reference section in the HATS Information Center at http://publib.boulder.ibm.com/infocenter/hatshelp/v75/index.jsp?topic=/com.ibm.hats.doc/doc/rcpjavadoc/index.html.
If you select to save the extract data as a global variable, the Text option of the Planes to extract setting is automatically selected.
Integration Objects do not directly extract to global variables. Instead, the output page for the Integration Object retrieves the data from the Integration Object after it has run, and then sets the global variables. Remember only shared global variables can be accessed by Integration Objects.
If you select to save the extract data as a macro variable, the Text option of the Planes to extract setting is automatically selected. Only data from the text plane can be saved to a macro variable.
Use the Advanced section to set the following options:
Data from any plane can be extracted and saved as a global variable. Only data from one plane can be extracted per Extract action. Only data from the text plane can be saved to a macro variable or used in an Integration Object.
For more information see Extract action (<extract> element).
The Extract All action enables you to add multiple Extract actions, for all fields on the screen, at one time.
You can easily exclude single fields, all empty protected fields, or all input fields, and set names for the extracts.
If an extract already exists with the same name, a warning message displays to notify you that proceeding will override the settings for the existing extract.
If you select the Save as global variable option, you can also select whether to Synchronize extract names and global variables names. If you do, then the names are kept in sync. Otherwise, you can edit the global variable name to make it different than the name of the extract.
For information about the other VME settings for this action, see Extract action. For more general information see Extract action (<extract> element).
The Input action simulates keyboard input from an actual user. The action sends a sequence of keystrokes to the host terminal. The sequence can include keys that display a character (such as a, b, c, #, &, and so on) and also action keys (such as [enter] and others).
For more information see Input action (<input> 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:
Specifies the number of milliseconds to wait. The default is 10000 milliseconds (10 seconds).
For more information, see <pause> element.
The Perform action allows you to specify a Java method to run. This action can only be added for macros in advanced macro format.
The action invokes a method belonging to a Java class that you have imported as a user-defined type (see Variables and Types tab).
For more information see Perform action (<perform> element).
The Play macro action runs another macro.
For more information, see PlayMacro action (<playmacro> element).
The Prompt action provides a powerful way to send immediate user keyboard input into the 3270 or 5250 application or into a variable.
If a prompt already exists with the same name, a warning message displays to notify you that proceeding will override the settings for the existing prompt.
The Handler section enables you to determine how the prompt is processed. You can select one of the following radio buttons:
For HATS rich client projects, you can specify a custom macro handler, or browse to select from the list of custom macro handlers defined in the rich client project, to prompt the user for the necessary information, and include a button for the user to submit the information. A default macro handler, named DefaultMacroHandler, is shipped with HATS. You can find this file in the HATS Projects view, expanding the project name, and expanding Rich Client Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime by calling the createButtonArea() and createButtons() methods in the render() method of your custom macro handler. These methods are called in the default implementation of the RcpMacroHandler.render() method. For more information about RcpMacroHandler, see the HATS RCP API Reference section in the HATS Information Center at http://publib.boulder.ibm.com/infocenter/hatshelp/v75/index.jsp?topic=/com.ibm.hats.doc/doc/rcpjavadoc/index.html.
If a prompt value is based on a global variable set by an extract, and the promptall attribute is set to true, the extract action is not run before the prompts values are retrieved. Because of this, the global variable used by the prompt does not contain a value. If you use global variables with extracts and prompts, you should set the promptall attribute to false. For further information regarding the promptall attribute, see The promptall attributes.
Integration Objects do not access global variables directly. Instead, the input and output pages for the Integration Object retrieve the global variable value, and set it into the Integration Object before it is run. Only shared global variables can be accessed by Integration Objects.
For more information see Prompt action (<prompt> element).
The Prompt All action enables you to add multiple Prompt actions, for all fields on the screen, at one time.
You can easily exclude fields and set names for the prompts.
If a prompt already exists with the same name, a warning message displays to notify you that proceeding will override the settings for the existing prompt.
If you select the Set prompt to global variable option, you can also select whether to Synchronize prompt names and global variables names. If you do, then the names are kept in sync. Otherwise, you can edit the global variable name to make it different than the name of the prompt.
For information about the other VME settings for this action, see Prompt action. For more general information see Prompt action (<prompt> element).
The Set cursor position 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.
Specify the Row and Column location where you want the mouse click to occur. The screen capture is displayed if it is available. If so, you can click on it to set the Row and Column fields. You can also enter into the Row and Column fields a variable name in the form $var$.
For more information see <mouseclick> element.
The Update variable action allows you to update the value of a macro variable. This action can only be added for macros in advanced macro format.
For more information see Variable update action (<varupdate> element).
The Next Screen Connection tool of the palette allows you to define a new next screen connection.
To add a next screen connection between two screens, click Next Screen Connection in the palette, click on the source screen and then click on the target screen.
If other connections originating from the same source screen exist, the new connection will have the highest order or priority. You can use the Reorder action on the next screen connection pop-up menu to change the order.
To create a loop, that is a next screen connection with the same source and target, click on the same screen twice. The loop is displayed as an arrow, if no other next screen connection is defined for the screen, or as a circle showing the order, if more next screen connections are defined for the screen.
The Reorder action on the next screen connection pop-up menu allows the order (or priority) of the connection to be changed. This impacts the order of all the other next screen connections originating from the same screen.
The Reorder action works as an Up and Down. That is, if the connection with order 2 is changed to order 3 (down 1), then the connection with order 3 goes to order 2 (up 1).
The source or target of a next screen connection can be changed by dragging the appropriate end of the connection to a new source or target screen.
To work with VME preferences, from the menu bar select Window > Preferences > HATS > Visual Macro Editor. You can modify the following preferences: