Visual Macro Editor

The Visual Macro Editor (VME) gives you the ability to visually develop HCL ZIETrans macros. The VME combines many of the features of the HCL ZIETrans 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 HCL ZIETrans 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.

Note:
Support for the Macro Editor and the Advanced Macro Editor is deprecated in HCL ZIETrans V1.0. While support continues for now, HCL reserves the right to remove these capabilities in a subsequent release of the product. This support is replaced by the Visual Macro Editor.

Creating a new macro

In addition to using the host terminal, you can use the VME to create a new macro using the New Macro wizard.

In the HCL ZIETrans perspective, use any of the following procedures to start the New Macro wizard:

The wizard includes one panel where you can:

Using the editor

The VME is the default editor for HCL ZIETrans macros. When you double-click on a macro object (.hma file), the VME opens.

The VME is composed of the following parts:

  1. Design tab
  2. Palette view
  3. Integrated terminal
  4. Source tab
Figure 49. Visual Macro Editor parts
Visual Macro Editor parts

Design tab

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.

Figure 50. Visual Macro Editor design tab
Visual Macro Editor design tab

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.

Macro menu

The following actions are enabled on the macro's pop-up menu (right-click on the white macro canvas):

Save
Saves the macro to a file, disabling the Undo and Redo actions.
Copy As image
Copies the entire image of the macro to the system clipboard. This is useful for pasting the image of the macro into an email, or design document.
Paste
Only enabled after a screen copy or cut.
Reset Layout
Resets the macro screens by attempting to minimize the number of crossed next screen connection lines. Entry screens are positioned at the top. Exit screens are positioned at the bottom. By default, the layout is reset when a screen is added using the integrated terminal. The layout of a macro created in a previous version of HCL ZIETrans is automatically set (using this same algorithm) when the macro is opened the first time in the VME.
Properties
Allows editing macro-level settings.

Screen menu

The following actions can be performed on a screen's pop-up menu (right-click a macro screen object):

Cut
Deletes and copies the macro screen. For more information, see Cut, delete, copy, and paste screens.
Copy
Copies the macro screen and allows pasting it into the same macro or another macro. For more information, see Cut, delete, copy, and paste screens.
Paste
Only enabled after a screen copy or cut.
Delete
Removes the macro screen from the macro. For more information, see Cut, delete, copy, and paste screens.
Rename
Allows renaming the macro screen. Disabled if more than one screen is selected.
Properties
Allows editing macro screen-level settings. Disabled if more than one screen is selected.

Action menu

The following actions can be performed on a screen action's pop-up menu (right-click a screen action):

Edit
Allows editing the screen action. Only enabled if one action is selected. For more information, seeAdding and editing actions.
Remove
Removes the action from the macro screen.
Move Up
Moves the action up in the list of screen actions. Disabled for the first action.
Move Down
Moves the action down in the list of screen actions. Disabled for the last action.

Next screen connection menu

The following actions can be performed on a next screen connection's pop-up menu (right-click a next screen connection object):

Delete
Removes the next screen connection from the macro.
Reorder
Enabled on a next screen connection if there are other next screen connections originating from the same screen. Disabled when more than one next screen is selected. For more information, see Reordering and changing next screen connections.

Palette view

The Palette allows you to:

Figure 51. Visual Macro Editor Palette view
Visual Macro Editor Palette view

Integrated terminal

The integrated terminal toolbar allows for the following actions:

Connect
Connect to the host.
Disconnect
Disconnect from the host.
Add Screen
See Adding a screen from the integrated terminal.
Play Macro
See Playing the macro.
Stop Macro
See Playing the macro.
Host keypad
Interact with the host using the host keypad pull-down.
Note:
In the integrated terminal, when navigating the host application, the F12 key is intercepted by IBM® Rational® Software Delivery Platform (Rational SDP), which then moves the focus to the design pane of the VME. The F12 key is never sent to the host application. To work around this issue, and for other host keys as needed, use the host keypad pull-down from the toolbar.
Figure 52. Visual Macro Editor integrated terminal
Visual Macro Editor integrated terminal

Source tab

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.

By default, content assistance is enabled for all macros in the project. While editing a macro on the Source tab, press Crtl+Space to invoke content assistance. You can configure which macros in the project provide content assistance. For instructions, see Macro Content Assistance.

Working with macros

Editing macro properties

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.

General tab

The General tab allows you to view and modify the following macro properties:

