callService Method

This topic documents a feature of Binary Behaviors, which are obsolete as of Internet Explorer 10.

Calls a method that is implemented on a Web Service.

Syntax

iCallID = sElementID.sFriendlyName.callService( [oCallHandler], fo, oParam)

Parameters

sElementID Required. The id of the element to which the WebService behavior is attached.
sFriendlyName Required. The friendly name for the Web Service, which is defined by calling the useService method.
oCallHandler Optional. The name of a script callback function that handles the results returned from this instance of the method call.
fo Required. One of the following possible values.
strFuncName
A String representing the name of the remote function being called. The String must be bounded by single or double quotation marks.
objCall
A call object, which has the necessary properties defined to call a remote function.
oParam Required. One or more comma-delimited parameters, which are passed to the method name specified by fo.

Return Value

In the case of asynchronous communication, returns an Integer, which is a unique identifier for the instance of the method call. In the case of synchronous communication, returns a result object.

Remarks

By using this method, the WebService behavior invokes a remote method call on a Web Service.

The callService method invokes asynchronous communication between the WebService behavior and the Web Service by setting the async property to true. The return value of the method is an Integer that identifies the instance of the method call. In this case, use an onresult event handler or callback function to process the returned results.

The callService method invokes synchronous communication between the WebService behavior and the Web Service by setting the async property to false. The return value of the method is a result object.

For an illustration using both synchronous and asynchronous communication between the WebService behavior and the Web Service, see the examples on the call object page.

If oCallHandler is not specified, then an onresult event handler is used to examine the results of the callService. The properties of the event object can be examined to determine if the call was made successfully.

If oCallHandler is specified, then a callback handler function is used to process the results of the method call. The result object is passed to the first parameter of the callback function, so the user specifies the name of the object in the script code. Code samples using each approach are given in Using the WebService Behavior.

Regardless of the type of function used to process the results, the properties exposed to script are similar. If an event handler is used, the syntax used to access result information is event.result. If the callback approach is used, the object name is the name of the first parameter in the callback function declaration. For a comprehensive list of property objects returned by a WebService behavior call, see onresult.

When passing an XmlElement object to a web service using oParam, the XML contained in the XmlElement must contain a single root node. The root node is not returned by the result object. In the following XML data island, BOOKLIST is the root.

<XML ID=myXMLElement>
<?xml version="1.0"?>

<BOOKLIST>
   <BOOK>
      <CODE>16-041</CODE>
      <CATEGORY>HTML</CATEGORY>
      <RELEASE_DATE>1998-03-07</RELEASE_DATE>
      <SALES>127853</SALES>
      <TITLE>Instant HTML</TITLE>
   </BOOK>
   <BOOK>
      <CODE>16-048</CODE>
      <CATEGORY>Scripting</CATEGORY>
      <RELEASE_DATE>1998-04-21</RELEASE_DATE>
      <SALES>375298</SALES>
      <TITLE>Instant JavaScript</TITLE>
   </BOOK>
</BOOKLIST>

</XML>

The following example shows a call to a web service. The element where the WebService Behavior is attached has an id of aaa , and the friendly name for the web service is tst .

var x = myXMLElement.documentElement;   // get the xmlelement object
    aaa.tst.callService(myCallBackFunction,"XmlEcho",x);            

This callback function returns the first child of the BOOKLIST element by asking for the zero element child. You cannot ask for the root or BOOKLIST element because it has no parent element.

function myCallBackFunction(res) {
    if (!res.error) {
        var x = res.value;
        var y = x.selectNodes("BOOKLIST")[0].xml;
        alert(y);
    }else{
        alert(res.errorDetail.string);
    }
}

Example

The following example shows how to call the add method to calculate the sum of two integers.

<script language="JavaScript">
var iCallID;

function init()
{
    service.useService("/services/math.asmx?WSDL","MyMath");
    iCallID = service.MyMath.callService("add",5,6);
}
</script>
<body onload="init()">
<div id="service" style="behavior:url(webservice.htc)">
</div>
</body>

Applies To

WebService

See Also

HTC Reference, Using HTML Components to Implement DHTML Behaviors in Script, onresult, useService, Using DHTML Behaviors, Using the WebService Behavior, About the WebService Behavior