Macros and host terminal

A macro is an XML script that defines a set of screens. Each screen includes a description of the screen, the actions to perform for that screen, and the screen or screens that can be presented after the actions are performed.

ZIETrans supports macro-based customization to speed up and customize the host application process. Macros can be used for the following functions:

You can use macros to do any or all of the following functions:

Skip-screen
Skip-screen macros are navigational macros that move the user from one screen to another screen without displaying intervening screens.
Prompt
Prompt macros contain steps to request input from users during the host session. They can also set prompts from a user list. For example, you can use a prompt macro to ask a user for a user ID and password before logging into a host application.
Note:
User list prompts can only be used in connect macros.

Prompt macros can also be used by developers to provide constant values or values obtained from global variables.

Extract
Extract macros contain events to extract host screen information as a string, as a list of strings, or as a table. For example, you can use an extract macro to connect to a directory-type host application and extract the results of doing a search in the directory.

Macros recorded or imported in ZIETrans Toolkit are saved in a ZIETrans macro (.hma) file. You can see the macros defined in your project by expanding the Macros node in the ZIETrans Projects view of the ZIETrans Toolkit.

ZIETrans provides three different editors you can use to view and modify ZIETrans macros, the Macro Editor, the Advanced Macro Editor, and the Visual Macro Editor. The Visual Macro Editor is the default editor for ZIETrans macros. When you double-click on the name of a macro, the Visual Macro Editor is opened. For more information about the Visual Macro Editor, see the chapter, Visual Macro Editor, in the ZIETrans Advanced Macro Guide.

To open the Macro Editor, right-click on the name of the macro and select Open With > Macro Editor.

The Advanced Macro Editor is opened from the Macro Editor Overview page. For more information about the Advanced Macro Editor, see the chapter, Advanced Macro Editor, in the ZIETrans Advanced Macro Guide.

Note:
Support for the Macro Editor and the Advanced Macro Editor is deprecated in ZIETrans V1.0. While support continues for now, it may be removed in a future release of the product. This support is replaced by the Visual Macro Editor.

Macro Editor

The following sections describe each tab of the macro editor.

Overview

The Overview tab of the macro editor summarizes general information about the macro, such as the name, description and last modified date and time. The items you can modify on this tab are the description of the macro, the pausetime, timeout and connection.

Pausetime is the number of milliseconds of delay after each action is performed. Timeout is the number of milliseconds to wait before terminating the macro and Connection lets you select which connection to use from the drop-down menu.

The Open Host Terminal and Advanced Editor buttons are described in detail below.

Figure 54. ZIETrans macro recording
Macro recording using the host terminal

Open Host Terminal

You can click Open Host Terminal to create or work with your macro using the host terminal. Once the terminal opens, you can use any of the icons on the toolbar to record and create your macro.

Host Terminal

You can also use the Host Terminal to edit a previously recorded macro by right-clicking on the nodes in the macro tree and selecting Edit. If you select a screen to edit, this will launch the screen recognition criteria editor which will allow you to modify your screen. If you edit any input that you entered in your screen, a window will open up and allow you to change or modify the input. If you edit the Next Screens node, you will be given a list of available screens to select for your next screen. Select from the list in the order you want your screens to appear.

To debug macro play errors, four icons exist on the Host Terminal toolbar. The icons are designed to help you step through a macro, where a step is defined as playing one action or recognizing one screen. The icons are Step Into, Step Over, Step Return and Resume.

Each of the icons have function keys associated with them. Depending on which view is active (either the Macro Navigator or the Host Terminal) , the F5, F6, F7, and F8 keys will function differently. For instance, if the Macro Navigator is active, pressing F5 will do Step Into, and pressing F6 will do Step Over. If the Host Terminal is active, pressing F5 or F6 will send the AID key to the host. For more information about these and other macro related icons, see Macro related icons.

