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: - Click Add new variable in the upper pane
of the window to create a new variable and add it to the list of variables.
- Select the new variable.
- Select the Extract options that you want to use in the lower pane
of the window.
- 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.
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:
- Verify that the Extract options that you have specified are in
fact the ones that you want to use.
- 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.
- 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:
Variable type and cardinality: - If you previously used the variable as a simple variable then
you cannot later reuse it as an array variable, and vice versa (see Type of variable).
- If you previously used the variable with a cardinality of some
value (such as 10) then you cannot later use the variable with a different
cardinality (such as 9 or 11) (see Cardinality).
Table 1. Re-using a variable in an Extract action, or
in an Insert action, or as a loop variable: Variable type and cardinality| Previous use: |
New use cannot be: |
- Extract action:
- Extracting a field into a variable
- Extracting an area into a simple variable
- Insert action
- Loop variable
|
|
|
|
- Extract action:
- Extracting a field into a variable
- Extracting an area into a simple variable
- Insert action
- Loop variable
|
- Extract action:
- Array variable with cardinality == some value N
|
- Extract action:
- Array variable with cardinality !=N
|
Maximum Iterations®:- If you previously used the variable for non-iterative data (see Iterative
data and non-iterative data) then you cannot later reuse the
variable for iterative data, and vice-versa.
- If you previously used the variable with a Maximum Iterations of some value (such as 30)
then you cannot later use the variable with a different number of
Maximum Iterations (such
as 29 or 31).
Table 2. Re-using a variable in an Extract action, or
in an Insert action, or as a loop variable: Maximum iterations| Previous use: |
New use cannot be: |
- Extract action, non-iterative data
- Insert action
- Loop variable
|
- Extract action, iterative data
|
- Extract action, iterative data
|
- Extract action, non-iterative data
- Insert action
- Loop variable
|
- Extract action:
- Maximum Iterations ==
some value M
|
|
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 iterationsEx-
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 intov_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.