Tables use the same identification properties as other steps use: Screen Name, Step Description, Task Endpoint, Recognition Rule, and Transition Action. The logging properties; Log User Event and User Event Message Expression are described in the Task and Task Step Property Descriptions topic, as their functionality does not depend on whether they are used in tables.
Other table properties define the table, and all table constants and variables are case-sensitive. When in SELECT mode, variables used in table property expressions will only support screen data (data contained in host or user fields). In UPDATE and UPDATE MULTIPLE mode, the navigation engine will first try to resolve the variable using screen data, and, if unsuccessful, will try to resolve the variable using task data.
This topic contains a list of table properties, constants, and variables, and a short description of each.
To display table properties, select the table under Task Steps. To edit a property, type or select a new value.
| Property |
Description |
| Screen Name |
Displays the name of the host screen associated with this step. You can change the name to something more meaningful; however, be sure to not use any of the reserved words.
If you change the name, the screen name for all other steps associated with the same screen will also be updated. You cannot use the same name for different screens within the same task.
Screen names cannot contain spaces; they can contain only the following characters: letters, numbers, the underscore (_), and the dollar sign ($). |
| Step Description |
Provides a description of the step. Adding information to this property is optional. |
| Task Endpoint |
Indicates whether or not this table step has been marked as the task endpoint. Values are true and false. |
| Recognition Rule |
The unique expression used to identify the screen associated with this step. |
| Transition Action |
The keys that navigate from the current step to the destination step. If your task contains a single step, then the value is None. Click the Transition Action Value field for a drop down list of all possible transition actions, including IBM AID keys and other special actions. Unisys and VT AID keys are not included in the drop down list. |
| Table Name |
By default, tables are named by consecutive number as they are created (Table1, Table2, and so on). You can change the name to something more meaningful. |
| Table Start Point (column, row) |
The location on the screen that the table starts (upper left). |
| Table End Point (column, row) |
The location on the screen that the table ends (lower right). In the user interface, the Table Start Point and the Table End Point must be different. If you need them to be the same, you'll have to modify your project's NavMap directly. |
| Table Row Offset Expression |
An expression used to locate the first record in a table. Use this expression to define the location of the first record when the record appears somewhere after the beginning of the table, for example, after a specified string. This expression should evaluate to an integer. |
| Table Height Expression |
An expression used to locate the last record in a table. The default is TABLE_HEIGHT, which is equivalent to the entire height of the table.
Example:
If the page has the table-end-marker (meaning it is the last page), then the table ends one line before the table-end-marker. For all other pages, the table ends at row 22.
The two occurrences of table-end-marker in the expression can be different. One value indicates the last page; the other indicates the location of the last row.
IF((screenname.STARTROW('table-end-marker'))
!= ( -(1)), (screenname.STARTROW('table-end-marker'))
- 1, 22) |
| Next Page Inputs |
The keystrokes used to go to the next screen of the table. Click under Value to display the Next Page Inputs dialog box, in which you can add available inputs and modify the values of inputs. For a list of the action keys available for use when editing this field, see AID Keys.
 |
