Client-side scripting
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).