JScript is Microsoft's implementation of the ECMAScript 3 language specification and has a syntax that is similar to object oriented languages like C++ and Java. The following section covers the general information needed to use scripting components in your own scripts. For general information about the language, refer to the JScript User's Guide.

Creating Objects

To begin using one of the scripting components, the first thing that you need to do is create an instance of the object for use in your script. This is typically done using the CreateObject function. However, it is important to note that different scripting hosts provide alternate methods of creating an instance of a component. For example, in Internet Explorer, the <object> tag can also be used to create an instance of an object for use in a client-side script. The following code is an example of how the File Transfer Protocol scripting object could be created:

var ftpClient = WScript.CreateObject("SocketTools.FtpObject.6");

The argument to the CreateObject function is called the programmatic ID (ProgID) for the component. It is a string which identifies the object that is to be created, and each scripting component has a unique name. To determine what value should be passed for a specific component, refer to the Technical Reference documentation. Once an instance of the object has been created, you can reference it just as you would any other ActiveX control or COM object.

Note that in this example, we are using the CreateObject method in the WScript object which is part of the Windows Script Host. Active Server Pages would use Server.CreateObject instead. It is also possible to create an instance of the object using the ActiveXObject function:

var ftpClient = new ActiveXObject("SocketTools.FtpObject");

One difference is that the ActiveXObject function will only allow the script to access the properties and methods of the component, but not its events. If you wish to implement event handlers for your WSH script, you should use the WScript.CreateObject method instead.

Initialization

After an instance of the object has been created, the next step that you need to take is to call the Initialize method. This will prepare the component for use, validating the runtime license, loading any required networking libraries and allocating the system resources that it requires. The Initialize method has several optional arguments, however in most cases the only argument that is required is the runtime license key. This is a string of characters which is used to validate your development license. It is important to note that the runtime key is not your product serial number. For more information, refer to the section on Component Initialization. The following code demonstrates how the FTP component can be initialized:

var strLicenseKey = ""; // Set this to the runtime license key string
var nError = ftpClient.Initialize(strLicenseKey);
if (nError != 0) {
    WScript.Echo("Unable to initialize SocketTools component");
    return;
}

Good coding practice dictates that for every time the Initialize method is called, it should be matched with a call to the Uninitialize method before the object is destroyed or the script terminates. This tells the component to release any resources that were allocated. Note that if your script does not explicitly call the Uninitialize method, it will be done automatically when the object is destroyed.

Data Types

JScript is a loosely typed language, which means that you do not explicitly declare the data type of variables. Instead, all variables are considered to be variants, and JScript will automatically perform any data conversions as needed. For example, if you add a numeric value to a variable that contains a string, that number will be converted to a string.

Error Handling

Errors returned by the scripting components are handled in one of two ways in JScript. If an error occurs when setting a property, this will raise an exception that must be handled by the script or it will terminate with an error message. For example, if an invalid value is assigned to the FTP object's URL property, an exception will be thrown. To catch these errors, use the try..catch statement:

try {
    ftpClient.URL = strResource;
}
catch (e) {
    var nError = e.number & 0xffff;
    WScript.Echo("Error " + nError.toString() + ": " + e.description);
    WScript.Quit(1);
}

The e argument to the catch statement specifies the Error object which contains information about the last error that occurred. It has two properties, number and description. Note that the error number returned by the Error object is a 32-bit value, with the low word containing the error code.

If an error occurs when calling a method in one of the scripting components, that method will typically return a numeric error value which indicates the type of error. A return value of zero indicates that the method was successful. The following is an example of how the return code from the Connect method is used to determine if the connection was successful:

var nError = ftpClient.Connect(strHostName)
if (nError != 0) {
    WScript.Echo(ftpClient.LastErrorString);
    WScript.Quit(1);
End If

In this case, the LastErrorString property is used to display a message to the user indicating why the method failed. Note that there are some exceptions to this rule, where some methods may return either a string or boolean value. Refer to the technical reference documentation for the component to determine what an appropriate return value is for a specific method.

Event Handling

Event notification is the means by which the component informs the script of a change in the status of the current session. It is similar in concept to function callbacks, and developers who are familiar with Visual Basic will find that events are handled in a similar way in JScript. For example, when the GetFile method is used in the FTP component, as the file is being downloaded the OnProgress event will be periodically fired so that the script can update any user interface objects, such as a ProgressBar control. The event handler would look like this:

function ftpClient_OnProgress(FileName, FileSize, BytesCopied, Percent)
{
    formMain.progressBar.Value = Percent;
}

To enable event notification in the Windows Script Host, the object must be connected to the event handler using the ConnectObject method. This is typically done after the object has been created, but before it is initialized:

var strLicenseKey = ""; // Set this to the runtime license key string
var nError = ftpClient.Initialize(strLicenseKey);
if (nError == 0) {
    WScript.ConnectObject(ftpClient, "ftpClient_");
}
else {
    WScript.Echo("Unable to initialize SocketTools component");
    return;
}

The second argument to the ConnectObject method is the prefix which the scripting engine looks for to determine if the function is an event handler. In this case, a function that begins with ftpClient_ followed by the name of an event for the object will be considered the handler for that event. It is important to keep in mind that the event handler signature (the number of arguments passed to the event handler) must match exactly, otherwise the event handler code will not be called.

If you are using JScript in HTML pages and want to use events, you cannot create automagic event handlers like you can in VBScript. You must use the <script> tag to define a handler instead, such as:

<script for="ftpClient" event="OnProgress(FileName, FileSize, BytesCopied, Percent)" language="jscript">
<!--
    formMain.progressBar.Value = Percent;
-->
</script>

An important thing to keep in mind is that if you wish to use events in your web page, you must create an instance of the object in the page using the <object> tag, not by using the CreateObject function. For more information about how to use the scripting components in web pages, refer to the section on Internet Explorer.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.