Task Builder contains a translator that formats all AID key designations. It is important that you enter the AID key in the correct format, for example {F8}. If you enter an 8 in the Next Page Input value, the translator will correctly read {F8}. However, if you enter F8, the translator reads F{F8}, which is an invalid command. By correctly entering the AID key, you will avoid navigation errors. |
|
| Last Page Rule |
The rule that detects the last page of the table. The default is True, which defines a one screen table. When you need to navigate through multiple screens, the rule will be more complex, such as "HostField9 like 'End'" or not("HostField2 like '*MORE*'").
To define a rule based on a value in the table, use the CURRENT_LINE constant to specify the value. CURRENT_LINE will walk through each row in the table until the specified value is reached. Use caution when using user fields for evaluating expressions, as they are fixed, not relative fields. Thus, only the area defined by the user field specification is examined.
| Sample Rules and Descriptions |
screenname.STRINGAT(22, 60, 20) like
'*THIS IS LAST PAGE*'
The last page is detected when a specified string is found (or not found) in the specified location. |
TRIM(screenname.STRINGAT(2,1,21,80)) == ''
Sometimes the end of table can be detected when the next page input results in an empty table. You can specify a rule that checks for an empty table. In this example, coordinates (2, 1, 21, 80) are the table boundaries. The built-in method TRIM strips the leading and trailing spaces, leaving an empty string if the rectangle region has only spaces. |
screenname.STARTROW('End of File') != -1
In this example, the last page marker is not at a specified location. You can specify a rule that looks for a particular string anywhere on the screen. |
userCURRENT == userLAST
You can specify a rule that looks for fields outside the table, to specify the current page and the last page index. Create user fields around these two quantities (user field CURRENT and LAST). The rule is as shown.
Alternatively, use the built-in method INTEGERAT() instead of defining user fields. |
|
Take care to verify that your Last Page Rule evaluates to true. If it does not, and you are working with a table that contains repeating records, then an infinite loop may be created. You will need to close Task Builder to escape the loop. |
|
| Record Width (columns) |
The number of characters in each record in a row. There can be more than one column of records in a table. |
| Record Height (rows) |
The number of rows in each record. A record can span more than one row. The total height of the table in rows must be evenly divisible by the value for Record Height. |
| Column Spacing (columns) |
The number of spaces between the columns of data. |
| Table Action |
Choose SELECT, UPDATE, or UPDATE MULTIPLE from the drop down list. The property is set to SELECT by default.
SELECT gets existing data from the field, while UPDATE adds the value set in the Set Fields property to the field. For example, with Table Action set to UPDATE and the Set Fields property set to "cmd='S'", the appropriate field is updated with an "S". Only the first row that matches (where the Where rule evaluates to true) is updated.
The UPDATE MULTIPLE property functions in the same manner as the UPDATE property, but updates multiple table rows instead of merely the first row of data.
The INSERT property is used to populate tables with data. Multiple records can be inserted into a table by defining task inputs using the new data type, Delimited String Array. Task inputs of this type must be formatted as a list of values separated by a delimiter. If multiple delimited string arrays are used, then the arrays should agree in size.
- Create your table, defining all fields and necessary rules.
- Change the Table Action property to INSERT.
- Create a task input for every field in the table, using the New Task Input option from the Task menu.
- In the Task Input property page, change the Data Type property to Delimited String Array.
- You can change the Delimiter property from a comma (the default) to a string of any length. This will be necessary if an individual value in the array can contain a comma.
- In the Set Field table property, map each field in the table to the matching task input that you defined in step 3. When using INSERT, fields must always be associated with task inputs of type Delimited String Array, even if only one set of values are provided.
When all records have been inserted, table processing will automatically stop. Therefore, when a table INSERT spans multiple pages, simply set the Last Page Rule to false.
Note that host fields are always cleared before data is inserted, even when empty values are specified. |
| Set Fields |
The Set Fields property is enabled when Table Action is set to Update. See the Table Action property for more information. |
| Requested Fields |
Displays the user fields to be returned in a record. Click under Value to display the Requested Fields dialog box, in which you can add the user fields needed to extract data from the table. Regardless of the table level (detail tables) at which a user field is defined, it is always added to the table properties for the highest level table. |
| Where Rule |
Define a rule to filter the records returned for a table. The Where rule evaluates to true or false. By default, all records are selected.
Often, the user will not be interested in all the records of a table. You can define a rule that extracts only records that satisfy some constraints.
Example:
Field1 like 'SMITH'— where Field1 is a user field containing last names. This rule would return all records containing the last name of 'Smith'.
This is similar to the SQL SELECT statement WHERE clause.
|
If the variable USER_WHERE is added to the Where Rule, you can further filter the records that are returned for a table.
Example:
Where:
Where Rule = UserField2 like 'd*'
- and -
USER_WHERE variable = UserField23 like 'do*',
then UserField2 like 'd*' AND UserField23 like 'do*' becomes the new Where rule, returning all records where user field 2 begins with ”d” and user field 23 begins with ”do”. |
The Where Rule must be a boolean expression and must include a table entity (the table itself or a table field). |
| Detail Screens |
Detail screens present very long records in more than one level. The first level of the table displays only the first level of fields for each record. When a record is selected, more fields can be shown in a separate screen. The host handles the communication between records and specific detail screens, but your table properties must include a list of the detail screens associated with the table to provide the path information. |
| Detail Screen Inputs |
Click under Value to display the Detail Screen Inputs dialog box, in which you can specify the AID keys and inputs required to display the screen that includes the next level detail table. Inputs can include both user fields and unprotected host fields. For a list of the action keys available for use when editing this field, see AID Keys.
Cursor-based path: A table screen to detail screen path is cursor-based if the action to go to the detail screen involves putting the cursor in the record and invoking an AID key.
Command-based path: A table screen to detail screen path is command-based if the user has to type a command in one of the table fields.
AIDKey-based path: A table screen to detail screen path is AIDKey-based if the user has to type an AIDKey. For example, to go to the detail of first record the user has to press PF1, to go to the detail of the second PF2, and so on. Task Builder records only the first instance of the AIDKey; PF1 in our example. The recorded path input looks like: AIDKEY: '@1'.
To use this type of path navigation, make a user field around where the Fkey is specified on the first record and call it, for example,Ffield. The detail table action would then be: Fkey(Ffield). For more information on the FKey function, see Using Functions to Create Expressions. |
Task Endpoint Action table properties are the same properties used for other task steps. For detailed instructions on using Task Endpoint Action, User Return Code Expression, and User Message Expression, see Task and Task Step Property Descriptions.
Table constant values are valid for these three table property fields:
Table Row Offset Expression, Table Height Expression, and Last Page Rule. They do not work with other table properties.
When a table is defined, two inputs are added to the task step; USER_WHERE and USER_TERMINATE. These inputs cannot be deleted from the Task Step tree, but both their names and values can be edited in the Step Properties pane. From the Task Step tree, choose the variable you want to edit.
You can expose one, or both, to users as task inputs when you create the task. The USER_WHERE expression is added to the Where Rule and will further filter the records returned by the table.
| Functions |
Description |
Result Type |
Used In |
| STARTROW(searchStr, count) |
Returns the start row of the given string. The string can contain wildcard chars such as '*'. Arg 'count' specifies the number of times the string must be matched. |
Integer |
Specify Start, End Row Rule for Relative Fields, List Tables, and so on. |
| ENDROW(searchStr, count) |
Returns the end row of the given string. The string can contain wildcard chars such as '*'. Arg 'count' specifies the number of times the string must be matched. |
Integer |
Specify Start, End Row Rule for Relative Fields, List Tables, and so on. |
| STARTCOL(searchStr, count) |
Returns the start col of the given string. The string can contain wildcard chars such as '*'. Arg 'count' specifies the number of times the string must be matched. |
Integer |
Specify Start, End Col Rule for Relative Fields. |
| ENDCOL(searchStr, count) |
Returns the end col of the given string. The string can contain wildcard chars such as '*'. Arg 'count' specifies the number of times the string must be matched. |
Integer |
Specify Start, End Col Rule for Relative Fields. |
Tables can contain either fixed length or variable length records. Each fixed length record is the same physical size, which is determined at design-time. Variable length records, on the other hand, can vary in physical size. The size is determined at run-time and by the contents contained within the field.
Below are typical examples of expressions that could be used to create and define tables containing both types of records.
