Calling another activity

Use the Call instruction to cause the current activity find another specified activity and execute it. When that activity completes, control returns to the calling activity.

The calling activity can provide input parameters to the called activity, or it can share its own parameter page with the called activity, an approach known as call-by-reference.

Optionally, you can identify pages that the called activity will use indirectly, through the prompt mode on the Pages & Classes tab of the calling activity. See Sharing pages between calling and called activities.

The called activity can update the values of parameters marked (on the Parameter tab of the Activity form) as In and also parameters marked as Out. If an Out parameter is a property reference, the value of that property is updated. For details on In and Out properties, see Activity form — Completing the Parameters tab.

Parameters

The Call instruction requires an activity name in the Method field, a checkbox for sharing the parameter page, and optionally a variable number of parameters for the called activity.

Parameter	Description
Activity (in the Method field)	Identify the activity you are calling. Type Call followed by a space and the Activity Name key part of an activity. To locate the activity with rule resolution at runtime, the system uses the class of the step page as the initial Applies To key part, and searches the class hierarchy for an activity of that name. If the Step Page field is blank, the system uses the Applies To key part of this activity as the initial Applies To key part. Optionally, you can identify the Applies To key part of the called activity explicitly, using the format: Call Data-Admin-Operator-ID.Analyze Call MyCo-Finance-Work-Form990.Validate The explicit class format causes rule resolution to bypass all class hierarchy searches — the activity must be present in the specific class identified before the dot. (Other aspects of rule resolution operate normally.) Because use of explicit class names can introduce inflexibility, complicate debugging, and reduce opportunities for rule reuse, avoid this format whenever possible. When you save an activity, CALL steps that use this format cause a rule warning.
Pass current parameter page?	Select to cause the calling activity's parameter page to be passed to (shared with) the called activity, which can alter its contents in any way. Clear to use the array that appears below the checkbox to pass parameters to the called activity. If you select this box, the 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 called activity are present on the parameter page before calling the activity.
Value	If you did not select the Pass current parameter page? box, complete values for parameters of the called activity. Enter literal or property reference values for each parameter that you want to have a value. These icons may appear: — Marks required parameters — Marks input parameters — Marks output parameters No image appears if the parameter is not designated as input or output. Do not use a local variable to hold an output parameter. Do not enter a constant as the value of an output parameter. The system creates a parameter page for the called activity that is separate from the calling activity's parameter page. The called activity's parameter page is destroyed upon return.

Results

The system uses rule resolution to locate the activity. It then constructs or shares a parameter page, and transfers control to the activity.

Sharing pages between calling and called activities

The preferred means for passing a single page from one activity to another is to identify the page in the Step Page field of the calling activity. The called activity receives this page as its primary page.

If you need to pass more than one page, use the indirect page mechanism:

• In the called activity, identify an indirect page by the keyword prompt as the Mode field in the Pages & Classes tab.
• In steps of the called activity, refer to these pages using the syntax promptpagename. No corresponding entry is required in the Parameters tab.
• In the calling activity, pass the additional pages as arguments to the Call instruction that invokes the second activity.
• The value supplied for the prompt page must not be blank and must evaluate to a clipboard page name (top-level or embedded). The keywords primary, top, local, and parent are not valid with prompt pages; the param keyword is valid.

Indirect pages provide a generic way to pass pages not only between activities, but also to other rule types such as list view rules and summary view rules.

An older alternative way to pass pages between activities — using the parameter Data Type of Page — is no longer recommended.

Accessing iteration values in a called activity

If an activity step involving iteration contains a Call instruction, special parameters are added to the parameter page and can be used within the called activity to access iteration details. See Activity Form — Completing the Steps tab — Iteration.

Viewing the call and branch hierarchy

Click the  Show Calls   button on the Steps tab of the Activity form to review the structure of possible call, branch, and Activity-List-Add operations that can occur from the activity. See Activity form — Using the Show Calls display.

Asynchronous execution

As an alternative to the Call instruction, you can use the Queue instruction to execute an activity asynchronously in parallel, in a child requestor.

	indirect page
	Using the Queue instruction to run an activity asynchronously

Methods and instructions by function