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:
  • If a screen node or an action node is selected in the Macro Navigator, and the current host terminal screen matches the recognition criteria of the selected screen, the new actions will be added at the beginning of the selected node. If an action was selected within the matching screen node, then recording will begin immediately following the selected action within the matching screen.
  • If a screen node or an action node is selected in the Macro Navigator window, and the host terminal screen does not match the recognition criteria of the selected screen, then a new screen node will be added to the Next Screens of the selected node, and recording will begin at the new screen node.
  • If the high level node is selected in the Macro Navigator window which corresponds to the macro name, then ZIETrans will search through all of the screen nodes and try to find a match for the current terminal screens. If a match is found, recording will begin at the beginning of the matching screen. If a match is not found, then a new screen node will be added to the Next Screens of the last screen and recording will begin at the new screen node.

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.
Note:
  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:
  • Extract this region as one string

    Specifies that the extracted text should be saved as a single horizontal string of characters. This option is supported for Integration Objects, global variables and macro handlers.

  • Extract this region as a list of strings

    Specifies that the extracted text should be saved as a vertical list of strings. This option is supported for global variables and macro handlers. For an Integration Object, a list of strings is treated as one continuous string.

  • Extract this region as a table:

    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 and macro handlers. For a global variable, strings extracted as a table become one continuous string.

    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:

      For considerations when using this function with DBCS support see Recording a macro.

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.
Note:
  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.

Parent topic: Host Terminal