Name
Name of the macro (view only).
Description
Description of the macro. Optional.
Author
Author of the macro. Optional.
Creation date
Date and time when the macro was created. Optional.
Pause between actions
The amount of time (in milliseconds) the macro playback engine waits between executing actions in a macro screen.
Timeout between screens
The amount of time (in milliseconds) the macro playback engine waits for a next screen to appear.
Handle all prompts at start of macro
Specifies whether the user is prompted for all of the macro's prompts at the start of the macro.
Connection
The name of the connection in the project to use. For HCL ZIETrans projects with a single connection, the connection is typically named main. This setting is important if the macro is used in an Integration Object (IO) because this value is hardcoded in the generated IO when the IO is created and is used at runtime to select which connection to use.
Automatically connect terminal when the macro is opened
Specifies whether to automatically connect the integrated terminal when the macro is opened.

Variables and Types tab

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.

Playing the macro

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.

Working with screens

Editing macro screen properties

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.

General tab

The General tab allows you to modify the following properties:

Name
Name of the macro screen.
Screen capture
If a screen capture is associated with the macro screen, then a preview is shown in the screen capture area. If no screen capture is associated with the macro screen, then a message is displayed in the screen capture area.

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.

Entry screen
Specifies a screen on which the macro can begin.
Exit
Specifies a screen on which the macro can end.
Transient screen
Specifies an unpredictable screen that may appear at anytime.
Set Recognition Limit

Specifies the number of times that the macro runtime recognizes the macro screen. When the macro runtime recognizes the macro screen by the specified times, the macro runtime does not process the actions of this macro screen, but instead performs the specified action.

By default the Set Recognition limit check box is cleared and the input field is disabled. If you select the check box, then the macro editor sets the default value of the Screens Before Error input field to 100. You can set the value to a larger or smaller quantity. For more information, see Recognition limit.

Set Pause Time
Specifies the time between actions for a particular macro screen.

Screen Recognition tab

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.

Actions tab

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.

Adding macro screens

Adding a screen by dragging a screen capture

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.

Adding a screen from the integrated terminal

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:

Adding a screen from the palette

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.

Associating a macro screen with a screen capture

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.

Screen preview

Hovering the mouse over a screen on the canvas shows a preview of the screen capture associated with it, if any.

Default screen recognition criteria

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.

Cut, delete, copy, and paste screens

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.

Figure 53. Delete screen example - before cut or delete
Delete screen example - before cut or delete

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.

Figure 54. Delete screen example - after cut or delete
Delete screen example - after cut or delete

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.

Figure 55. Copy screens example
Copy screens example

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.

Figure 56. Paste screens example
Paste screens example

Some considerations must be made when pasting one or more screens from or to a macro in advanced macro format.

Working with actions

Adding and editing actions

Adding and editing actions from the macro screen properties

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.

Figure 57. Visual Macro Editor actions
Visual Macro Editor actions

Adding an action to a screen from the palette

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.

Hiding and showing actions

Screen actions can be hidden or shown by clicking the toggle on the upper right corner of the screen figure.

Figure 58. Hiding screen actions
Hiding screen actions

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.

Figure 59. Showing screen actions
Showing screen actions

Actions

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.

Custom action

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:

ID
An arbitrary string that identifies the Java program that you want to run.
Arguments
Optional. The arguments that you want to pass to the Java program.

For more information see <custom> element.

Evaluate (If) action

The Evaluate (If) action provides the functions of an if-statement or of an if-else statement.

Condition
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. For more information, see Conditional and logical operators and expressions.
If True
Click this tab and click Add to add actions to perform for the case if the Condition is true.
If False
Click this tab and click Add to add actions to perform for the case if the Condition is false.

You can Add, Edit, Remove, move Up, or move Down, actions to perform for each case.

Note:

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

Extract action

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

Name
Specifies the name of the extract.

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.

Start row, Start column, End row, End Column
Specify the row and column coordinates of the area of the host screen to extract. When you use the mouse to mark the area on the host screen, these fields are filled for you.

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.

Extract this region as one string
When extracting from the text plane, specifies that the extracted text should be saved as a single horizontal string of characters. This option is supported for Integration Objects, macro handlers, global variables, and macro variables.

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.

Extract this region as a list of strings
When extracting from the text plane, specifies that the extracted text should be saved as a vertical list of strings. This option is supported for macro handlers, global variables, and macro variables. For an Integration Object, a list of strings is treated as one continuous string.

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.

Extract this region as a table
When extracting from the text plane, specifies that the extracted text should be saved as a table of horizontal and vertical strings, with rows and columns. This option is supported for Integration Objects, macro handlers, and macro variables. For a global variable, strings extracted as a table become one continuous string.
Note:
When extracting from the other (non-text) planes, this option is disabled because this non-text data is not intended to be displayed directly to a user. Instead, it is meant for developers who need the extra data to determine how to display or handle certain host screens.

Click Define to define the table.