Notes:
  1. ZIETrans requires you to define screen recognition criteria for certain screens. These screens are:
    • First and last macro screen
    • Start and end of a loop
    • Macro extract
    • Macro prompt
  2. Cut, copy, and paste functions are provided in the host terminal by using the following key combinations:
    • Cut: Ctrl-X or Shift-Delete.
    • Copy: Ctrl-C or Ctrl-Insert.
    • Paste: Ctrl-V or Shift-Insert.
  3. Two new Video Terminal (VT) connection properties enable you to force the normal foreground or background of the VT Host Terminal to selected colors. This might be useful in a case where a VT application changes a foreground color to match the background color and thus renders the text unreadable on the Host Terminal.

    The settings can be added to the Advanced tab of the connection editor. The settings, which operate independently of each other, are forceVTNormalForegroundToColor and forceVTNormalBackgroundToColor .

    The format for the setting value is redValue,greenValue,blueValue where the values each range from 0 to 255. For example, to override the normal foreground color to be white, add this setting to the table of advanced settings:

    forceVTNormalForegroundToColor = 255,255,255

    These settings only affect the normal foreground and background colors. If any character attributes are set (bold, blink, underline, or reverse) or if any of the ANSI colors are set by the VT application, these settings are ignored.

    For more information about advanced connection settings, see Configure optional, advanced connection settings.

Table 4 shows the macro icons that appear on the host terminal screen toolbar.

Table 4. Macro icons
Icon Description
open macro
Open a macro. Use the drop-down list to select a macro.
play macro
Play a macro. Use the drop-down list to select a macro.
record macro
Start recording a macro
stop macro
Stop recording a macro
save macro
Save the recorded macro
step into
Step Into (F5) the macro for debugging purposes
step over
Step Over (F6) the macro for debugging purposes
step return
Step Return (F7) in the macro for debugging purposes
resume
Resume (F8) playback of the macro
define macro screen recognition criteria
Define the screen recognition criteria for a macro screen
add a prompt action
Add a prompt action into the current macro (enabled only when recording a macro)
add an extract action
Add an extract action into the current macro (enabled only when recording a macro)
record a loop macro
Record a loop into the current macro (enabled only when recording a macro)
add prompt actions for all fields
Add prompt actions into the current macro for all fields on the screen (enabled only when recording a macro)
add extract actions for all fields
Add extract actions into the current macro for all fields on the screen (enabled only when recording a macro)
show/hide keypad
Show or hide the keypad in the host terminal window
text OIA
Show or hide the textual Operator Information Area (OIA)
Macro related icons

Below is a list of macro related icons on the Host Terminal toolbar:

Record macro

You can record macros in ZIETrans Toolkit using the ZIETrans host terminal. On the ZIETrans host terminal screen, click the Record macro icon. The Record Macro wizard appears and enables you to select the target project, name the macro, give it a description, and see where the macro is saved. The option, Create screen captures automatically while recording, lets you specify that a screen capture automatically be created for every screen navigated while recording the macro. These screen captures can then be used within the Visual Macro Editor if you must later make changes to the macro. This option is selected by default. Click Finish when you have specified these items.

Next the Define Screen Recognition Criteria window appears because ZIETrans forces the first screen to have explicitly defined screen recognition. You can then use the ZIETrans host terminal screen to navigate through the host application to any screen.

If you have a macro already open within the ZIETrans host terminal, the Record macro icon will ask if you want to record a new macro or append to the open macro. If you append to the open macro, then macro recording will begin, and your actions will be appended to the current macro. The location within the macro where recording begins depends on what is selected in the Macro Navigator tree on the left, and whether the current terminal screen matches the screen recognition criteria of the selected node. Specifically:

Do not create a macro whose only step is to insert an extract or add a prompt. If you do this, when the user supplies a value, the page will not change, and there will be no way for the user to move to another page. If a macro doesn't go back to the host, it will sit and time out.

