Business Process and Data Transformation Language Reference
<call>
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Send a request to a business operation, or to another business process.
Synopsis
<call name="Call" target="MyApp.MyOperation" async="1">
  <request type="MyApp.Request">
    ...
  </request>
  <response type="MyApp.Response">
    ...
  </response>
</call>
Details
Attributes are required unless otherwise indicated in the table description.
Attribute or Element Description Value
name attribute 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
target attribute 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
async attribute 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)
timeout attribute 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.”  
<annotation> element
<request> element Required. Specifies the type (class name) of the request to send.  
<response> element Optional. Specifies the type (class name) of the response to return. If omitted, no response is returned from this <call>.  
Description
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:
The <call> element has the child elements <request> and <response> 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 or response variables in the business process execution context.
Note:
There is detailed information about the business process execution context in documentation of the <assign> element. Also see Business Process Execution Context in the chapter “About BPL Processes” of Developing BPL Processes.
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).
The following example sends an synchronous Ens.StringRequest request to the Get Weather Report business operation:
<call name='Get Weather Report' target='Get Weather Report' async='0' >
<request type='Ens.StringRequest' >
<assign property="callrequest.StringValue" value="context.Location" action="set" />
</request>
<response type='Demo.ZenService.Msg.WeatherOperationResponse' >
<assign property="context.OperationReport" value="callresponse" action="set" />
</response>
</call>
The following example uses the <call> element to send an asynchronous MyApp.SalaryRequest request to the MyApp.PayrollApp business operation:
<call name="FindSalary" target="MyApp.PayrollApp" async="1">
  <request type="MyApp.SalaryRequest">
    <assign property="callrequest.Name" value="request.Name" />
    <assign property="callrequest.SSN" value="request.SSN" />
  </request>
  <response type="MyApp.SalaryResponse">
    <assign property="context.Salary" value="callresponse.Salary" />
  </response>
</call>
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, request, callrequest, 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.
Variable Purpose
callrequest 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.
callresponse 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.
context Throughout the business process, the context object serves as a general-purpose container for any business process data that needs to be persistent.
request 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.
response 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 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 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">
synctimedout 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:
  • If 0, no call timed out. All the calls had time to complete. This is also the value if the <sync> activity had no timeout set.
  • If 1, at least one call timed out. This means not all <call> activities completed before the timeout.
  • If 2, at least one call was interrupted before it could complete.
Generally you test synctimedout for status and then retrieve the responses from completed calls out of the syncresponses collection.
Caution:
Like all other execution context variable names, status is a reserved word in BPL; do not use it except as described in this table.
Indirection in the name or target Attributes (Accessing Context Variables)
The values of the name or target 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:
<sequence>
  <while condition='...'>
      <call name="A" async="1" />
   </while>
  ...
  <sync calls="A" type="all" timeout="3600"/>
</sequence>
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:
  1. 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 
  2. Set the Name of the <call> equal to this variable.
  3. Create a string containing all the <call> names, comma-separated, i.e.: "A1,A2,A3,A4,A5". Save that in a separate variable, context.allCallNames, in the example below.
  4. Set the calls attribute of the <sync> equal to the variable containing the list of calls.
<sequence>
  <while condition='...'>
      .... code here to set up callname and allCallNames ...
      <call name="@context.callname" async="1" />
   </while>
  ...
  <sync calls="@context.allCallNames" type="all" timeout="3600"/>
</sequence> 
See Also
<assign>, <code>, <reply>, <sequence>, and <sync>