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.

Parameters

Identify the name of a collection rule.

Parameter	Description
(entered in the Method field)	Type Collect followed by one space and the Purpose — second key part — of a collection rule. At runtime, rule resolution uses the class of the Step Page of this step (or the primary page of the activity, if the Step Page field is blank) to find the collection rule.
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.

Results

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.

Notes

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.

Checking the method status

This method updates the pxMethodStatus property only if it fails. See How to test method results using a transition.

About Collection rules

Methods and instructions by function