One of the nice things about the client-side scripting that we're about to describe is that it is written utilizing JavaScript and Java. As such, it can be used by both Internet Explorer and Netscape browsers. We have tested it as far back as version 4.0 for both of these browsers, but there is no reason that, in the event that you user's have computers from the stone age, earlier browsers wouldn't work as well. Also, if you get the Java components from Microsoft, there is a limitation on the amount of data that can be pushed back and forth. That limit is around 100,000KB. Yes, we've run into that...don't ask. The component that is provided with this example had that limit extended to over 1MB.
Ironically, we'll start our discussion of the scripting that is done on the client side by identifying the files that need to be placed on the server side. The ZIP file link included in the References section to the right contains four files: rs.asp, rs.htm, rsproxy.class and rsproxy.java. In order to get remote scripting to work, these files (actually all but rsproxy.java, the source code for rsproxy.class) need to be resident on the server. We put them into a directory called _ScriptLibrary underneath the virtual directory of the web site. This is the directory that is assumed by the sample code for the rest of this article. However, you can put them whereever you would like, so long as you adjust the code appropriately.
There are two pieces of code that need to be included in the page that runs
on the client. The first of these, shown below, includes the source files necessary
to implement and initialize the functions that call the server, marshall the
parameters and handle the response. It is really the two <SCRIPT>
tags that need to be included. We typically wrap them in a <DIV>
so that it is isolated from the rest of the page.
<div style="display:none">
<script language="Javascript" src="_ScriptLibrary/rs.htm">
</script>
<script language="Javascript">
RSEnableRemoteScripting("_ScriptLibrary")
</script>
</div>
The other piece of client-side code actually makes the call to the server and then processes the response.
<SCRIPT language=JavaScript>
<!--
//=================== Remote script Functions ================
function ExecuteRS(sRsFunction, sParm) {
var results = RSExecute("http://www.tagconsulting.com/test.asp", sRsFunction,
sParm, ReturnRS );
}
function ReturnRS(co) {
if(co.status != 0) {
alert("Unable to execute remote script! Return message:\r\n" + co.message);
} else {
alert(co.return_value);
}
}
//-->
</script>
To start the remote scripting process from the browser, your client-side code would call the ExecuteRS javascript function passing in the function name and the parameter(s). From within ExecuteRS, a call will be made to RSExecute. This is a function that is implemented in rs.htm. The parameters are the URL that contains the remote scripting function (see the next section for how it is implemented), the name of the exposed function that is called within that URL, a list of parameters and the callback function. I did say a list of parameters. You can have as many parameters as you want (within reason...I don't want an e-mail saying that the call failed with 500 parameters and blaming me for not knowing what I'm talking about) between the function name and the callback function. The only criteria is that the number of parameters match the number expected for that function on the server side.
As you might have guessed (with the presence of a callback function and all), this is an asynchronous process. Once the ExecuteRS function has completed, the client side waits for the results. That is done by having the remote scripting process call the specified function (in this case, ReturnRS) when the result has come back. The lone parameter into this function is an object that contains, among other things, the status (did the request succeed or fail) and the text of the page that was returned by the request.
The return_value property is the important one with respect to the operation of remote scripting. The value of the property is the value that was returned by the function in the server-side page. That statement will make more sense after reading the next section. As for what you can do with this value, the short answer is "anything you want". It is just a string, nothing more. I have passed back error messages, delimited strings and full XML documents, depending on the situation. It is also up to you to use the information that comes back to perform the desired task (like filling in the name, address and contract person for the selected customer).
Comments