Executing Server Script Remotely

If you have created ASP pages as page objects, you can call methods on those pages remotely — that is, you can execute a method on an ASP page while a client page is loaded in a browser and without navigating away from the client page.

Because you do not leave the client page, its values are preserved and client scripts can continue processing without complex strategies to save values between pages. In the meantime, the server script can execute server-appropriate procedures, such as database lookups. When a procedure is finished, the server can send just the results to the client, rather than reformatting and resending an entire page. This reduces server load.

You can execute server script two ways:

Synchronously Your script calls the remote procedure and waits for it to return. This is useful if you need the results of the remote procedure before you proceed.
Asynchronously Your script makes the call to a remote script, and then continues processing. The page remains available for users to work with. Asynchronous calls are useful in Web applications because a remote procedure can take a long time while the request goes to the server and back.

Making Remote Procedure Calls Synchronously

Remote scripting uses the technology of ASP page objects. The page to be called is an ASP page object on which you have exposed methods. The client page, which can be either an .htm file or .asp file, contains client scripts that call the page object's methods.

To make remote scripting calls from a client page to a server page, you use the page object's execute child object. The execute child object does not return a single value from the method you call. Instead, it returns a call object, which is an object containing return and status information about the called procedure.

The most commonly used property is the call object's return_value property, which contains the single value calculated or looked up by the remote procedure. Other call object properties allow you to get more information about the state of the remote procedure call, as discussed later in this topic.

To make a synchronous remote procedure call

Create a reference on the current page to the page object you want to use. For details, see "Referencing Other Pages" in Extending the Scripting Object Model Across Pages.
In your client script, call the procedure using syntax such as this:
```
pageObject.execute.methodName
```

Note Remote scripting is implemented using script stored in the Script Library. Do not alter the contents of the library, or remote scripting might not work properly.

For example, the following function is called in client script to validate a credit card. To perform the validation, it calls the method validate in the page object poSignIn. The value returned by the remote procedure is available in the return_value property of the call object valid.

<SCRIPT LANGUAGE="JAVASCRIPT">
function checkCreditCard(){
   retObj = poSignIn.execute.validate(txtCC.value);
   if (retObj.return_value == "OK"){
      alert("Accepted");
   }
   else{
      alert("Rejected");
   }
}
</SCRIPT>

Calling Methods Asynchronously

When you call a remote scripting procedure asynchronously, you must include extra processing in the calling script to determine when the remote call has finished. To do this, you specify a callback procedure, which is a function that is called when the remote procedure has finished.

To use a callback function, you create an additional function in the client page to process the results of the remote script. You can optionally also create an error handling process in client script that can be called if the remote script encounters an error condition.

To make an asynchronous remote procedure call

When calling a method using the execute object, include the name of a callback function using syntax such as this:
```
co = PageObject.execute.Method(p1, p2, callBack)
```
where:
co   A call object.
p1, p2   Any parameters required by the called procedure. You can pass as many parameters as required.
callBack   The name of a method that will be called when the remote procedure has finished. When the remote method has finished, it jumps immediately to the process you have specified.

For example, the following illustrates a button whose onclick attribute specifies that it should call a remote procedure for validating a credit card. The call to the remote procedure specifies the function displayResults as its callback.

<BUTTON 
   ID="btnValidate"
   TYPE="button"
   LANGUAGE="JavaScript"
   ONCLICK="poSignIn.execute.validate(txtCC.value, displayResults)">
   "Validate Credit Card"
</BUTTON>

The displayResults function accepts the remote procedure call object as a parameter and tests it to determine whether the credit card was valid.

<SCRIPT LANGUAGE="JavaScript">
function displayResults(retObj)
{
   if (retObj.return_value == "OK"){
      alert ("Your order has been accepted.");
   }
   else{
      alert("Invalid credit card number, please re-enter.");
   }
}
</SCRIPT>

Note You can also use remote scripting calls outside the scope of the page object's execute method. For details, and for more information about remote scripting, see the Microsoft Scripting Web site http://www.microsoft.com/scripting.