Rational Developer for System z

Select Variable window: Selecting an Extract variable

This topic describes how to select a variable for an Extract action from the list of variables in the Select Variable window.
Tip: To quickly create an Extract action with a properly configured variable:
  1. Click Add new variable in the upper pane of the window to create a new variable and add it to the list of variables.
  2. Select the new variable.
  3. Select the Extract options that you want to use in the lower pane of the window.
  4. Click OK.
The window creates the Extract action and configures the variable to match the storage requirements of the specified Extract options (see Automatic configuration of the selected variable).
This topic includes the following subtopics:

The list of available variables

The list of variables available for a new Extract action is displayed in the upper pane of the Select Variable window.

The list includes all the variables in the variable message of the current flow (the flow being recorded) that can possibly be used with the new Extract action (depending on the Extract options that you specify).
Note: The list includes any String variable that you have used previously in the current flow as an Insert variable, an Extract variable, or a loop variable.
From this list you ultimately need to select a variable whose characteristics match the storage requirements of the Extract options that you specify in the lower pane of the window (see The characteristics of the variable must match the Extract options). You can do this in either of two ways:
The relevant characteristics of an Extract variable are:
  • The type of the variable (simple variable or array variable -- see Type of variable).
  • The cardinality of the variable, displayed in the second column of the upper pane (see Cardinality).
  • The maximum iterations value of the variable, displayed in a third column of the upper pane if you are currently recording a loop (see Maximum iterations). Not all variables have this characteristic.

These purpose of having these characteristics is to simplify the relative complexity of the underlying data structures of the variable.

Automatic configuration of the selected variable

For automatic configuration to occur the variable selected in the upper pane of the window must have the following characteristics:
  • It must be a simple variable (that is, not an array variable or a complex data structure); and
  • It must not have been used previously in the flow as the variable for an Extract action, an Insert action, or a loop variable.

If these conditions are met then when you click OK in the Select Variable window the window automatically configures the selected variable to match the storage requirements of the Extract options that you specified in the lower pane of the window (see Tip: To quickly create an Extract action with a properly configured variable).

The automatic configuration of a variable consists of modifying (if necessary) the characteristics of the selected variable, including the type of variable (simple or array), the cardinality value, and the maximum iterations value.

For example, suppose that the Extract options specify that the text is to be read from a rectangular area of the application screen having a size of 5 rows by 30 columns, and that the text is to be stored into an array variable, using a separate instance of the variable for each iteration of a loop, with a maximum of 20 loop iterations. To accommodate these requirements the variable is automatically configured to have the following properties:
  • Type of data: An array variable
  • Cardinality: 5
  • Maximum iterations: 20.

Once a variable is configured for a particular Extract action the configuration is permanent. However, you can reuse the variable with other Extract actions, so long as the characteristics of the variable match the requirements of the specified Extract options.

Note: In automatic configuration the characteristics of the variable -- type of variable, cardinality, and maximum iterations -- are set by changing the underlying data type and size of the variable. In the above example the original simple variable is a String variable. The configuration is accomplished by replacing the original String variable with an array of arrays of Strings. The outer array has 20 elements (maximum iterations) and each of its elements is an array of 5 String elements (cardinality). See Viewing the data structure of an Extract variable.

The characteristics of the variable must match the Extract options

The Select Variable window requires that the characteristics of the selected variable must exactly match the storage requirements of the specified Extract options. If this requirement is not met then the window displays an error message describing the mismatch.

Important: This rule does not apply if you use the automatic configuration feature of the Select Variable window on a new variable, or on a variable that you have not previously used in an Extract action, or an Insert action, or as a loop variable in the same flow. The automatic configuration sets the characteristics of the variable to match the specified Extract options.

The characteristics of the selected variable include its type (see Type of variable), its cardinality (see Cardinality), and its maximum iterations value if any (see Maximum iterations).

Here are some examples of this type of error:
  • Error in the variable type: The selected variable is a simple variable (cardinality = 1) and the Extract options require an array variable (cardinality > 1), or vice versa.
  • Error in cardinality: The cardinality of a selected array variable is not equal to the number of rows in the rectangular area to be extracted.
  • Error with maximum iterations: The maximum iterations value of the variable is not equal to the value specified in the Maximum number of iterations field.

For a more detailed description see Reuse of a previously configured variable.

To resolve this type of error:
  1. Verify that the Extract options that you have specified are in fact the ones that you want to use.
  2. If you want to reuse a previously configured variable select a variable from the list whose characteristics match the storage requirements of the Extract options.
  3. Optionally, select an existing or new simple variable and let the window automatically configure the variable with the proper characteristics see Automatic configuration of the selected variable).

Reuse of a previously configured variable:

The Select Variable window protects a configured variable from being reconfigured into a different type of variable later on in the same flow.

Therefore some restrictions apply when you select a variable in the Select Variable window to use either in an Insert action, or in an Extract action, or as a loop variable, and you have previously used the variable for one of the same three purposes in the same flow:

Length of variables: The Select Variable window does not require you to specify the number of characters that a simple variable (a String variable) or that an element of an array (each element is a String) can contain.

