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) |
|
| 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 check box 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.
|
| Value |
An asterisk 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 check box. Ensure that the RuleSets containing the collection rules are also checked.
To log execution of Collect instructions, select the Save Execution Information? check box 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 |
Type 
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.
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.
indicates a required parameter.