IBMlogo
IBM eNetwork Communications Server for Windows NT
Host Publisher Feature, Version 6.01
[Next|Previous|Contents]

Using the DYNASCRIPT tag

Use the DYNASCRIPT tag to add server-side ActiveX scripts to pages in a Host Publisher Web library. These scripts can:

You can use several languages to write scripts. The ActiveX scripting syntax varies by language. For specific information about syntax, refer to the documentation for the ActiveX scripting language you are using.

Format

 
<DYNASCRIPT Language="language" {SESSIONED="True/False"}>
    .
    .
    .
</DYNASCRIPT>

Note: The DYNASCRIPT tag requires a </DYNASCRIPT> end tag.

Attributes

The following attributes apply to the DYNASCRIPT tag:

LANGUAGE (Required)

The languages you can use to write scripts in Host Publisher are dependent on the ActiveX scripting engines installed on a PageServer machine. If you have installed Microsoft Internet Explorer 3.x, the developer has access to the VBScript and JScript languages. Additional ActiveX scripting engines might be available for purchase from third-party vendors.

Note: JScript is the Microsoft implementation of the JavaScript scripting language. Although JScript is the Microsoft implementation name, the LANGUAGE= parameter must be JavaScript.

VBScript syntax:
<DYNASCRIPT Language=VBScript>

JScript syntax:
<DYNASCRIPT Language=JavaScript>

SESSIONED (Optional)

When the SESSIONED attribute is specified, the script has access to a Session object that enables scripts across multiple pages to store and retrieve values generated by previous pages and scripts.

VBScript syntax:
<DYNASCRIPT Language=VBScript SESSIONED=true>

JScript syntax:
<DYNASCRIPT Language=JavaScript SESSIONED=true>

Scripting objects

The DYNASCRIPT tag provides access to the following objects:

Session object

The Session object stores key-and-value parameter pairs specified by the developer. This object is unique, because its values remain in place between accesses to Host Publisher pages by the same user. Every user has a unique Session object.

The SESSIONED attribute and session data for the DYNASCRIPT tag maintain data beyond a single page. You must define session data for the page. You can reference the session variable any number of times until the session object time-out expires. The session object time-out default is 10 minutes from the last time the user accesses the session object.

Each parameter pair has a key and a value.

For examples of how to use the Session object, refer to the examples under Session data and Document object examples.

Supported methods for Session object

LookupOne(KeyName)
If there is at least one parameter pair with KeyName as its key, its value is returned. (If more than one pair, the value of any one of the pairs might be returned.) If no parameter pair has KeyName as its key, an empty object is returned.

GetProp(KeyName)
Works just like LookupOne, except that if there is no parameter pair with KeyName as its key, an empty string (that is, the string with the value " ") is returned instead of an empty object.

GetNumPairs()
Returns an integer specifying the number of parameter pairs available.

GetPairKey(PairIndex)
Returns the key string for a parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetPairValue(PairIndex)
Returns the value string for a parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetNumValues(KeyName)
Returns the number of parameter pairs that have KeyName as their key.

GetKeyValue(KeyName, Index)
Returns the value string for a parameter pair with the key of KeyName. Index is zero-based and should be between 0 and GetNumValues(KeyName) -1. For example, GetKeyValue("Hobbies",2) would return the value of the third parameter pair that has "Hobbies" for a key. If PairIndex is out of range, the function returns an empty object.

AddPair(KeyName, ValueName, DontAddDuplicatePair)
Add a new parameter pair. DontAddDuplicatePair is a Boolean value. Pass true if you do not want to add the parameter pair when another pair already has the same key and value. No value is returned.

SetProp(KeyName, ValueName)
Add a new parameter pair, first eliminating any other pairs with a key matching KeyName. No value is returned.

RemovePair(KeyName, ValueName)
Removes a parameter pair. If there are multiple identical pairs, only the first is removed. Returns true if a pair was removed. Returns false if no such pair exists.

RemoveKey(KeyName)
Removes all parameter pairs with a key of KeyName. Returns true if at least one pair was removed. Returns false if no pairs had a key of KeyName.

RemoveAll()
Removes all of the parameter pairs. No value is returned.

Note: Many of the methods return a string upon success or an empty object upon failure. In JavaScript, you can test for the empty object by comparing the return value to null. In VBScript, the empty object can be tested for by comparing it to " ". Unfortunately, there is no way to distinguish between this case and the successful return of an empty string in VBScript.

