VBScript Tutorial


The PI-SDK can be used to provide PI data to users in a Web browser. There are several ways this can be done. Two approaches are shown here, one that uses client side VB script in an HTML page, and one that uses server side VBScript in an ASP page. These two approaches have different software requirements on the client and server that may drive the decision over the method to use.

Unlike Visual Basic, when using VBScript, optional and default arguments must be provided for all calls. This is similar to programming in C++.

  1. Client Side Script

In this example, VBScript is used in an HTML page. The page is stored on a Web server and downloaded to the client on demand where the processing takes place. In this configuration, most current Web servers can be used as the page provider and no special software needs to be installed on the server. The client, however, must be running Internet Explorer 4 or higher and the PI-SDK must be installed on the client machine.

This example allows a user to enter the name of a server and retrieve all the point classes defined on that server. After selecting a particular point class the user can retrieve all the attributes of that class.

  1. Step 1:

On a computer that has the PI-SDK installed locally, open Notepad with an empty file and insert the HTML code below into the file. Save the file as sdkclient.htm in a directory of your choice.

<HTML>

<HEAD>

<TITLE></TITLE>

<P><STRONG><FONT face="" size=5>

PI-SDK Example</FONT></STRONG></P>

</HEAD>

<BODY>

 

<P><STRONG><FONT face="" size=5></FONT></STRONG>&nbsp;</P>

<P><FONT face="" size=4>HTML Page from server using local PI-SDK object to gather server information</FONT>.</P>

<P>Enter Server name:&nbsp;

<INPUT id=text1 name=text1></P>

<P>

<TABLE border=0 cellPadding=1 cellSpacing=1 width=72.34% height=242 style="HEIGHT: 242px; WIDTH: 429px">

<TR><TD>

<P><INPUT id=button1 name=button1 type=button value="Get Point Classes" language="vbscript" onclick="GetPointClasses"></P></TD>

<TD><P><SELECT id=select1 name=select1 size=5

style="HEIGHT: 102px; WIDTH: 183px">

<OPTION selected></SELECT></P></TD></TR>

<TR><TD></TD><TD></TD></TR>

<TR><TD>

<P><INPUT id=button2 name=button2 type=button value="Get Attributes" language="vbscript" onclick="GetAttributes"></P></TD>

<TD><SELECT id=select2 name=select2 size=5 style="HEIGHT: 102px;

WIDTH: 186px"> <OPTION selected></SELECT>

</TD></TR> 

<TR><TD></TD><TD></TD></TR></TABLE> 

</P>

<script language="vbscript">

dim srv, PISDK1, ptclasses

Function GetPointClasses()

err.clear

dim ptclass,e

 

On error resume next

set PISDK1 = createobject ("PISDK.PISDK")

if err.number then

msgbox err.description

exit function

end if

set srv = PISDK1.Servers.Item(CStr(text1.value))

if err.Number then

msgbox err.description

exit function

end if

' Clear listbox

select1.length = 0

set ptclasses = srv.PointClasses

for each ptclass in ptclasses

Set e = Document.createElement("OPTION")

e.Text=ptclass.name

e.Value=ptclass.name

select1.Options.Add e

next  

if err.number then

msgbox "Error retrieving PointClass" & err.description

exit function

end if

end function

Function GetAttributes()

err.clear

On error resume next

dim ptclass,e

set ptclass = ptclasses(select1.value)

' Clear the list box

select2.length = 0

dim ptatr

for each ptatr in ptclass.PointAttributes

Set e = Document.createElement("OPTION")

e.Text=ptatr.name

e.Value="ListItemValue"

select2.Options.Add e

next

end function

 

</script>

</BODY>

</HTML>

 

  1. Step 2:

Open Internet Explorer (version 4 or higher) and select the Open command from the File menu. Choose the Browse button and browse to the location where you stored sdkclient.htm in the previous step. Select the file and click OK.

  1. Step 3:

In the displayed form, enter the name of a server that is in your local Known Servers Table. Click the "Get Point Classes" button. You should see a list of point classes displayed in the list box to the right of the button. Select one of the point classes in the select box and click the button labeled "Get Attributes." You should see the list of attributes for the selected point class displayed in the list box to the right of the button. If you get the message "ActiveX component can't create object." You may have to change the security settings on your browser.  The PI-SDK is not marked "Safe for Scripting" because it has functions that allow writing to the registry.  In principle you could use the SDK to damage registry settings.  Typically you can set the security settings for your Local Intranet Zone to Low as pages from your own site can be trusted and avoid the browser preventing object creation.

  1. Code Discussion:

The HTML code starts with standard header tags.

<HTML>

<HEAD>

<TITLE></TITLE>

<P><STRONG><FONT face="" size=5>

PI-SDK Example</FONT></STRONG></P>

</HEAD>

<BODY>

There is no title for the page though you could add one. A simple string is displayed in the header. This is followed with some text that is displayed in our form.

<P><STRONG><FONT face="" size=5></FONT></STRONG>&nbsp;</P>

<P><FONT face="" size=4>HTML Page from server using local PI-SDK object to gather server information</FONT>.</P>

<P>Enter Server name:&nbsp;

We will not go into basic HTML syntax here as that is available from many sources. We follow our text with an Input box to gather the user's choice of server.

<INPUT id=text1 name=text1></P>

We enclose the following buttons and list boxes in a table to provide visual alignment. Again we leave the details of HTML table attributes to the reader.

<TABLE border=0 cellPadding=1 cellSpacing=1 width=72.34% height=242 style="HEIGHT: 242px; WIDTH: 429px">

We start our first table record and put a button in the first cell.

<TR><TD>

<P><INPUT id=button1 name=button1 type=button value="Get Point Classes" language="vbscript" onclick="GetPointClasses"></P></TD>

This button will be referenced as "button1" and we define its caption with the value attribute. We also indicate that it will execute VBScript as its language and specify the VBScript function, GetPointClasses, we want to call when the user clicks the button. The function is defined later in the page.

In the next cell in our table we define the list box, referred to as a Select box in Web terms.

<TD><P><SELECT id=select1 name=select1 size=5

style="HEIGHT: 102px; WIDTH: 183px">

<OPTION selected></SELECT></P></TD></TR>

We will refer to the box as "select1" and we specify initial size attributes. We then specify an empty row in our table followed by a row whose first cell is another button.

<TR><TD></TD><TD></TD></TR>

<TR><TD>

<P><INPUT id=button2 name=button2 type=button value="Get Attributes" language="vbscript" onclick="GetAttributes"></P></TD>

Button2 will call the GetAttributes function defined later. The next cell contains our second Select box.

<TD><SELECT id=select2 name=select2 size=5 style="HEIGHT: 102px;

WIDTH: 186px"> <OPTION selected></SELECT> </TD></TR>

We finish our HTML display code with another empty row and the end of the table and paragraph.

<TR><TD></TD><TD></TD></TR></TABLE> </P> 

The remaining code defines the functions our buttons will call in VBScript. We start by defining the language.

<script language="vbscript">

Then we declare some page scope variables we will use. In script all variable are of type Variant.

dim srv, PISDK1, ptclasses

We declare our GetPointClasses function next, clear out the global err object (similar to VB), and dimension some local function variables.

Function GetPointClasses()

err.clear

dim ptclass,e

We next create our PISDK app object using the ProgID. Before the call we set the error handling so we can test the return ourselves rather than having the error thrown to a handler. This is similar to Visual Basic error handling discussed elsewhere in this document.

On error resume next

set PISDK1 = createobject ("PISDK.PISDK")

if err.number then

msgbox err.description

exit function

end if

We test the global error object to ensure that we were able to create the object and if not we display a message box and exit the function.

Next we retrieve a server object from the PI-SDK Servers collection using the name entered in our input text box, referring to it by the declared ID "text1." We check the error object again to handle an invalid server name.

set srv = PISDK1.Servers.Item(CStr(text1.value))