Table Extract Configuration
Use this page to format the columns of the table.
  • Column name

    Use this field to change the heading of the selected column.

  • Expand 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.

  • Reduce 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.

  • Merge

    Use this button to merge two highlighted columns into a single column. The characters in the highlighted columns are joined into one column.

  • Divide

    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.

    Note:

    When you click Divide, HCL ZIETrans 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.

Note:
When extracting from the other (non-text) planes, this option is disabled because this non-text data is not intended to be displayed directly to a user. Instead, it is meant for developers who need the extra data to determine how to display or handle certain host screens.
Show handler
For HCL ZIETrans Web applications, you can select a .jsp file to display the extracted information to the user. A default macro handler is shipped with ZIETrans, and it is named default.jsp. You can find this in the ZIETrans Projects view, expanding the project name, and expanding Web Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the ZIETrans runtime.
Note:
Integration Objects do not use this option. Instead, the output page will retrieve the extracted data from the Integration Object and display them.
Save as global variable
You can enter a name for the global variable in the Name field or select an existing variable using the drop-down menu. If you select an existing global variable in the Name field, click Advanced and specify how to handle the existing variable by selecting one of the following radio buttons: You can also specify whether this variable is shared by selecting the Shared check box.

If you select to save the extract data as a global variable, the Text option of the Planes to extract setting is automatically selected.

Note:
If you extract a value and assign it to a global variable set by an extract, and you plan to use the global variable value for a prompt, you should set the promptall attribute to false. When the promptall attribute is set to true, the extract action is not run before the prompt values are retrieved. Because of this, the global variable used by the prompt does not contain a value. Macros recorded in HCL ZIETrans default to promptall=true. For further information regarding the promptall attribute, see The promptall attributes.

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.

Save as macro variable
Select this box to specify a macro variable in which to save the extract data. This option is only displayed if macro variables are enabled for the macro.

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.

Variable
Select the variable in which to save the extract data. The drop-down menu is populated with all variables defined in the macro.

Use the Advanced section to set the following options:

Extract as one continuous region
Clear this box to capture a rectangular block of text. For more information, see Capturing a rectangular area of the host terminal. Select this box to capture a continuous sequence of text that wraps from line to line. For more information, see Capturing a sequence of text from the host terminal.
Unwrap
Select this box to capture the entire contents of any field that begins inside the specified extract area. For more information, see Unwrap attribute.
Planes to extract
Select the plane from which the data is to be extracted. The options are listed below. The default is Text.

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.

Notes:
  1. For information about the format and contents of the different data planes in the Host Access Class Library (HACL) presentation space model, see Host Access Class Library Planes -- Format and Content at https://www.ibm.com/support/knowledgecenter/SSS9FA_13.0.0/com.ibm.hod.doc/doc/hacl/DWYL0M88.HTML?origURL=api/redirect/hodhelp/v13r0/index.jsp.
  2. For an example of how to use non-text plane data in an Integration Object see the section, Extracting data from non-text planes, in the ZIETrans Web Application Programmer's Guide.

For more information see Extract action (<extract> element). For considerations when using bidirectional language support, see Macro prompt and extract bidirectional options in the ZIETrans User's and Administrator's Guide.

Extract All action

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

Input action

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

Insert at current cursor position
Select this box to have the macro runtime insert the input at the current cursor position on the host terminal. Clear this box to set the cursor Row and Column fields yourself. Enter the cursor row and column at which to insert the input. If a screen capture is available, you can click on it to set the cursor row and column. You can also enter into the Row and Column fields a variable name in the form $var$.
String
Enter into this field the string to send to the host terminal. You can enter an AID key into this field. For example, pressing F12 on the keyboard will insert [pf12]. Other AID keys can be inserted using the drop-down menu next to the field. Since a [tab] will be inserted if the TAB key is pressed, the mouse must be used to exit the field.
Translate host action keys
Select this box, which is the default value, to have the macro runtime interpret an action key string (such as [enter]) as an action key rather than as a literal string.
Move cursor to end of input
Select this box to have the macro runtime move the text cursor to the end of the input
Encrypt string
Select this box to have the macro editor encrypt the sequence of keys contained in the String field.

For more information see Input action (<input> element).

Pause action

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:

Duration (in milliseconds)

Specifies the number of milliseconds to wait. The default is 10000 milliseconds (10 seconds).

For more information, see <pause> element.

Perform action

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

Java method
Specifies the method to run. 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.

For more information see Perform action (<perform> element).

Play macro action

The Play macro action runs another macro.

Macro
Select from this list box the macro to run. The list box is populated with all the macros in the project.
Start screen
Select from this list box the macro screen in the target macro that you want the macro runtime to process first. Select (default) to start the target macro at its usual start screen.
Transfer macro variables
Select this box to have the macro runtime transfer to the target macro all the variables that belong to the calling macro, including the contents of those variables.