Note:
If you intend to create an Integration Object from a macro, ensure that you follow these requirements when naming the macro:
  • The name of the macro must consist of only letters, digits, or underscore characters.
  • The first character of the name cannot be a numeral.
  • Double byte (fullwidth) characters are not allowed.
Stop Macro
When you are finished recording your macro, click the Stop Macro icon.
Save Macro
Once you have stopped recording your macro, you will need to save it by clicking the Save Macro icon.
Step Into (F5)
Clicking the Step Into (F5) icon allows you to step from a screen to its first enclosed action, and from action to action. Using the F5 key on your keyboard will perform the same function. This is used for debugging purposes.
Step Over (F6)
Clicking the Step Over (F6) allows you to go from screen to screen (performing all intervening actions). Using the F6 key on your keyboard will perform the same function. This is used for debugging proposes.
Step Return (F7)
Clicking the Step Return (F7) allows you to finish playing the actions under a screen and go to the next screen. Using the F7 key on your keyboard will perform the same function. This is used for debugging proposes.
Resume (F8)
To resume the playback of your macro, you can either click the Resume (F8) icon or press the F8 key on your keyboard. This can be used to run the rest of your macro if you are currently stepping through it.
Define Screen Recognition Criteria

You can set screen recognition criteria that ZIETrans uses to match host screens. Host screens can be recognized by any combination of criteria including how many input fields or total fields are on the screen, the coordinates of the cursor's position, and text strings on the screen within a defined rectangle or anywhere on the screen. For more information see Screen Recognition Criteria or Begin Screen.

Add Prompt Action

If you want the macro to prompt the user for information, click Add Prompt Action to display the Add Prompt Action wizard. You can give the prompt a name and a default value. If the information the user provides, such as a password, should not be displayed on the host screen, click the Password protect input check box.

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.

The Row and Column fields of the Position section of the wizard define where on the host screen the prompt information provided by the user is placed. If you place your cursor at a location on the host screen, such as the field for a password, before you begin recording the macro, the Row and Column fields are filled with those values. The Handle Macro Prompt section of the wizard enables you to determine how the prompt is processed. You can select one of the following radio buttons:

Show handler
For 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 ZIETrans 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.
Notes:
  1. 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.
  2. The Show handler option is disabled when the macro extracts from a plane other than the text plane.
Note:
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, see Interacting with global variables.
Note:

If a prompt value is based on a global variable set by an extract, and promptall 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 promptall to false.

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, see User List.
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.

Click OK when you have made your selections.

Add Extract Action

If you want the macro to extract information from the host screen, select an area on the host screen then click Add Extract Action to display the Add Extract Action wizard. You can specify a name for the extract. The Start row, Start column, End row, and End column fields of the Position section of the wizard define from where on the host screen the information is extracted. When you mark a region of the host screen with a rectangle and then click Add Extract Action, the Position section fields are filled with the values when the Add Extract Action wizard is displayed.

You can specify the Extraction Format as either:

The Handle Macro Extract section of the wizard enables you to determine how the prompt is processed. You can select the following check boxes:

Show handler
For 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, you must specify how to handle the existing variable by selecting one of the following radio buttons:
  • Overwrite the existing value with this new value
  • Overwrite the existing value with this new value, starting at the specific index.
  • Append this new value to the end of the existing value.
  • Insert this new value into the existing value, at the specific index.
You can also specify whether this variable is shared by selecting the Shared check box.
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 promptall to false. When promptall 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.

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.

Click OK when you have made your selections.

Record a Loop

If you want to record a loop in your macro, click Record a Loop then navigate to the screen where the loop will begin. Click Next to define the screen recognition criteria for the first screen in the Click Next to define additional criteria or Finish to return to the main terminal. At the main terminal, perform the actions which will be run during each cycle of the loop then press Next. Determine how your loop will end by selecting either End when a unique screen is recognized or End after a fixed number or iterations and enter the number of loops below. Click Next then navigate to the final screen of the loop and press Finish to complete the loop.

