iiChapter 3 Using the ILS ActiveX Server Component With Active Server Pages

To use ILS, you will use the Active Server Pages script processor and its collection of objects and components, as well as the ILS ActiveX server component. This chapter provides the information needed for using the ILS component in Active Server Pages scripts.

iiii

The Basics

All pages that use scripting must use the .asp file name extension, and must be in a virtual root on your Web server that has both read and execute permission.

iiiiiiiii

Creating a Reference to the ILS ActiveX Server Component

You must create an instance of each ActiveX server component you use in each HTML page that uses the component. When you create the instance, the server component executes commands to initialize itself. You must also create a variable for this instance of the server component. This variable is used when you call the methods and properties of the server component. You choose the variable name to use in your script.

Creating an instance of the object and assigning a variable are both done in one statement in your .asp page:

<% set variable = Server.CreateObject ("component_identifier") %>

The component identifier for ILS is ms.ils.

For example, to create a reference to the ILS component in your script, you could use the following line to create a variable called ils.

<% set ils = Server.CreateObject("ms.ils") %>

The object creation statement must precede use of the component.

When a script completes, the instance of the object is removed from memory.

To refer to an ILS database attribute in a script, you use VBScript syntax to refer to the attribute as a property of the created object. For instance, the example below shows the location of a user:

<% = ils.location %>

iiiiiiiiiiii

Using the ILS ActiveX Server Component

Components have both methods and properties. Methods take parameters while properties can be either read or set.

When you use a method or property, you prefix it with the variable name you defined when you created the instance of the object using Server.CreateObject. For example, the Error property shows the error code. To display the error code, you would use this line:

<% = ils.error %>

You can nest calls inside methods. In the following example, the call to the Active Server Pages Request object is nested inside the call to the Find method.

<% ils.find(Request.form)%>

iiiiiiii

Active Server Pages Syntax

Complete syntax information can be found in the online Active Server Pages Roadmap provided with the Internet Information Server version 3.0 upgrade.

There are several key syntax issues to note:

Two types of comments can be used: complete statements and comments inside another script line. Neither type is sent to the client, so they can both be used to help make your pages readable and maintainable, without being visible to the user.

For complete comment lines, use

<% REM Comment here. %>

Comments can also be inserted in the middle of a script by using a single quote. For example,

<% if ils.gna = "" then 'first name is blank %>

To display an output expression, such as the value of a property or the result of a method, you must use an equal sign (=). For example, to display the last name of a user, you would use:

<% = ils.fna %>

In order to split a single line of VBScript code into multiple lines for readability, the last character at the end of intermediate lines must be an underscore (_).
Many methods and properties return TRUE or FALSE. If you display the return value, TRUE is displayed as -1, and FALSE is displayed as 0.

iiiiiiiiiiiii

Error Handling

Whenever you use any of the components in a script, you must be prepared for errors. Checking for error conditions in your scripts is critical for the user to have a good experience.

There are several error handling issues to consider in all scripts:

While debugging your scripts, you will want to leave ASP error handling on by default. Once you have finished debugging your page and are ready to release your content, you may want to include the following line at the beginning of your file so that the page continues to be processed after an error. This lets you provide your own error messages, rather than showing the error messages provided by Active Server Pages. However, it also means that error messages you are not expecting will be ignored, potentially masking error conditions.

<% on error resume next %>

Make sure the ILS ActiveX server component exists after you create it. For example:

<% on error resume next %>

<% set ils = Server.CreateObject("ms.ils") %>

<% if IsObject(ils) = FALSE then %>

ILS is not installed correctly on this server.

<% else %>

Rest of page here.

<% end if %>

Check the return code for each method you use to see that the operation completed successfully. For example, the Create method creates a new listing.

<% createresult = ils.create(Request.form) %>

<% if ( createresult <> "WPQR_SUCCESS" ) then %>

Your listing was not created due to the following error:

<%=ils.error %>.

<% end if %>

When processing information provided to an .asp page by a form, check for no response. For example:

<% if Request("cna") = Empty then %>

You must provide your e-mail name to delete your listing.

<% else %>

<%ils.delete(Request.form)%>

<% end if %>

When writing .asp pages that process input from a form, be sure to handle the case when a user clicks the browser Refresh button. You need to trap this situation and provide an appropriate method. To do this, you can use the Content_Length property of the Active Server Pages Request method.

For example:

<% if Request("Content_Length") > 0 then %>

Show online users.

<% else %>

Provide form to collect user's information.

<% end if %>

Return to Start Page