Changing session data time-out

Use the Registry Editor to change the session data time-out.

The location is:
HKEY_LOCAL_MACHINE\Software\IBM\Host Publisher\PageServer

The key is:
SessionScopeTimeout.

Integration objects can refer to session data

After you have defined session data using DYNASCRIPT statements, any subsequent page or SIM that supports session data can refer to the data. However, before the session data can be used, the page with the DYNASCRIPT SESSIONED attribute must be accessed by a client.

You can enter session data in the following SIMs:

In the

Use the

To

ODBC SIM

Enter SQL and the Edit SQL tabs Select Statement text box

Type:[property name]

ActiveX SIM

Method dialog box, From box

SelectSession Variable

Java SIM

Parameter dialog box

SelectPass the value of a single session value

Host Access SIM

Macro editor

Type:[property name]

Document object

The document object is an object reference to the document the PageServer is generating. Scripts can write content into the current document and the client sees the data.

Supported methods for Document object

Write(string)
Takes a single string parameter, the contents of which are written to the current document.


WriteLn(string)
Takes a single string parameter, the contents of which are written to the current document, followed by a carriage return/line feed.


Include(LibName,BookName, PageName)
Takes three string parameters. This method includes the contents of another Web library (WBL) page and inserts the contents into the current page at the location of the executing script.

Document.Write examples

VBScript syntax:

<DYNASCRIPT Language=VBScript>
Document.Write("Write out some document text")
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript>
Document.Write("Write out some document text");
</DYNASCRIPT>

Document.Include examples

Attention: Do not use the .WBL extension with the name of the library (TestLibrary).

VBScript syntax using a function:

<DYNASCRIPT Language=VBScript>
Dim MyResult
MyResult=Document.Include("TestLibrary", "TestBook", "TestPage")
</DYNASCRIPT>

VBScript syntax using a subroutine:

<DYNASCRIPT Language=VBScript>
Document.Include "TestLibrary", "TestBook", "TestPage"
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript>
Document.Include("TestLibrary", "TestBook", "TestPage");
</DYNASCRIPT>

Session data and Document object examples

If the SESSIONED attribute is specified, a script can set session variables using commands such as:

VBScript syntax:

<DYNASCRIPT Language=VBScript SESSIONED=true>
Session.SetProp "Property1", "Persistent Data for Property One"
Session.SetProp "Property2", "Persistent Data for Property Two"
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript SESSIONED=true>
Session.SetProp("Property1", "Persistent Data for Property One");
Session.SetProp("Property2", "Persistent Data for Property Two");
</DYNASCRIPT>

A script can retrieve those value on another page by using syntax such as:

VBScript syntax:

<DYNASCRIPT Language=VBScript SESSIONED=true>
Document.Write(Session.GetProp("Property1"))
Document.Write(Session.GetProp("Property2"))
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript SESSIONED=true>
Document.Write(Session.GetProp("Property1"));
Document.Write(Session.GetProp("Property2"));
</DYNASCRIPT>

Unless you specify the SESSIONED attribute, the Session object is not available in the context of the script.

Environment object

The environment object contains information about the request for the current page. Its properties enable access to information about the current page's URL and query parameters.

Supported properties for Environment object

URL
String value containing the URL request that came from the client. No Form parameters are passed. Only the URL is passed.


PARAMS
Object value containing properties that map directly by name to the key-and-value parameter pairs passed to the PageServer from the client.


HEADERS
Contains the HTTP request headers passed with the request for the current page.


OUTHEADERS
Passes information that is appended to the HTTP response heading.

Note: The names of these properties are case sensitive.

Environment.URL property

Environment.URL contains the value of the URL for the current page. It does not contain any parameters associated with the URL.

Environment.PARAMS property

Environment.PARAMS refers to key-and-value parameter pairs mapping to the query parameters passed by the client when the current page was requested. In the Web environment, this gives access to Web form selections.

Environment.PARAMS can list all the parameter pairs, even if you do not know the value of the keys.

Environment.PARAMS can store more than one pair with the same key. Scripts using Environment.PARAMS can work with multivalued parameters, such as those produced by a group of check boxes.

Supported methods for Environment.PARAMS property

LookupOne(KeyName)
If there is at least one parameter pair with KeyName as its key, its value is returned. (If there is more than one pair, the value of any one of the pairs might be returned.) If no parameter pair has KeyName as its key, an empty object is returned.