Note:
Significant emphasis should be placed on the screen recognition criteria for the starting and ending screens of the loop. In some cases, you may have a starting screen that is almost identical to the ending screen. You must be careful in distinguishing these screens from one another.
Add Prompt Actions for All Fields
If you select this icon, the Insert All Fields from Global Variables window will open. There you can select a Stored Screen name from the drop-down list. You also have the option of creating a screen capture by selecting the Create a Screen Capture check box. Selecting the Shared check box will take the global variable from the shared list.
Notes:
  1. Default values that you specify for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts in the host terminal macro editor or the advanced macro editor. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.
  2. If you use this option with Integration Objects, ZIETrans will add fields to the Integration Object for each defined global variable. You must write code to set the global variable values and copy them into the Integration Object before it is run. This can be done in the .jsp page that runs the Integration Object. For more information, see Insert Integration Object Properties. Remember only shared global variables can be accessed by Integration Objects.
Add Extract Actions for All Fields
If you select this icon, the Extract All Fields from Global Variables window will open. There you can select a Stored Screen name from the drop-down list. which will be used as a prefix for the global variables created for all fields. If the text of the protected fields should be grabbed at runtime, select the All fields option. If the text for the protected fields will be static in the transformation JSP, select the Input fields option. Selecting the Shared check box will take the global variable from the shared list.
Note:
If you use this option with Integration Objects, ZIETrans will add fields to the Integration Object for each defined global variable. You must write code to copy the data from the Integration Object into shared global variables after the Integration Object is run. This can be done in the .jsp page that runs the Integration Object. For more information, see Insert Integration Object Properties. Remember only shared global variables can be accessed by Integration Objects.
Show/Hide Keypad

This icon allows you to either show the terminal keypad or hide the terminal keypad.

Show Textual OIA

The Show Textual OIA (Operator Information Area) icon allows you to see the exact row and column position of the cursor on your terminal screen. It also tells you whether the input is inhibited or not inhibited.

Host Screen Preview

To see what the current host screen would look like if transformed by the server, click the Host Screen Preview tab at the top of the Host Terminal window. The preview screen will display the host screen you are on as a Web page.

The host screen preview first applies any screen customization defined for the present screen. If there are no screen customizations defined for the current screen, the project level template and default rendering rules are applied to the screen.

The host screen preview applies the order of screen customizations listed in the Events tab of your Project Settings. As soon as it finds a screen recognition match is shows you the screen transformed by the transformation defined in that screen customization (if any). If there is not match, then the default transformation is shown.

The host screen preview will not process any screen customizations defined in the next screen list. Next screens are not processed in the host screen preview. For more information, see Next Screen.

Note:
The Host Screen Preview tab is only seen if your current host terminal is associated with the default connection. If you open a host terminal on a background connection, you will not see this preview.

Advanced Editor

You can also click Advanced Editor on the Overview tab to launch the advanced features of the ZIETrans macro editor, and modify settings for the macro. A separate window opens for the macro editor which has the following tabs:

For more information about the advanced editor features of the macro editor, see ZIETrans Advanced Macro Guide.

Prompts and Extracts

The Prompts and Extracts tab of the macro editor lists the configured macro prompts and extracts, and how they are handled when the macro is played. You can edit the ZIETrans-specific properties of a prompt or an extract by selecting it in the table and clicking Edit.

Source

The Source tab displays the tags in the macro-name.hma file for all the attributes and values for the macro, where macro-name is the name you gave to the macro when you created it or imported it. As you make changes on other tabs in the project editor, the tags and attributes displayed in the source file change to match. You can also make changes to the tags and attributes in the source file, and they are reflected on the appropriate tabs of the macro editor.

Prompts and extracts appear in the macro source file in the order that you recorded them. In addition, when you open the macro in the editor, the cursor appears on the same line it was on when you last saved the macro, instead of appearing at the top of the macro file.

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 product provide content assistance. For instructions, see Macro Content Assistance.

