Send a request to a business operation, or to another business process.
<call name="Call" target="MyApp.MyOperation" async="1"> <request type="MyApp.Request"> ... </request> <response type="MyApp.Response"> ... </response> </call>
Attributes are required unless otherwise indicated in the table description.
|Attribute or Element
||Required. The name of the <call> element; provide a literal string, or by using the @ indirection operator to refer to the value of a context variable.
If you wish to use a <sync>
element to retrieve responses from asynchronous calls, refer to them using this name
|A string of 1 to 255 characters
||Required. The configured name of the business operation or business process to which the request is being sent. Provide this value as a literal string, or by using the @ indirection operator to refer to the value of a context variable.
||A string of one or more characters
||Required. Specifies the type of request to make. If 1 (true), the request is asynchronous. If 0 (false), the request is synchronous.
||1 (true) or 0 (false)
||Optional. Sets a timeout on a synchronous call. The timeout value is used only when the async attribute of the <call> is set to 0 (false). Specifies the time, in seconds, to wait for the response, as an expression that evaluates to an XML xsd:dateTime value.
||A string of one or more characters; for example 2003:10:19T10:10
|disabled, xpos, ypos, xend,yend attributes
||See Common Attributes and Elements.
||Required. Specifies the type (class name) of the request to send.
||Optional. Specifies the type (class name) of the response to return. If omitted, no response is returned from this <call>.
The <call> element sends a request (synchronously or asynchronously) to a business operation or business process. The <call> element has a required attribute, async
, that determines how the request is made:
is 0 (or False), the request is made synchronously; the business process waits until it receives a response before continuing execution.
A <call> element with async='False'
and a <response> block defined suspends execution of its business process thread until the called operation completes.
A <call> element with async='False'
but with no
<response> block defined behaves as if async='True'
. If you want to send a synchronous request but do not require a response, create a non-functioning <response> block so that the <call> waits for the target host to finish before continuing execution.
is 1 (or True), the request is made asynchronously; the business process continues to execute after making the request. The business process can later receive the responses from several asynchronous calls by providing a <sync>
element that specifies a list of the <call> elements for which it is waiting. For details, see the <sync>
topic later in this book.
The <call> element has the child elements <request>
which identify the class of request and response objects to use in making the call. Either element can contain one or more <assign>
elements. In the <request> element, <assign> elements are used to fill in the properties of the request object used for the call. The <response> element uses <assign> elements when it needs to move the properties of the resulting response object to a new location, such as the context
variables in the business process execution context.
In the case of an asynchronous request, the <assign> elements within the body of the <response> element are executed when the corresponding request is received. There is no guarantee when this will occur, so a business process will typically use the <sync>
element to wait for an asynchronous response. Note that if a response is not received within the timeout
period specified by the <sync> element, then the assignments defined by the corresponding <response> block will not be executed, and the response itself will be marked with a status of Discarded.
If the call is synchronous, an optional timeout can be specified using the timeout
attribute on the <call> element itself. This attribute cannot be used for asynchronous calls. If the <call> element has async
set to 1 (true) then the only way to set a timeout period is to use the timeout
attribute on the <sync>
element that is being used to collect the asynchronous response(s).
<call name='Get Weather Report' target='Get Weather Report' async='0' >
<request type='Ens.StringRequest' >
<assign property="callrequest.StringValue" value="context.Location" action="set" />
<response type='Demo.ZenService.Msg.WeatherOperationResponse' >
<assign property="context.OperationReport" value="callresponse" action="set" />
<call name="FindSalary" target="MyApp.PayrollApp" async="1">
<assign property="callrequest.Name" value="request.Name" />
<assign property="callrequest.SSN" value="request.SSN" />
<assign property="context.Salary" value="callresponse.Salary" />
Whenever a <call> element is executed, the BPL engine inserts the name
of the <call> element into the message header so that it is visible in later Message Browser and Visual Trace displays.
Use of the <assign> Element
The above example includes <assign>
elements that manipulate properties in the variables in the business process execution context such as context
, and callresponse
. While many details concerning these variables are found in the documentation for the <assign>
element, the following table describes the execution context variables as they relate to the <call> activity:
The <call> element can refer to the following variables and their properties. Do not use variables not listed here.
||A <call> element contains a <request> element that identifies the type of message that will be sent to the target. If this message type has input parameters, the <request> element must provide <assign> elements that assign values to properties in the callrequest object. These properties must match the input parameters for the message type. After the <request> completes, the callrequest object goes out of scope.
||If the request message type has a corresponding response message type, the <call> element contains a <response> element. When the response arrives, control passes to the <response> element. The output parameters from the response message become properties of the callresponse object. Since callresponse only has meaning inside the <response> element, to preserve these values the <response> element must provide <assign> elements that assign callresponse values to properties of other, more permanent objects in the business process execution context, usually context or response.
||Throughout the business process, the context object serves as a general-purpose container for any business process data that needs to be persistent.
||Throughout the business process, the request object contains the original properties that were sent to the business process as parameters of the request that instantiated it.
||The response object retains its scope throughout the business process. It contains the properties that are expected to be returned to the caller as output parameters of this business process. Whatever is inside the response object, when a business process completes or exits, will be interpreted as the return values of the business process.
||status is a %Status value that indicates success or failure. When a BPL business process starts up, status is automatically assigned a value indicating success. As the BPL business process runs, if at any time status acquires a failure value, the business process immediately exits and writes the corresponding text message to the Event Log. status automatically receives the returned %Status value returned from any <call> activity, without any special statements in the BPL code. Thus, if any <call> activity fails, the BPL business process immediately exits and writes an Event Log entry.
||syncresponses is a collection of response objects, keyed by the names of the <call> activities being synchronized. Only completed calls are represented. You can retrieve a response from syncresponses only after a <sync> and before the end of the current <sequence>. Do so using the syntax syncresponses.GetAt("MyName") where the relevant call was defined as <call name="MyName">
||The synctimedout value is an integer. synctimedout indicates the outcome of a <sync> activity after several calls. You can test the value of synctimedout after the <sync> and before the end of the <sequence> that contains the calls and <sync>. synctimedout has one of three values:
Generally you test synctimedout
for status and then retrieve the responses from completed calls out of the syncresponses
Like all other execution context variable names, status
is a reserved word in BPL; do not use it except as described in this table.
The values of the name
attributes are strings. The name
identifies the call and may be referenced in a later <sync>
element. The target
is the configured name of the business operation or business process to which the request is being sent. Either of these strings can be a literal value:
<call name="Call" target="MyApp.MyOperation" async="1">
Or the @ indirection operator can be used to access the value of a context variable that contains the appropriate string:
<call name="@context.nextCallName" target="@context.nextBusinessHost" async="1">
Using Multiple Asynchronous <calls> in a Loop, Followed by a <sync>
This section describes how to use multiple asynchronous <calls> in a loop, followed by a <sync>.
When a BPL makes a <call> it makes note of the name of the call; in the <sync>, you must specify that same name to designate which pending request to wait for. In some scenarios, you have multiple asynchronous calls in a loop, as in this example:
<call name="A" async="1" />
<sync calls="A" type="all" timeout="3600"/>
Because the BPL tracks which call to wait for by the call name, the sync completes as soon as the first
response comes in. If you want the sync to wait until all such calls are completed, it is necessary to generate a set of unique call names and then use that list of names. Here is a way to do so:
Create a context variable containing a string which changes for each call by adding a numeric iterator (i
in the example below). Before the call, initialize this variable as in the following example:
set context.callname = "A" _ context.i
Set the Name
of the <call> equal to this variable.
Set the calls
attribute of the <sync> equal to the variable containing the list of calls.
.... code here to set up callname and allCallNames ...
<call name="@context.callname" async="1" />
<sync calls="@context.allCallNames" type="all" timeout="3600"/>
© 1997-2019 InterSystems Corporation, Cambridge, MA