GetProp(KeyName)
Works just like LookupOne, except that if no parameter pair has KeyName as its key, an empty string (that is, the string with the value "") is returned instead of an empty object.


GetNumPairs()
Returns an integer specifying the number of parameter pairs available.


GetPairKey(PairIndex)
Returns the key string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.


GetPairValue(PairIndex)
Returns the value string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.


GetNumValues(KeyName)
Returns the number of parameter pairs that have KeyName as their key.

GetKeyValue(KeyName, Index)
Returns the value string for a specific parameter pair with the key of KeyName. Index is zero-based and should be between 0 and GetNumValues(KeyName) -1. For example, GetKeyValue("Hobbies",2) would return the value of the third parameter pair that has "Hobbies" for a key. If PairIndex is out of range, the function returns an empty object.

Note: Many of the Environment.PARAMS methods return a string upon success or an empty object upon failure. In JavaScript, you can test for the empty object by comparing the return value to null. In VBScript, the empty object can be tested for by comparing it to " ". Unfortunately, there is no way to distinguish between this case and the successful return of an empty string in VBScript.

Environment.URL and Environment.PARAMS examples

In the examples, the following URL is sent from the client to the PageServer:

http://www.company.com/HostPublisher/library/book/page.htm?OS=nt&Version=4.0

VBScript syntax:

<DYNASCRIPT Language=VBScript>
urlname = Environment.URL
SystemType = Environment.PARAMS.GetProp("OS")
SystemVersion = Environment.PARAMS.GetProp("Version")
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript>
urlname = Environment.URL;
SystemType = Environment.PARAMS.GetProp("OS");
SystemVersion = Environment.PARAMS.GetProp("Version");
</DYNASCRIPT>

As a result, the following variables are set to these values:

The following examples demonstrate a simple page that does some form validation and lists the chosen values from a group of check boxes.

VBScript syntax:

<form action=_THIS method=POST>
Name: <INPUT TYPE=TEXT SIZE=20 NAME="UserName"><BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Chess"> Chess<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Gardening"> Gardening<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Horseback Riding"> Hoseback Riding<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Quilting"> Quilting<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Skiing"> Skiing<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Video Games"> Video Games<P>
<INPUT TYPE=SUBMIT VALUE=OK>
</FORM>
<HR>

<DYNASCRIPT LANGUAGE=VBSCRIPT>

NumHobbies = Environment.PARAMS.GetNumValues("Hobbies")
UserName = Environment.PARAMS.LookupOne("UserName")

if NumHobbies = 0 then
    Document.Write("Please Select Some Hobbies.")
elseif UserName = "" then
    Document.Write("Please Enter a Name.")
else
    Document.write(UserName + ", you selected the following Hobbies. <br>")

    REM List all the hobbies
    for HobbyIndex = 0 to NumHobbies - 1
        Hobby = Environment.PARAMS.GetKeyValue("Hobbies", HobbyIndex)
        Document.Write(CStr(HobbyIndex + 1) + ". " + Hobby + "<br>")
    next
    end if

</DYNASCRIPT>


JScript syntax:

<form action=_THIS method=POST>
Name: <INPUT TYPE=TEXT SIZE=20 NAME="UserName"><BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Chess"> Chess<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Gardening"> Gardening<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Horseback Riding"> Hoseback Riding<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Quilting"> Quilting<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Skiing"> Skiing<BR>
<INPUT TYPE=CHECKBOX NAME="Hobbies" VALUE="Video Games"> Video Games<P>
<INPUT TYPE=SUBMIT VALUE=OK>
</FORM>
<HR>

<DYNASCRIPT LANGUAGE=JAVASCRIPT>


  NumHobbies = Environment.PARAMS.GetNumValues("Hobbies");
  UserName = Environment.PARAMS.LookupOne("UserName");

  if (NumHobbies == 0)
      Document.Write("Please Select Some Hobbies.");
  else if (UserName == "" || UserName == null)
      Document.Write("Please Enter a Name.");
  else
  {
  Document.write(UserName + K ", you selected the following Hobbies. <br>");

  // List all the hobbies
    for (HobbyIndex = 0; HobbyIndex < NumHobbies; HobbyIndex++)
      {
      Hobby = Environment.PARAMS.GetKeyValue("Hobbies", HobbyIndex)
      Document.Write((HobbyIndex + 1) + ". " + Hobby + "<br>")
      }
  }

