Using the Collect instruction |
Use the Collect instruction to begin execution of a collection rule (Rule-Declare-Collection rule type). This rule can execute additional rules of several types, including activities and other collection rules.
Identify the name of a collection rule.
Parameter |
Description |
(entered in the Method field) |
Type |
Pass current parameter page? |
Select to cause the current activity's parameter page to be passed to (shared with) the collection rule, which can alter its contents in any way. Clear to use the array that appears below the checkbox to pass parameters to the called collection rule. If you select this box, the resulting parameter page remains available to the calling activity after the return. This capability is sometimes known as call-by-reference. If you select this box, make sure that input parameter values needed by the collection rule are present on the parameter page before the Collect instruction executes. |
Value |
If you did not select the Pass current parameter page? box, complete values for parameters of the collection rule. Enter literal or property references for parameters. An asteriskindicates a required parameter. The system creates a parameter page for the collection that is separate from the calling activity's parameter page. The collection's parameter page is destroyed when this method completes. |
The system uses rule resolution to locate the collection rule identified in the Method field.
It sets values for the properties in the Preset Property Values array of the Preamble and Stop tab.
It evaluates the stop conditions on the Preamble and Stop tab for the first time. If any when condition rules listed on that tab evaluates to true, the associated activity executes and all the processing for this collection rule ends.
Thereafter, processing continues in two phases:
In the first phase, the system creates a list of candidate steps to be executed, resolving any rows of the Collection tab with Another Collection
or List View
as the Execute field. Rules of these types can cause additional rules to be appended to the bottom of the list of candidate rules.
Steps execute from top to bottom to assemble this list. For steps with Another Collection
in the Execute field, preconditions are evaluated. Rules for the called collection are included in the list only for steps with no precondition, or steps with preconditions that evaluate to true. Preconditions for other steps are ignored during this phase.
At the end of this phase, no candidate step contains Another Collection
or List View
in the Execute field; all such rows are expanded.
In the second phase, steps assembled in the first phase are evaluated in sequence, subject to preconditions and stop conditions. Preconditions are tested, and rules are executed only for rows that contain no precondition or a precondition that evaluates to true. Stop conditions (on the Preamble and Stop tab) are re-executed again for each row; any stop condition that evaluates to true causes the Collect instruction to end.
When all candidate steps are evaluated, the Collect instruction ends.
Use the Tracer to debug Collect instructions. In the Event Types to Trace area of the Trace Options form, select the Collections checkbox. Ensure that the RuleSets containing the collection rules are also checked.
To log execution of Collect instructions, select the Save Execution Information? checkbox on the Preamble and Stop tab of the collection rule. See More about Collection rules.
If the Execute field for a step indicates that a Declare Expression rule is to be executed, execution of that Declare Expression rule can (through forward chaining) cause other Declare Expression rules (with When applied by a Rule Collection
in the Calculate Value field) to execute. However, Declare Expression rules with this value in the Calculate Value field are never evaluated more than once per step. Declare Expression rules with other values in the Calculate Value field execute normally.
This method updates the pxMethodStatus property only if it fails. See How to test method results using a transition.
About Collection rules |