if err.Number then

msgbox err.description

exit function

end if

We clear the select box for the point classes by setting its length to 0. This is important if the user clicks the "Get Point Classes" button more than once.

select1.length = 0

We retrieve the PointClasses collection for the server by setting our declared variable to the server's PointClasses property.

set ptclasses = srv.PointClasses

Now we fill the select box with the point classes for this server by iterating through the PointClasses collection in typical Visual Basic "For Each" fashion.

for each ptclass in ptclasses

Set e = Document.createElement("OPTION")

e.Text=ptclass.name

e.Value=ptclass.name

select1.Options.Add e

next  

Note to work with select boxes we need to use the CreateElement method of the Document object passing it the "OPTION" argument. The Document object is a page level object created automatically as part of the Dynamic HTML (DHTML) programming model. Each element has a Text and a Value property. We set both here but the Text property is the one that is displayed in the list box. We could choose to display a different display name for the value we store in the Select list. To add the item to the Select list we call the Add method of the Options member of the select box we designated as "select1." Again we check for errors and display an appropriate method if there is a failure.

if err.number then

msgbox "Error retrieving PointClass" & err.description

exit function

end if

Finally we complete the function.

end function

The second function, GetAttributes, is nearly the same as the GetPointClasses function. We retrieve the point class the user selected by retrieving the selected name from the first select list accessing its Value property.

set ptclass = ptclasses(select1.value)

We then fill up the second select list by iterating through the PointAttribute collection of the PointClass.

We close the HTML code by terminating our script tag, body tag, and finally the HTML tag.

</script>

</BODY>

</HTML>

  1. Server Side Script

In this example, two pages are built. The first is a regular HTML page that gathers data from the user and submits it to an ASP page on the server. The ASP page generates HTML code that is displayed on the client. In this configuration the server must be Microsoft Internet Information Server (for its ASP support), and it must have the PI-SDK installed on it. The clients in this configuration can run any current browser and do not need any PI-SDK specific software or configuration to run.

In this example the user is prompted to enter a server name and a state set name. The form is then submitted to the ASP page, which calls the PI-SDK using VB Script and generates HTML displayed on the client.

  1. Step 1:

The files for this example need to be installed on a machine running Internet Information Server in a directory that is available to clients through a Web address. The user accesses the example by calling up the HTML page GetDigStates.htm. Create this file by opening Notepad and inserting the text below. Save the file as GetDigStates.htm.

<HTML>

<HEAD>

<TITLE></TITLE>

</HEAD>

<BODY>

<Form Action="digStates.asp" Method="POST">

<P><STRONG><FONT face="" size=5>PI-SDK

Example</FONT></STRONG></P>

 

<P>HTML Page talking to Server side ASP Page which uses

PI-SDK for server information.</P>

<P>Enter Server Name:&nbsp;

<INPUT id=text1 name=text1></P>

 

<P>Enter State Set Name:

<INPUT id=text2 name=text2></P>

<P><INPUT id=submit1 name=submit1 type=submit value=Submit></P>

</FORM>

</BODY>

</HTML>

  1. Step 2:

The Web page created in the previous step posts its data to an ASP page named in the HTML code. To create the ASP page, open Notepad and insert the following text. Save the file as digStates.asp in the same directory as the previous file.

<%@ Language=VBScript %><HTML>
<HEAD>
</HEAD>
<BODY>
<P>&nbsp;</P>
<%
set pisdk = Server.CreateObject ("PISDK.PISDK")
strStateset = Request.Form("text2")
Response.write "<SPAN STYLE='font-weight : bold;'>" & strStateSet & "</SPAN>"
set srv = pisdk.Servers(Request.Form("text1"))
set stateset = srv.StateSets.Item(CStr(strStateSet))
for each digstate in stateset
   Response.Write "<P>" & digstate.name & "</P>"
next
%>
</BODY>
</HTML>

  1. Step 3:

From a client machine, open a browser and navigate to the Web location where you stored the GetDigStates.htm page. The page should prompt for a server name and a state set name. Enter a PI Server name from the Known Servers Table on the Web server machine where Internet Information Server is running and the PI-SDK is installed. Enter a state set name for a set available on the entered PI Server then click the Submit button. The ASP page should generate a new page with the state set name as its title and list the various states under it, one per line.

  1. Code Discussion:

The initial page, GetDigStates.htm, is quite simple. As with the client side code the page starts with standard HTML header information.

<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">

<TITLE></TITLE>

</HEAD>

<BODY>

The initial tag for starting a form follows this.

<Form Action="digStates.asp" Method="POST">

The action attribute of this form indicates the page that will receive the data from this form. The method attribute indicates that the form data should be posted to the receiving page, which sends it in the data stream rather than as part of the URL.

The next few lines are standard HTML text displaying the page title and the prompt for the server name.

<P><STRONG><FONT face="" size=5>PI-SDK

Example</FONT></STRONG></P>

<P>HTML Page talking to Server side ASP Page which uses

PI-SDK for server information.</P>

<P>Enter Server Name:&nbsp;

This is followed by an Input tag for gathering the server name.

<INPUT id=text1 name=text1></P>

The prompt for the state set name looks much the same.

<P>Enter State Set Name:

<INPUT id=text2 name=text2></P>

Following the text entries we have an input tag for our button.

<P><INPUT id=submit1 name=submit1 type=submit value=Submit></P>

The type=submit attribute indicates that this input tag is for a button that submits a form. This type of input also provides a name/value pair that is passed with the form data.

We close the page with ending tags.

</FORM>

</BODY>

</HTML>

 

We indicated in the Form tag that we would submit the form to the page digstates.asp. This page starts with a language declaration.

<%@ Language=VBScript %>

In ASP pages, all text between the <% and %> tokens is processed on the server. HTML outside these tokens in displayed on the client with other data written to the client by the ASP code.

The next few lines are normal HTML header information.

<HTML>

<HEAD>

<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">

</HEAD>

<BODY>

<P>&nbsp;</P>

This is followed by some ASP code. First we create the main PI-SDK app object.

<%set pisdk = Server.CreateObject ("PISDK.PISDK")

As this is VBScript, the variables are again variants. The "Server" name here is a bit misleading. In this context it is part of the ASP object model and represents the Internet Information Server, in whose process space we will create our PISDK object. We create the object from a ProgID as before.

Next we retrieve the name of the requested StateSet from the submitted form passing the name of the form element to retrieve. We need this value twice so we store it in a variable.

strStateset = Request.Form("text2")

Now we display the name of the requested StateSet to the user using the Response.Write function to write to the browser within our code. We have used a span tag to show the name in bold.

Response.write "<SPAN STYLE='font-weight : bold;'>" & strStateSet & "</SPAN>"

Next we retrieve a PI-SDK Server object using the name passed in on the original form. Again we specify the name of the form element to retrieve.

set srv = pisdk.Servers(Request.Form("text1"))

Now we retrieve the desired StateSet object from the PI-SDK Server using the name we retrieved earlier. Note we use the CStr function on this variable that we are passing to StateSets.Item.  This is because the Item method for StateSets takes a Variant as an index and we need to specify that the type of variant we are passing in this case is a string.  You could also pass the StateSet ID to the Item method as a numeric.

set stateset = srv.StateSets.Item(CStr(strStateSet))

To complete the task we iterate through the states of the StateSet using a "For Each" loop.

for each digstate in stateset
   Response.Write "<P>" & digstate.name & "</P>"
next

Again we use Response.Write to output to the browser from our procedure and we include paragraph tags to get each state on a new line. 

Finally we close the ASP code and conclude the open HTML tags, body and HTML.

%>

</BODY>

</HTML>

The code accessing the PI-SDK for both of these samples is straightforward and should be familiar to Visual Basic programmers. These Web access methods allow the developer to choose between distributed processing on clients with installation and configuration requirements, or more centralized data manipulation available to a wide audience using any browser.

Enabling Operational Intelligence