</DYNASCRIPT>

Passing all form parameters

If you do not specify a field name after PARAMS, all form parameters after the ? are passed. The string is in the undecoded form sent by the Web browser.

In the examples, the following URL is sent from the client to the PageServer:

http://www.company.com/HostPublisher/library/book/page.htm?OS=nt&Version=4.0

 
VBScript syntax:

<DYNASCRIPT Language=VBScript>
urlname = Environment.URL
SystemType = Environment.PARAMS
</DYNASCRIPT>

JScript syntax:

<DYNASCRIPT Language=JavaScript>
urlname = Environment.URL;
SystemType = Environment.PARAMS;
</DYNASCRIPT>

As a result, the following variables are set to these values:

Environment.HEADERS property

The Environment.HEADERS object contains the HTTP headers passed with the request for the current page. Using Host Publisher with a Web server point of entry, these headers are actually the headers that the HTTP browser passed when requesting the page.

The methods available with Environment.HEADERS are the same as those available with Environment.PARAMS. Here, the key-and-value parameter pairs refer to header names and header values, rather than query parameter names and values.

Supported methods for Environment.HEADERS

LookupOne(KeyName)
If there is at least one parameter pair with KeyName as its key, its value is returned. (If there is more than one pair, the value of any one of the pairs might be returned.) If no parameter pair has KeyName as its key, an empty object is returned.

GetProp(KeyName)
Works just like LookupOne, except that if no parameter pair has KeyName as its key, an empty string (that is, the string with the value "") is returned instead of an empty object.

GetNumPairs()
Returns an integer specifying the number of parameter pairs available.

GetPairKey(PairIndex)
Returns the key string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetPairValue(PairIndex)
Returns the value string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetNumValues(KeyName)
Returns the number of parameter pairs that have KeyName as their key.

GetKeyValue(KeyName, Index)
Returns the value string for a specific parameter pair with the key of KeyName. Index is zero-based and should be between 0 and GetNumValues(KeyName) -1. For example, GetKeyValue("Hobbies",2) would return the value of the third parameter pair that has "Hobbies" for a key. If PairIndex is out of range, the function returns an empty object.

 
Note: Many of the Environment.HEADERS methods return a string upon success or an empty object upon failure. In JavaScript, you can test for the empty object by comparing the return value to null. In VBScript, the empty object can be tested for by comparing it to "". Unfortunately, there is no way to distinguish between this case and the successful return of an empty string in VBScript.

Environment.HEADERS example

The following example displays all the HTTP request headers that were passed during the request for the current page.

JScript syntax:

<h3>Here are the headers your browser sent:</h3>
<dynascript language=javascript>

Headers = Environment.HEADERS;
NumHeaders = Headers.GetNumPairs();

for (i=0; i < NumHeaders; i++)
{
    Document.Write(Headers.GetPairKey(i) + " = " + Headers.GetPairValue(i));
    Document.Write("<br>");
}

</dynascript>

Environment.OUTHEADERS property

To pass headers back to the Web browser, add header keys to the Environment.OUTHEADERS object. Any headers added to this object are added to the HTTP response headers. Using Host Publisher with a Web server point of entry, these headers are sent back to the Web browser.

Supported methods for Environment.OUTHEADERS

The methods available with Environment.OUTHEADERS are the same as those available with the Session object.

LookupOne(KeyName)
If there is at least one parameter pair with KeyName as its key, its value is returned. (If there is more than one pair, the value of any one of the pairs might be returned.) If no parameter pair has KeyName as its key, an empty object is returned.

GetProp(KeyName)
Works just like LookupOne, except that if there is no parameter pair with KeyName as its key, an empty string (that is, the string with the value "") is returned instead of an empty object.

GetNumPairs()
Returns an integer specifying the number of parameter pairs available.

GetPairKey(PairIndex)
Returns the key string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetPairValue(PairIndex)
Returns the value string for a specific parameter pair, specified by PairIndex. PairIndex is zero-based and should be between 0 and GetNumPairs() -1. If PairIndex is out of range, the function returns an empty object.

GetNumValues(KeyName)
Returns the number of parameter pairs that have KeyName as their key.

