Chapter 3 DynaScript Predefined Objects

document object

Object

Represents a document in your Web site. Each document can be a file or folder.

Syntax

To use a document's property:

document.propertyName

To use a document's method:

document.MethodName( parameter )

Description

The methods that you use to manipulate documents are shared between the document object and the site object.

The site object allows you to manipulate your Web site's documents. For example, use the following format to create a document:

site.CreateDocument(docName, documentType, description, content[,connectionName | connectionId])

For information on site.CreateDocument, site.DeleteDocument, or site.GetDocument, see "site object".

WARNING!

Don't confuse the Dynamo document object and the JavaScript document object. The Dynamo document object supports a different set of properties and methods that are customized for working with databases.

Example

This example creates a new document called MyDoc in the Site folder:

<!--SCRIPT 
  site.CreateDocument( "/site/MyDoc.stm","text", "my new document", "hello" );
-->

cachedOutputTimeOut property

Syntax

document.cachedOutputTimeOut

Description

Duration of time (integer) for which the generated output of a script or template is cached. The default is zero. This property is not persistent; it is reset to zero if you restart the Web server.

Example

This example sets the cache time of the current document output to 3 minutes.

<!--SCRIPT 
  /* setting the cache time */
  document.WriteLn( "This is my output that will be cached for 3 minutes." ); 
  document.cachedOutputTimeOut = 3;
-->

connectionId property

Syntax

document.connectionId

Description

ID of associated connection object (integer). Connection IDs may change if you restart the Web server. For this reason, Sybase recommends that you use the connectionName property instead.

Example

This example displays the connection ID of a script's associated connection object:

<!--SCRIPT 
  /* displays the connection Id */
  document.WriteLn( document.connectionId ); 
-->

The output from this example might look like this:

connectionName property

Syntax

document.connectionName

Description

Name of the associated connection object (string).

Example

This example displays the connection name of a script's associated connection object.

<!--SCRIPT 
  /* display the connection name */
  document.WriteLn( document.connectionName );
-->

contentType property

Syntax

document.contentType

Description

Type of document being displayed (string). The content types are standard MIME content types. This property is not persistent; it will be reset when the Web server is restarted.

Example

This example selects a graphic called bart.gif from a table in the database and then displays it to a browser. The second part of the example tells the browser to expect an image rather than HTML.

<!--SQL 
  select data from imagetable where imagename = 'bart.gif'
-->

<!--SCRIPT
  /* set the content type to image */
  document.contentType = "image/gif";
  document.write( SQL.GetValue("data") );
-->

description property

Syntax

document.description

Description

Description associated with the document (string).

Example

This example displays the description that was entered when the document /Site/descript.ssc was created:

<!--SCRIPT 
  descDoc = site.GetDocument ( "/Site/descript.ssc" );
  document.WriteLn( descDoc.description );
-->

id property

Syntax

document.id

Attributes

This property is read-only.

Description

Internal document object ID (integer). IDs may change if you restart the Web server. For this reason, Sybase recommends that you use the documentName property to identify documents instead of the ID property.

Example

This example displays the document ID.

<HTML> 
<TITLE>docid.stm</TITLE>
<BODY>
<H1>Display the document's Id number.</H1>
<p>The document id for docid.stm is: </p>
<!--SCRIPT
  document.WriteLn( document.id );  
-->
</BODY>
</HTML>

The output is similar to:

Display the document's Id number.

The document id for docid.stm is: 

265

lastModified property

Syntax

document.lastModified

Attributes

This property is read-only.

Description

Returns the time (string) of the last change to the document (for example, 1996-10-24 14:24:29 ).

Example

This example displays the date the document was last altered:

<!--SCRIPT 
  document.WriteLn( document.lastModified );
-->

The output from this example is:

1997-06-06 10:40:30

location property

Syntax

document.location

Description

Full URL for the document.

Linked folders
You cannot move a linked folder inside a linked folder.

Example

This example displays the location of the document object.

<!--SCRIPT 
  /* location of the document. */
  document.WriteLn( document.location );
-->

The output from this example is:

/Site/location.ssc

name property

Syntax

document.name

Description