Creating a new variable for the list

You can create a new variable by clicking Add new variable and typing a variable name. The window creates a new simple variable (actually a new String variable -- see Type of variable) and adds it to the list of available variables.

If a new variable or any previously unused simple variable is the selected variable when you click OK then the window automatically configures this variable with the characteristics required by the selected Extract options (see Automatic configuration of the selected variable).

Type of variable

In the Select Variable window the type of a variable is either simple (that is, not an array and not a complex data structure) or array.

A simple variable is implemented as a String variable. An array variable is implemented as an array of Strings (see Table 3).

The cardinality value of a variable indicates whether the type of the variable is simple or array (again, see Table 3).

Table 3. Type of variable
Type of variable: Implemented as: Cardinality:
Simple A String variable 1
Array An array of Strings >1

For more information about the underlying data structure of Extract variables see Viewing the data structure of an Extract variable.

Cardinality

The second column of the Select Variable window displays the Cardinality value of each variable.

The cardinality of a variable is significant when you want the Extract action to read the text displayed in a rectangular area of the application screen and to store the text into an array variable. (Each row of the extracted text is written into a successive element of the array starting with element [1].)

The cardinality value of an array variable indicates the maximum number of rows of text that the array variable can contain, or what is the same thing, the number of array elements in the array variable. Examples:
  • An array variable with a cardinality of 10 has 10 elements and can hold 10 rows of text from an Extract action.
  • An array variable with a cardinality of 24 has 24 elements and can hold 24 rows of text from an Extract action.

The window displays an error message if the selected variable has a cardinality (for example, 10) that is not exactly equal to the number of rows of text (such as 9 or 11) in the rectangular area that you specify (see Automatic configuration of the selected variable).

A secondary use of the cardinality value of a variable is to indicate whether the variable is a simple variable or an array variable (see Table 3).

Maximum iterations

The third column of the Select Variable window displays the Maximum Iterations value of each variable, if the variable possesses this characteristic.

This column is displayed only when you are recording a loop.

The maximum iterations value of a variable is significant when you select the check box Extract data every iteration of the loop in the lower pane of the window (see Extract data every iteration of the loop). Selecting this check box indicates that in each iteration of the loop, when the Extract action is performed, the Extract action writes the extracted text into a separate instance of the specified variable, rather than into a single instance of the specified variable (see Maximum number of iterations).

The window displays an error message if the selected variable has a maximum iterations value that is not exactly equal to the value specified in Maximum number of iterations field of the window (see The characteristics of the variable must match the Extract options and Maximum number of iterations).

Viewing the data structure of an Extract variable

The data structures of the various types of Extract variables are described in:
Also you can view or modify the actual data structure of a variable in the following contexts:
  • The message editor allows you to view, modify, and create variables in the variable message of the flow.
  • The mapping editor allows you to graphically view and modify mappings of data between variables in the mapping routines of the flow. Mappings are used to implement Extract actions, among other uses (see Working with mappings and transforms in the mapping editor).
  • Also in the mapping editor, the Content Assist feature of the Condition input area enumerates in ESQL all the accessible fields of the source and target variables (see Specifying a condition for a mapping).

Data structure of Extract variables: Non-iterative case

This subtopic describes the data structure of Extract variables in the "non-iterative" case, that is when the check box Extract data every iteration of the loop is cleared or absent in the Select Variable window. In this scenario:
  • The Extract action is not within a loop recording; or
  • The Extract action is within a loop recording but stores the extracted text into the same instance of the Extract variable in each iteration of the loop.

Table 4 describes the data structures used in this case, depending on the Extract options you choose:

Table 4. Data structure of Extract variables: Non-iterative case
Extract from field or area: Type of target variable: Cardinality: Enumeration of the elements of the variable using ESQL (examples): Text extracted by the Extract action (examples):
Field Simple variable (String) 1 v_Flow.strName 'ABC Supplies'
Area Simple variable (String) 1 v_Flow.strList

'ABC Supplies,FGH Papers  ,
JKL Foods   ,NOP Metals  '

(with a comma as the delimiter between rows)

Array variable (Array of Strings) 4 (in this example)

v_Flow.arrNames[1]
v_Flow.arrNames[2]
v_Flow.arrNames[3]
v_Flow.arrNames[4]

'ABC Supplies'
'FGH Papers  '
'JKL Foods   '
'NOP Metals  '

As the table illustrates, the various storage requirements for an Extract action in the non-iterative case are as follows:
  • Text that is extracted from a field must be stored into a simple variable:
    • The simple variable is a String variable:
      • In general a simple variable is a scalar variable (not an array or a complex data structure).
      • For an Extract action a simple variable must be a String variable. The Select Variable window does not display simple variables that are not String variables.
      • A new variable that is created by clicking Add new variable is a String variable.
    • The cardinality of a simple variable is always 1.
  • Text that is extracted from a rectangular area of the application screen must be stored either into a simple variable or into an array variable:
    • A simple variable:
      • As is the case when the extracted text is from a field, a simple variable is a String variable.
      • See the comments on a simple variable above under the description of text extracted from a field.
      • The text from the rectangular area is stored as a single string into the String variable.
    • An array variable:
      • An array variable is an array of Strings.
      • Each row of text from the rectangular area of the application screen is stored into an element of the array variable starting with element [1].
      • Cardinality:
        • The cardinality value of the array variable is the number of array elements that the array variable contains.
        • The cardinality value of the array variable must be exactly the same as the number of rows of text in the rectangular area.