GetKeyValue(KeyName, Index)
Returns the value string for a specific parameter pair with the key of KeyName. Index is zero-based and should be between 0 and GetNumValues(KeyName) -1. For example, GetKeyValue("Hobbies",2) would return the value of the third parameter pair that has "Hobbies" for a key. If PairIndex is out of range, the function returns an empty object.

AddPair(KeyName, ValueName, DontAddDuplicatePair)
Add a new parameter pair. DontAddDuplicatePair is a Boolean value. Pass true if you do not want to add the parameter pair when another pair has the same key and value. No value is returned.

SetProp(KeyName, ValueName)
Add a new parameter pair, first eliminating any other pairs with a key matching KeyName. No value is returned.

RemovePair(KeyName, ValueName)
Removes a parameter pair. If there are multiple identical pairs, only the first is removed. Returns true if a pair was removed. Returns false if no such pair exists.

RemoveKey(KeyName)
Removes all pairs with a key of KeyName. Returns true if at least one pair was removed. Returns false if no pairs had a key of KeyName.

RemoveAll()
Removes all parameter pairs. No value is returned.

Pages that are cached by the PageServer do not include the OUTHEADER information. If the page is read from the PageServer cache, the response does not include OUTHEADER information. When using the OUTHEADER property, deactivate page caching for that page.

Note: Many of the Environment.OUTHEADERS methods return a string upon success or an empty object upon failure. In JavaScript, you can test for the empty object by comparing the return value to null. In VBScript, the empty object can be tested for by comparing it to " ". Unfortunately, there is no way to distinguish between this case and the successful return of an empty string in VBScript.

IObjects object

The IObjects object gives DYNASCRIPT access to a global object representing the integration objects.

Supported methods for IObjects object

Get(IntegrationObjectName)
If IntegrationObjectName is the name of an integration object in the current library, this call returns an object representing the integration object.

Integration object
The integration object is the object returned by a successful call to IObjects.Get().

GetItem(ItemName)
Returns the value of the given integration object item (for the current integration object row). If the item is not valid, a null object is returned.

IsItemName(ItemName)
Returns true or false, depending on whether the given item name is a valid item name for the integration object.

NextRow()
Moves the integration object to the next row. Returns false if the integration object is already on the last row, otherwise returns true. Some SIMs, like the Java SIM or ActiveX SIM, support integration objects with one row only.

DoCommand(CommandName)
Instructs the integration object to execute a command. The range of valid commands depends on the SIM of the integration object.

IObject object example

The following DYNASCRIPT example lists all the values for the "ENGLISH" and "SPANISH" items in an integration object named "numbers."

JScript syntax:

<DYNASCRIPT language=javascript>

var numbers = IObjects.Get("numbers");
var bMore = true;
while (bMore)
{
    Document.Write(numbers.GetItem("ENGLISH") + ", " + numbers.GetItem("SPANISH") + "<br>");
    bMore = numbers.NextRow();
}

</DYNASCRIPT>

Alias object

The Alias object gives access to the URL aliases set up for the current Web library (WBL).

Supported methods for Alias object

Lookup(aliasname)
Returns the URL alias established for this name or the name passed to the method if the name is not in the current WBL's URL alias table.

IsPresent(aliasname)
Returns true if the name is in the current WBL's alias table or false if it is not.

Server object

The server object is used to create instances of other OLE servers for use within the script.

Supported methods for Server object

CreateServerObject (string)
Takes as a parameter a single string indicating the Server class name of the object that the developer intends to instantiate.

Server object example

The following example instantiates an instance of Microsoft Excel, which can be used for accessing contents of spreadsheets or setting values passed from Web browsers into spreadsheets for calculation purposes. Any of the methods available within Excel can be accessed through the object returned by Server.CreateServerObject. This sample also uses the IObjects scripting object.

JScript syntax:

<DYNASCRIPT LANGUAGE=JavaScript SESSIONED=true>
z = IObjects.Get("MCATSearchby");
res = z.GetItem("results");
var Excel=Server.CreateServerObject("Excel.Application");
Excel.Workbooks.Open("C:\\temp\\Book1.xls");
Excel.Worksheets("Sheet1").Activate;
Excel.ActiveSheet.Range("A1").Value =res;
Excel.Workbooks.Close;
Excel = null;l
</DYNASCRIPT>


[Next|Previous|Contents]
IBM eNetwork Communications Server for Windows NT
Host Publisher Feature, Version 6.01