Name (including extension, if any).

Example

This example displays the name of the document.

<!--SCRIPT 
  /* name of the document. */
  document.WriteLn( document.name );
-->

The output from this example is:

name.ssc

parent property

Syntax

document.parent

Description

The containing folder object of this document (document).

Linked folders
You cannot move a linked folder inside a linked folder.

Example

This example moves the document /site/sample/products.stm into /site/myFolder:

<!--SCRIPT 
  myFolderDoc = site.GetDocument( "/site/myFolder" );
  productsDoc = site.GetDocument( "/site/sample/products.stm" );
  productsDoc.parent = myFolderDoc
-->

redirect property

Syntax

document.redirect

Description

The name of the URL to which the current request is to be directed (string). This property is not persistent; it will be reset when you restart the Web server.

Example

This example directs a request to http://www.sybase.com:

<!--SCRIPT 
  document.redirect = "http://www.sybase.com";
-->

size property

Syntax

document.size

Attributes

This property is read-only.

Description

Length in bytes (integer) of the document.

Example

This example displays the size of the document:

<!--SCRIPT 
  /* Size of the document. */
  document.WriteLn( document.size );
-->

source property

Syntax

document.source

Description

Uninterpreted document content (source).

Example

This example changes the contents of /site/sample.stm to "hello world":

<!--SCRIPT 
  sampleDoc = site.GetDocument( "/site/sample.stm" );
  sampleDoc.source = "hello world";
-->

status property

Syntax

document.status

Description

A string that indicates a status code and a brief explanation of that code. The status code values are defined in the HTTP specification.

Example

This example prompts the user for a user ID and a password, then displays the status code.

<!--SCRIPT 
  authType = document.GetServerVariable( "AUTH_TYPE" );
  if( authType != null ) {
    authType = authType.toUpperCase();
  }
  if( authType == "BASIC" ) {
   // Web server has successfully authenticated
   // the user
    document.writeln( "<HTML>Welcome</HTML>" )
  } else {
   // document.status is part of the HTTP
   // header sent to the browser.
   // For "401" a browser will prompt the 
   // user for a userid and password and attempt 
   // to login to the Web server
  document.status = "401 Unauthorized";  
   // since the HTTP headers are only seen by the 
   // browser, we still need to provide an    
   // informational message which
   // will be displayed if the user selects
   // cancel in the login dialog
  document.writeln( "<html><body><h1>" );
  document.writeln( document.status );
  document.writeln( "</h1></body></html>" );
}
-->

type property

Syntax

document.type

Attributes

This property is read-only.

Description

The type of Dynamo document (string). One of:

directory Dynamo folder
directoryLink Dynamo linked folder
image binary file
script DynaScript file
text Dynamo HTML template

Example

This example displays the document type:

 <!--SCRIPT 
  /* type of document */
  document.WriteLn( document.type );
-->

value property

Syntax

document.value.variable

Attributes

This property is read-only.

Description

Values of passed-in arguments (URL arguments, typically from an HTML form), where variable is the argument name (array).

Example

This example converts a user provided temperature from Celsius to Fahrenheit or from Fahrenheit to Celsius.

The first part of the example prompts the user to select the type of conversion and to enter a value. The values are held in the parameters theType and temperature :

<HTML>
<H1>Converting Temperatures   </H1>
<BODY>

<P>This page allows you to convert a temperature from <I>Celsius</I> to
<I>Fahrenheit</I> or from <I>Fahrenheit</I> to <I>Celsius</I>.
<BR>
<HR WIDTH="100%">

<P>Select the appropriate button and enter the temperature you would like
to convert.

<FORM METHOD=POST ACTION="convert.stm">
<OL>
<LI><INPUT TYPE="radio" NAME="theType" value="CtoF" CHECKED>Celsius to Fahrenheit<BR>
<INPUT TYPE="radio" NAME="theType" value="FtoC">Fahrenheit to Celsius<BR>
<LI><INPUT TYPE="text" NAME="temperature" SIZE="4"> Temperature
</OL>
<P><INPUT TYPE="submit"></p>
<P><INPUT TYPE="RESET" VALUE="Clear Form"></P>
</FORM>