Working with macro errors

Errors in a macro are summarized in the Problems view, whether you are using the macro editor, text editor, or XML editor. The source code of the macro displays a marker, a red circle with a white X in it, which appears on any lines containing an error.

The macro can be saved even when it contains errors, enabling you to find and fix the errors at a later time, if necessary. However, macros containing errors cannot be played at runtime or in the host terminal.

Importing a macro

You can also import macros recorded with other programs, such as the IBM® WebSphere® Host Publisher or IBM Host On-Demand. To import these macros, select File > Import > ZIETrans > Host Publisher/HOD Macro and click Next to display the Import a Host Publisher/HOD Macro dialog. Click Add and navigate to the location of the macro on the file system.

Notes:
  1. A Host On-Demand macro with an exit screen that performs an action that submits an AID key to the host may cause timing problems when running in the ZIETrans runtime. When the macro finishes running, ZIETrans runtime renders the exit screen. But the AID key causes the host to return another (trailing) screen which is not rendered. To correct this timing problem, do one of the following:
    • Use the automatic refresh function to display the trailing screen. See Automatic Disconnect and Refresh  Web-only .
    • Use the Visual Macro Editor (VME) to change the exit screen for the macro from the original exit screen to the trailing screen. The integrated terminal of the VME works like Host On-Demand and can be used to play the macro and display the trailing screen. Use the VME to add the trailing screen to the macro, change its properties to indicate it is the exit screen, and change the properties of the original exit screen to remove the exit screen indication. For more information, see the Visual Macro Editor chapter in the ZIETrans Advanced Macro Guide.
  2. Host Publisher macros with fixed iteration loops continually recognize the same screen and perform different actions. In ZIETrans, you cannot create a screen customization to recognize the same screen a second time and perform a different action than the first time it was recognized. If you attempt to use a Host Publisher macro with fixed iteration looping, your project might go into an infinite loop. Host Publisher macros with fixed iteration looping can be identified by looking at the source code for the macro. The macro contains customreco tags with ID attributes of HPubFixedIterationLoop and custom tags with ID attributes of HPubIncrementLoop.

Exporting a macro

You can export ZIETrans macros as well as IBM Host On-Demand macros. To export these macros, select File > Export > ZIETrans > ZIETrans Macro or File > Export > ZIETrans > HOD Macro and click Next.

Select the Macro files to export along with the destination. You can elect to overwrite the existing resources by selecting the Overwrite existing resources with warning check box.

Click Finish when done.

Note:

For considerations when using DBCS support see Exporting a macro.

Macro hints and tips

Preventing an infinite loop

Running a macro is one of the actions that you can specify to be performed when a host screen matches a screen customization's recognition criteria. When you record a macro, be sure that the final screen is not the screen that is recognized by the screen customization that has the macro defined as the action. If the recognized screen is the final screen of the macro, a loop will be created.

Handling transient screens

You can define transient screens along with non-transient screens for your macros. However at runtime, you may see one of your transient screens get recognized unexpectedly.

When comparing macro next screen descriptors, non-transient screen descriptors are compared first, then transient screen descriptors are compared. If the current screen information is updated after comparison of non-transient screen descriptors begins, the updated screen information is used for transient screen descriptor comparison. Therefore, it is possible that if a screen is locked (OIA is input-inhibited) when non-transient screen comparison begins, and then becomes unlocked, with no other changes, before transient screen comparison begins, this can cause non-transient screens to not be recognized, but then subsequently transient screens can be recognized, which is not the expected behavior.

To avoid this unexpected behavior, you can control whether the same screen information is used when comparing non-transient screen and transient screen descriptors. To do this, add the advanced connection setting, screenRecoUseOIASnapshot, and set its value to true. For how to set advanced connection settings, see Configure optional, advanced connection settings.