For more information, see PlayMacro action (<playmacro> element).

Prompt action

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

Name
Specifies the name of the prompt. This name is displayed in the prompt to the user, so you can use it to provide instructions related to the prompt field.

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.

Default value
Specifies a default value to use for the prompt field.
Password protect input
Select this box to encrypt prompt input provided by the user.
Note:
Default values that you specify for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts using the macro editors. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.
Save value to macro variable
Select this box to specify a macro variable in which to save the prompt input. This option is only displayed if macro variables are enabled for the macro. The Do not insert value into field option is only enabled if Save value to macro variable is selected.
Variable
Select the variable in which to save the prompt input. The drop-down menu is populated with all variables defined in the macro.
Do not insert value into field
Select this box to have the macro runtime not display the prompt input in the input field. This field is enabled only when the Save value to macro variable box is selected.
Clear field before inserting value
Select this box to have the macro runtime clear the contents of the input field before typing begins.
Insert at current cursor position
Select this box to have the macro runtime insert the prompt input at the current cursor position on the host terminal. Clear this box to set the cursor Row and Column fields yourself. Enter the cursor row and column at which to insert the prompt input. If a screen capture is available, you can click on it to set the cursor row and column. You can also enter into the Row and Column fields a variable name in the form $var$.
Translate host action keys
Select this box, which is the default value, to have the macro runtime interpret an action key string (such as [enter]) as an action key rather than as a literal string.
Move cursor to end of input
Select this box to have the macro runtime move the text cursor to the end of the input

The Handler section enables you to determine how the prompt is processed. You can select one of the following radio buttons:

Show handler
For HCL ZIETrans Web projects, you can select a .jsp file to prompt the user for the necessary information, and include a button for the user to submit the information. A default macro handler, named default.jsp, is shipped with ZIETrans. You can find this file by clicking the ZIETrans Projects view of the Toolkit, expanding the project name, and expanding Web Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the ZIETrans runtime.
Note:
Integration Objects ignore the selected .jsp handler. Instead, an input page is created for the Integration Object, and a prompt for the value is placed in that input page. The generated output page copies the value supplied by the input page into the Integration Object before the Integration Object is run.
Set prompt to string
If you know what value should be returned from a prompt, you can enter that string in the String field.
Set prompt to global variable
If you want the value of the prompt to be provided by a global variable, enter a name for the global variable in the Name field or select an existing variable using the drop-down menu next to the Global variable field. If you click the Advanced button, you can specify whether your variable is shared or indexed. If it is an indexed variable, you also need to specify whether to show all indexes or a single index. For more information about global variables, see the chapter, Interacting with global variables, in the ZIETrans User's and Administrator's Guide.
Note:

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.

Set prompt to property from User List
If you want the prompt to access a user list, select the User Profile from the drop-down list. The user profile is the key as to determining whether to use the userid or password as the User List property. For more information about user lists, see the section, User List, in the ZIETrans User's and Administrator's Guide.
Note:
User list prompts can only be used in connect macros.
Use Web Express Logon
If you have configured your ZIETrans application to use web express logon, enter the prompt type as either the user ID or password in the Prompt type drop-down list and enter the application ID in the Application ID field.
Note:
The Prompt type should be prefilled with the correct value.

For more information see Prompt action (<prompt> element). For considerations when using bidirectional language support, see Macro prompt and extract bidirectional options in the ZIETrans User's and Administrator's Guide.

Prompt All action

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

Set cursor position action

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.

Trace action

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

Trace specification

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

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

For more information, see Trace action (<trace> element).

Update macro variable action

The Update macro variable action allows you to update the value of a macro variable. This action can only be added for macros in advanced macro format.

Variable
Select from this list box the name of the macro variable to update. The list box drop-down is populated with all the variables defined for the macro
Type
Displays the type of the selected macro variable.
Value
Specifies the value to assign to the macro variable. The value must be in the correct format for the type.

For more information see Variable update action (<varupdate> element).

Working with next screen connections

Adding a next screen connection from the palette

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.

Reordering and changing next screen connections

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.

Working with VME preferences

To work with VME preferences, from the menu bar select Window > Preferences > HCL ZIETrans > Visual Macro Editor. You can modify the following preferences:

Show screen actions by default
Select this preference to show actions on macro screen objects by default. Clear this preference to hide the actions by default. You can click the action toggle on the macro screen to show/hide the actions for the specific screen. This preference only affects macros opened in the VME for the first time. The default is selected.
Restrict number of screen actions shown
Specifies the maximum number of actions displayed for a macro screen object. This is useful for complex macros where the interface is too complex if all actions are shown. The default is 5.