</BODY>
</HTML>

The next part of the example receives the values entered by the user and uses the values to calculate the requested temperature:

<HTML>
<TITLE>convert.stm</TITLE>
<BODY>
<H1>Temperature</H1>
<P>Your answer is: </P>

<!--SCRIPT
  // receiving  user provided data 
  var conversionType = document.value.theType;
  var tempnumber = document.value.temperature;

  var DemoObj = CreateObject( "SybaseDemoObject.TempConvert" );
  if( conversionType == "CtoF" ){
    var c = DemoObj.ConvertCtoF( tempnumber );
    document.WriteLn( "The Celsius temperature of " + tempnumber + " is " + c + " on the Fahrenheit scale." );
    } else {
      var f = DemoObj.ConvertFtoC( tempnumber ); 
      document.WriteLn( "The Fehrenheit temperature of " + tempnumber + " is " + f + " on the Celsius scale." );
    }  
-->

</BODY>
</HTML>

The first part of the next example prompts the user to select items from a list in which all the items have the same name element of "choice" . If only one item is selected, the value is held in document.value.variable. If two or more items are selected from the list the values are held in document.value[0], document.value[1], document.value[2], and so on.

The second part of the next example displays the arguments selected from the first template.

<HTML>
<TITLE>multpar.stm</TITLE>
<BODY>
<HTML>
<H1>What Do I Have To Do Today? </H1>
<BODY>

<P> To do list:
<FORM METHOD=POST ACTION="display.stm" MULTIPLE SIZE="5">
<OL>
<INPUT TYPE="checkbox" NAME="choice" value="Laundry">Laundry<BR>
<INPUT TYPE="checkbox" NAME="choice" value="Walk the dog">Walk the dog<BR>
<INPUT TYPE="checkbox" NAME="choice" value="Wash the car">Wash the car<BR>
<INPUT TYPE="checkbox" NAME="choice" value="Groceries">Get groceries<BR>
<INPUT TYPE="checkbox" NAME="choice" value="Dust">Dust the house<BR>
</OL>
<P><INPUT TYPE="submit" VALUE="Submit List"></p>
<P><INPUT TYPE="RESET" VALUE="Clear Form"></P>
</FORM>
</BODY>
</HTML>

<HTML>
<TITLE>display.stm</TITLE>
<BODY>
<H1>My tasks are:</H1>
<!--SCRIPT
  if( typeof( document.value.choice ) == "object" ) {
    i = 0;
    while( exists( document.value.choice[i] ) ) {
      document.writeln( "value[" + i + "] = " + document.value.choice[i] );
      i++;
    }
  } else {
    document.writeln( "value = " + document.value.choice );
  }
-->
</BODY>
</HTML>

The last example looks up and displays the ID for a customer whose first and last name have been sent by a browser (typically in response to an HTML form).

<!--SCRIPT 
  myQuery=connection.CreateQuery( "select id from customer where lname = '" + document.value.lastName + "' and fname = '" + document.value.firstName + "'" );
  myQuery.MoveNext();
  document.WriteLn( yQuery.GetValue(1));
  myQuery.Close();
-->

ExportTo method

Syntax

document.ExportTo(pathName [, newName])

Description

For files, saves the file as an external (disk) file in the pathName disk directory. For folders, saves the contained document tree (all nested files and folders) as an external directory tree (disk files and folders) in the pathName disk directory. newname allows you to optionally rename the file in its new location.

Return

Boolean. This method returns true or false, indicating whether the method succeeded or not.

Example

This example exports /site/products.stm to the c:\ drive:

<!--SCRIPT 
  productDoc = site.GetDocument ( "/site/products.stm" );
  productDoc.ExportTo( "c:" )
-->

GetDirectory method

Syntax

document.GetDirectory( [fileMask, sortOrder] )

Description

For folder documents, returns an array of contained documents (for example, a directory listing) matched by the string fileMask. fileMask can contain the wildcard characters "*" and "?". The sort order may be name or type. Name is the sortOrder default.

For information on the wildcards, see "Wildcards".

Return

Array of document objects. Returns a list of contained documents.

