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

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.
  • Text
  • Color
  • Field
  • Extended field
  • DBCS
  • Grid
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.
Note:
  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.