Building the Action Diagram › How to Define Logic for Elementary Processes and Procedures › Add Repeating Actions › Add READ EACH Entity Action

Add READ EACH Entity Action

Adding READ EACH entity actions to the Action Diagram is made up of the following subordinate activities:

• Add READ EACH entity action
• Specify desired group view
• Target group view
• Specify sorting of READ results, if desired
• Specify any selection criteria
• Detail properties of a READ EACH statement

A READ EACH entity action retrieves information about multiple entities of a given type that meet specified selection criteria. The results of the READ EACH and its MOVE action can populate a repeating group view.

The DBMS dictates how the entity occurrences and their attribute values are retrieved when the READ EACH is first encountered during an execution. The DBMS does not indicate whether it retrieves data individually or all occurrences at once. The individual case is more common. If you change an entity occurrence after that, the change is not reflected in the next iteration.

Downstream Effects: READ EACH statements always cause a cursor to be used in the DBMS. For DB/2 mainframe batch applications, READ EACH statements can be generated with cursor hold. To access the option, select the Read Each statement. Select the Detail pull-down and the Properties action.

Note: For more information, see the Toolset Help.

The READ EACH action uses the following format:

READ EACH entity-view-list
[TARGETING repeating-group-view-1 [FROM THE BEGINNING]
[UNTIL FULL]]
[AND TARGETING repeating-group-view-1 [FROM THE BEGINNING]
[UNTIL FULL] . . .
[SORTED BY ASCENDING attribute 1] . . .
DESCENDING
[WHERE selection-conditions]
action-statement-list

The first line indicates the READ EACH action and the entity action views(s) being read. Entity-view-list indicates that you can specify multiple entity action views in the READ EACH statement. For a discussion of the advantages of reading multiple views in one READ statement, see the Add READ Entity Action section; the same advantages pertain to READ EACH statements.

The next four lines target the group view. A group view is a collection of entity views, other group views, or both. Only group views can be identified as repeating. The four lines contain optional TARGETING clauses that target repeating group views to be populated each time the READ EACH repeats. The repeating group views may be either local or export views. The TARGETING clause allows you to identify (connect) the repeating group read with the repeating export or local group that may be populated. The clause establishes the sequence in which the occurrences of the entity views within a repeating export or local group are populated. You can add multiple TARGETING clauses to allow multiple repeating group views to be populated simultaneously.

Part of the TARGETING clauses include the FROM THE BEGINNING and UNTIL FULL clauses. The FROM THE BEGINNING clause is useful if multiple READ EACH actions target the same repeating group view. To begin populating the group with the first entity view in the group, specify FROM THE BEGINNING. If you do not specify FROM THE BEGINNING, the group is populated beginning with the current entity view. The UNTIL FULL clause causes the READ EACH to terminate if an attempt is made to exceed the maximum number of occurrences set for the repeating group view.

You specify the order of the READ with two clauses: SORTED BY ASCENDING and SORTED BY DESCENDING. The SORTED BY clause returns entities in a particular sequence based on an attribute value. The ASCENDING clause returns the entities in a low-to-high order. The DESCENDING clause returns the entities in a high-to-low order.

The optional WHERE clause indicates selection conditions used for the READ EACH action. Refer to Specify Selection Conditions for a READ EACH Action.

Action-statement-list indicates a block of actions to occur for each occurrence.

One iteration occurs per distinct combination of entity occurrences that satisfy the selection criteria. One occurrence can be retrieved for more than one iteration if other view(s) in the read list retrieve new occurrences. Every view is populated for every iteration. If any view cannot be populated for a given combination of occurrences, then that combination is rejected (no iteration).

The following examples illustrate READ EACH statements (action-statement-list is not shown):

READ EACH product
WHERE DESIRED product code IS EQUAL TO "GA"
READ EACH product
TARGETING group export FROM THE BEGINNING UNTIL FULL
WHERE code IS EQUAL TO "GA"
customer_order
READ EACH customer order line
SORTED BY customer_orderline_number ascending
WHERE DESIRED CUSTOMER_ORDER_LINE_PART_OF_CURRENT