Example

This example displays all the documents in the /site folder that begin with the letter "a" and then sorts them alphabetically:

<!--SCRIPT 
  siteDoc = site.GetDocument( "/site" );
  dirList = siteDoc.GetDirectory( "a*", "name" );
  for ( i in dirList ) {
    document.WriteLn( dirList[i].name );
  }
-->

GetGenerated method

Syntax

document.GetGenerated( )

Description

Returns the interpreted output from a document as a string. You cannot run this method from within the same document from which you are calling GetGenerated .

Return

String. Returns the interpreted output.

Example

This example runs the script /site/products.ssc and places the output in the variable "part1". /site/products.ssc takes two parameters; name and password.

myDoc = site.GetDocument( "/site/products.ssc" );
myDoc.value.name = "open";
myDoc.value.password = "sesame";
part1 = myDoc.GetGenerated();

Inside products.ssc you would use "document.value.name ", and "document.value.password " to access the parameter values.

GetServerVariable method

Syntax

document.GetServerVariable( )

Description

Returns a value from a server. The server variable name is dependent on which server interface is being used. This method is not supported by CGI servers.

CGI equivalent	ISAPI	NSAPI (native)	NSAPI (Dynamo cover for NSAPI)	Personal Web Server
AUTH_TYPE	AUTH_TYPE	auth-type	AUTH_ TYPE
CONTENT_ LENGTH	CONTENT_ LENGTH	content-length	CONTENT _LENGTH	CONTENT_ LENGTH
CONTENT_ TYPE	CONTENT_ TYPE	content-type	CONTENT_TYPE	CONTENT_ TYPE
GATEWAY_INTERFACE	GATEWAY_INTERFACE			GATEWAY_ INTERFACE
HTTP_USER_AGENT	HTTP_USER_ AGENT	user-agent	HTTP_USER_AGENT	HTTP_USER_AGENT
PATH_INFO	PATH_INFO	path	PATH_INFO	PATH_INFO
PATH_TRANSLATED	PATH_TRANSLATED
QUERY_ STRING	QUERY_ STRING	query	QUERY_ STRING	QUERY_ STRING
REMOTE_ ADDR	REMOTE_ ADDR	ip	REMOTE_ ADDR	REMOTE_ ADDR
REMOTE_ HOST	REMOTE_ HOST
REMOTE_ USER	REMOTE_ USER	auth-user	REMOTE_ USER
REQUEST_METHOD	REQUEST_ METHOD	method	REQUEST_METHOD	REQUEST_METHOD
SCRIPT_ NAME	SCRIPT_NAME		SCRIPT_ NAME	SCRIPT_ NAME
SERVER_ NAME	SERVER_ NAME
SERVER_ PORT	SERVER_PORT			SERVER_ PORT
SERVER_ PROTOCOL	SERVER_ PROTOCOL	protocol	SERVER_ PROTOCOL	SERVER_ PROTOCOL
SERVER_ SOFTWARE	SERVER_ SOFTWARE		SERVER_ SOFTWARE	SERVER_ SOFTWARE
	HTTP_COOKIE	cookie	COOKIE	COOKIE
	URL			URL_PREFIX
	UNMAPPED_ REMOTE_USER
	SERVER_PORT_SECURE
	HTTP_ACCEPT
	ALL_HTTP

Return

String. Returns a value from the server.

Example

This example displays the address of the remote host:

<!--SCRIPT 
  REMOTE_ADDR = document.GetServerVariable( "REMOTE_ADDR" );
  document.writeln( "<BR>REMOTE_HOST = "+ REMOTE_ADDR  );
-->

The output for this example is:

REMOTE_ADDR = 122.47.156.352

ImportFrom method

Syntax

document.ImportFrom(fileName[, replaceOption, newName ])

Description

Imports the external file (or folder and its contents) named fileName into the Web site.

If name conflicts occur, the optional replaceOption determines how to resolve them:

newer Replaces existing file if incoming one is newer. This is the default if you do not specify replaceOption.
all Replaces existing file regardless of modification dates.

You can rename an imported file or folder with the optional newName parameter.

Return