Data structure of Extract variables: Iterative case

This subtopic describes the data structure of Extract variables in the "iterative" case, that is when the check box Extract data every iteration of the loop is selected in the Select Variable window. In this scenario the Extract action is within a loop recording and is configured to store the extracted text into a separate instance of the Extract variable in each iteration of the loop.

Table 5 describes the data structures used in this case, depending on the Extract options you choose. Notice in the last column that the text examples show only the text extracted in the first iteration of the loop:

Table 5. Options with the Extract action: Iterative case, assuming a maximum of 3 loop iterations

Ex-
tract
type:

Type of target variable:

Cardin
-ality:

Maximum iterations: Enumeration of the elements of the variable using ESQL (examples): Text extracted in the first iteration of the loop (examples):
Field An element in an array of String variables 1 3 (example)

v_Flow.cd_LOOP[1].cd_DATA
v_Flow.cd_LOOP[2].cd_DATA
v_Flow.cd_LOOP[3].cd_DATA

Text extracted in the first iteration of the loop and stored into the first array element:

'ABC Supplies'

stored into:

v_Flow.cd_LOOP[1].cd_DATA

Area An element in an array of String variables 1 3 (example)

v_Flow.cd.cd_LOOP[1].cd_DATA
v_Flow.cd.cd_LOOP[2].cd_DATA
v_Flow.cd.cd_LOOP[3].cd_DATA

Text extracted in the first iteration of the loop and stored into the first array element:

'ABC Supplies,FGH Papers  ,
JKL Foods   ,NOP Metals  '

(with a comma as the delimiter between rows) stored into

v_Flow.cd.cd_LOOP[1].cd_DATA

An array of arrays of Strings 4 (in this example) 3 (example)

v_Flow.cd.cd_LOOP[1].cd_DATA[1]
v_Flow.cd.cd_LOOP[1].cd_DATA[2]
v_Flow.cd.cd_LOOP[1].cd_DATA[3]
v_Flow.cd.cd_LOOP[1].cd_DATA[4]

v_Flow.cd.cd_LOOP[2].cd_DATA[1]
v_Flow.cd.cd_LOOP[2].cd_DATA[2]
v_Flow.cd.cd_LOOP[2].cd_DATA[3]
v_Flow.cd.cd_LOOP[2].cd_DATA[4]

v_Flow.cd.cd_LOOP[3].cd_DATA[1]
v_Flow.cd.cd_LOOP[3].cd_DATA[2]
v_Flow.cd.cd_LOOP[3].cd_DATA[3]
v_Flow.cd.cd_LOOP[3].cd_DATA[4]

Text extracted in the first iteration of the loop and stored into the first array element:

'ABC Supplies'
'FGH Papers  '
'JKL Foods   '
'NOP Metals  '

stored into

v_Flow.cd.cd_LOOP[1].cd_DATA[1]
v_Flow.cd.cd_LOOP[1].cd_DATA[2]
v_Flow.cd.cd_LOOP[1].cd_DATA[3]
v_Flow.cd.cd_LOOP[1].cd_DATA[4]

As the table illustrates, the various storage requirements for an Extract action in the non-iterative case are as follows:
  • For each separate instance of the Extract variable the data structure is the same as it would be in the non-iterative case described in the previous subtopic. That is:
    • Text extracted from a field must be stored into a simple variable (a String variable).
    • Text extracted from a rectangular area must be stored either:
      • Into a simple variable (a String variable) as a single string; or
      • Into an array variable (an array of Strings) having the same number of elements as the number of rows of text in the rectangular area.
    (See Data structure of Extract variables: Non-iterative case.)
  • The Extract variable is an array variable containing all the separate instances as its array elements:
    • For text extracted from a field:
      • The extracted text is the text contained in the field.
      • The array variable is an array of Strings.
      • Each array element is a String containing the text extracted from the field in one iteration of the loop.
    • For text extracted from a rectangular area of the application screen:
      • If the text is stored into a simple variable:
        • The extracted text is a single string of characters containing all the text from the rectangular area.
        • The array variable is an array of Strings.
        • Each array element is a String containing the text extracted from the rectangular area in one iteration of the loop.
      • If the text is stored into an array variable:
        • The extracted text is an array of Strings, each element of the array containing one row of text from the rectangular area.
        • The array variable is an array of arrays of Strings.
        • Each array element is an array of Strings containing the rows of text extracted from the rectangular area in one iteration of the loop.
    • Effect of the maximum number of iterations value of the variable:
      • In every case the maximum number of iterations value of the variable must be the same as the value specified in the Maximum Iterations field of the window.
      • This value is:
        • The number of iterations for which the variable can store instances.
        • The number of elements in the big array.
        • The maximum number of iterations that the loop will be allowed to run at run time.


Feedback