Boolean. This method returns true or false, indicating whether the method succeeded or not.

Example

This example imports the file d:\test\products.stm into the Site folder:

<!--SCRIPT 
  /* Import a document to a folder */
  myfolder = site.GetDocument ( "/Site" );
  myfolder.ImportFrom ( 'd:\\test\\products.stm','all' );
-->

IncludeGenerated method

Syntax

document.IncludeGenerated( )

Description

Includes the generated output of the document that is called in the output of the currently executing script. A document cannot call document.IncludeGenerated on itself.

Return

Boolean. This method returns true or false, indicating whether the method succeeded or not.

Example

This example gets the include.stm document and then generates and displays the output of that document within the current document:

<!--SCRIPT 
   mydoc=site.GetDocument( "~/include.stm" ); 
   mydoc.IncludeGenerated();
-->

Here are the contents of include.stm:

<HTML>
<TITLE>include.stm</TITLE>
<BODY>
<H1></H1>
<!--SQL
SELECT  customer.fname, customer.lname
FROM DBA.customer customer

 -->
<TABLE BORDER>
<TR>
<TH>fname</TH>
<TH>lname</TH>
</TR>
<!--formatting--><TR>
<TD><!--data--></TD>
<TD><!--data--></TD>
</TR><!--/formatting-->
</TABLE>
</BODY>
</HTML>

The output from this example is:

<HTML>
<TITLE>include.stm</TITLE>
<BODY>
<H1></H1>

<TABLE BORDER>
<TR>
<TH>fname</TH>
<TH>lname</TH>
</TR>
<TR>
<TD>Michaels</TD>
<TD>Devlin</TD>
</TR><TR>
<TD>Beth</TD>
<TD>Reiser</TD>
</TR><TR>
<TD>Erin</TD>
<TD>Niedringhaus</TD>
</TR><TR>
<TD>Meghan</TD>
<TD>Mason</TD>
</TR><TR>
<TD>Laura</TD>
<TD>McCarthy</TD>
...

Write method

Syntax

document.Write(outputString)

Description

Appends outputString to the output generated by this document.

Example

This example generates output without a line break:

<!--SCRIPT 
  document.WriteLn( "This is the write method. " );
  document.writeLn( "You can use a lower case w." );
-->

The output of this example is:

This is the write method. You can use a lower case w.

WriteLn method

Syntax

document.WriteLn(outputString)

Description

Same as Write , but also adds a line break.

Line breaks produced with WriteLn only work when viewing an HTML document as plain ASCII source (for example, in a text editor).

When this HTML is processed by a Web client, the resulting layout ignores these line breaks, so WriteLn ultimately produces the same output as Write .

To force line breaks in the final output, you must use the HTML <P> or <BR> tag. For example:

document.WriteLn( "<P>This starts on a new line" );

In general, WriteLn makes your HTML source easier to read, but does not reflect how it is formatted by a Web client.

To remain compatible with JavaScript, Dynamo allows you to use write for Write , and writeln for WriteLn .

Example

This example:

<!--SCRIPT 
  document.WriteLn( "This is the writeln method. " );
  document.writeln( "You can use lower case (writeln) or upper case (WriteLn)," );
  document.WriteLn( "but not Writeln." );
-->

outputs:

This is the writeln method. 
You can use lower case (writeln) or upper case (WriteLn),
but not Writeln.

document object

Object

Syntax

Description

Example

See also

cachedOutputTimeOut property

Syntax

Description

Example

connectionId property

Syntax

Description

Example

See also

connectionName property

Syntax

Description

Example

See also

contentType property

Syntax

Description

Example

description property

Syntax

Description

Example

id property

Syntax

Attributes

Description

Example

lastModified property

Syntax

Attributes

Description

Example

location property

Syntax

Description

Example

name property

Syntax

Description

Example

parent property

Syntax

Description

Example

redirect property

Syntax

Description

Example

size property

Syntax

Attributes

Description

Example

source property

Syntax

Description

Example

status property

Syntax

Description

Example

type property

Syntax

Attributes

Description

Example

value property

Syntax

Attributes

Description

Example

ExportTo method

Syntax

Description