Chapter 3 DynaScript Predefined Objects
The site
object
has these methods:
site.AskQuestion (title, message)
Displays a message with Yes and No buttons. This method is supported only when executing documents through Sybase Central.
Boolean. Returns true if the user picked Yes, and false otherwise.
To ask the user if he would like to continue:
<!--SCRIPT
if ( site.AskQuestion ( "Error", "Do you wish to continue?" )) {
document.WriteLn( "continuing" );
}
document.WriteLn( "good bye" );
-->
site.CopyDocument (source document, destination document)
Copies a document from one location to another. The destination document may be given a name other than the source document name when being copied. The specified path may be a relative or an absolute path or the tilde (~) character may be used. This is a method of the site object.
For information on using the tilde character see "Paths".
Boolean.
This example takes a copy of form.stm and places it into a folder called Forms with the new name form_new.stm:
<!--SCRIPT
site.CopyDocument("~/form.stm","/Forms/form_new.stm");
-->
For ODBC connections:
site.CreateConnection(connName, description, dataSource [, userName, password, type, connectParameters])
For Open Client connections:
site.CreateConnection(connName, description, server, userName, password, type [, database])
Creates a new persistent connection and returns a new connection object, where:
CreateConnection and DeleteConnection
You cannot delete a connection that
a script is actively referencing. Because of this, do not use CreateConnection
and DeleteConnection in the same script unless the connection object
has gone out of scope, or has been set to null by the time DeleteConnection
is called.
If the data source or server is blank, the
connection inherits the necessary information from the main connection
(the connection used by Dynamo to access the Web site documents).
The connection object returned by CreateConnection
in
this case is "incomplete" and cannot be used to
create a query. To obtain a connection object with the blank fields
filled in, use site.GetConnection.
Temporary connection
To create a temporary connection,
use the connection constructor. See "connection object" for
more information.
Connection object representing the newly created connection, or null if the connection cannot be created.
Typical reasons for null to be returned are:
This script creates a new ODBC connection to the sample database, and uses the new connection to execute a query.
<!--SCRIPT createConnection.ssc
/* Creating a connection to another site */
myConn = site.CreateConnection ( "Dynamo Demo", "sample application", "sample", "dba", "sql" );
-->
<HTML>
<TITLE>Query of the sample database </TITLE>
<BODY>
<H1>Information regarding the management team</H1>
<!--SQL CONNECTION_OBJECT = myConn
SELECT employee."manager_id", employee."emp_lname", employee."emp_fname", employee."salary"
FROM "DBA"."employee" employee
-->
<TABLE BORDER>
<TR>
<TH>manager_id</TH>
<TH>emp_lname</TH>
<TH>emp_fname</TH>
<TH>salary</TH>
</TR>
<!--formatting--><TR>
<TD><!--data--></TD>
<TD><!--data--></TD>
<TD><!--data--></TD>
<TD><!--data--></TD>
</TR><!--/formatting-->
</TABLE>
</BODY>
</HTML>
site.CreateDocument(docName, documentType, description, content [, connectionName | connectionId])
Creates a new document in the Web site and returns a document object. The parameters are:
"/Site/test/customer.stm"
document.type
).
directoryLink
, description is
the directory path of the disk-based folder.
Note:
Connection IDs are not persistent.
If you restart Dynamo, connection IDs may not be the same. For this
reason, we recommend the use of connection names whenever possible.
CreateDocument and DeleteDocument:
You cannot delete a document that
a script is actively referencing. Because of this, do not use CreateDocument
and DeleteDocument in the same script unless the document object
has gone out of scope, or has been set to null by the time DeleteDocument
is called.
Document object representing the newly created document, or null if the document cannot be created.
A typical reason for null to be returned is that a document by that name already exists.
This script creates a new template called MyDoc.stm inside the Site folder. The new document will consist of the word "hello".
<!--SCRIPT newdoc.ssc
site.CreateDocument( "/site/MyDoc.stm","text", "my new document", "hello" );
-->
site.CreatePropertySheet(propertySheetObject)
Starts the property sheet defined by propertySheetObject, where propertySheetObject is an indexed object, and each array element in it represents a separate property sheet page with the following properties:
text
Single-line
text box.
password
Single-line
text box with typed characters shown as asterisks (for security).
textArea
Multi-line
text box.
choice
Combo
box of values (uses choices).
sql
SQL-query
textArea with button to open query editor.
fileBrowse
Single-line
text box with Browse button to open standard file-selection dialog.
directoryBrowse
Single-line
text box with Browse button to open standard folder-selection dialog.
type
is sql
).
type
is sql
).
type
is choice
).
choices
array
that is selected by default when the wizard page is displayed (if type
is choice
).
This method is supported only when executing documents from within Sybase Central.
You can find the following propsht.ssc class file in the /system/utils directory of your site folder:
<!--SCRIPT propsht.ssc created on 06/25/97 09:33:32
// The following class is used for creating simple
// property sheet pages
class propertySheetPage( type, title, explanation, question, choices, selected, help ) {
this.type = type;
this.title = title;
this.explanation = explanation;
this.question = question;
this.choices = choices;
this.selected = selected;
this.help = help;
}
// The following class is used to indicate the
// position of an item on a property sheet page.
// If null is passed in to any of the parameters,
// a default value will be used.
class itemPosition( left, top, width, height )
{
this.left = left;
this.top = top;
this.width = width;
this.height = height;
}
// The following class is used to make a single
// item that you would like to place on a property
// sheet page.
class propertySheetItem( type, question, choices, selected, position, help )
{
this.type = type;
this.question = question;
this.choices = choices;
this.selected = selected;
this.position = position;
this.help = help;
}
// The following class is used to place a bitmap on
// a property sheet page.
class propertySheetPictureItem( picture, position )
{
this.type = "picture";
this.picture = picture;
this.position = position;
}
// The following class is used to make advanced
// property pages that contain more than one input
// field.
class propertySheetAdvanced( title, explanation, items )
{
this.type = "Advanced";
this.title = title;
this.explanation = explanation;
// Items: An array of items to be placed on the wizard
// page. Each member of the array should be of type
// wizardItem or wizardPictureItem. Null may be passed
// in if you would like a wizard page with no input
// fields in it.
this.items = items;
}
-->
Boolean. Returns true or false, indicating whether the user proceeded through the wizard or not.
This example shows how a script can use the site
object
to create a property sheet.
<!--SCRIPT NewLink.ssc
/* Add a folder linked to a directory*/
var webRoot = site.GetRootDocument();
import ( webRoot.location + '/system/utils/strtable.ssc' );
import ( webRoot.location + '/system/utils/wizard.ssc' );
var pSheet;
pSheet.name = new wizardPage( 'Text',
IntlStr.wizNewLink.p1.title,
IntlStr.wizNewLink.p1.explanation,
IntlStr.wizNewLink.p1.question
);
pSheet.directory = new wizardPage( 'DirectoryBrowse',
IntlStr.wizNewLink.p2.title,
IntlStr.wizNewLink.p2.explanation,
IntlStr.wizNewLink.p2.question
);
/* Display the wizard */
if( site.CreatePropertySheet(pSheet) ) {
/* Check if a folder name was provided */
if( pSheet.name.value.length > 0 ) {
/* Create the folder in the specified */
/* directory */
var fullname = document.location;
+ '/' + pSheet.name.value;
var newFolder = site.CreateDocument( fullname, 'directorylink', pSheet.directory.value );
if( newFolder == null ) {
document.writeln( formatString( IntlStr.unableToCreate, fullname ) );
}
} else {
document.writeln( IntlStr.noFolderName );
}
}
-->
site.CreateWizard(wizardObject)
Starts the wizard defined by wizardObject, where wizardObject is an indexed object, and each array element in it represents a separate wizard page with the following properties:
text
Single-line
text box.
password
Single-line
text box with typed characters shown as asterisks (for security).
textArea
Multi-line
text box.
choice
Combo
box of values (uses choices).
sql
SQL-query
textArea with button to open query editor.
fileBrowse
Single-line
text box with Browse button to open standard file-selection dialog.
directoryBrowse
Single-line
text box with Browse button to open standard folder-selection dialog.
type
is sql
).
type
is sql
).
type
is choice
).
choices
array
that is selected by default when the wizard page is displayed (if type
is choice
).
This method is supported only when executing documents from within Sybase Central.
You can find the following wizard.ssc class file in the /system/utils directory of your site folder:
<!--SCRIPT wizard.ssc
// The following class is used for creating simple
// wizard pages
class wizardPage( type, title, explanation, question, choices, selected, next, help ) {
this.type = type;
this.title = title;
this.explanation = explanation;
this.question = question;
this.choices = choices;
this.selected = selected;
this.next = next;
this.help = help;
}
// The following class is used to indicate the
// position of an item on a wizard page. If null
// is passed in to any of the parameters, a default
// value will be used.
class itemPosition( left, top, width, height ) {
this.left = left;
this.top = top;
this.width = width;
this.height = height;
}
// The following class is used to make a single
// item that you would like to place on a wizard
// page.
class wizardItem( type, question, choices, selected, position, help ) {
this.type = type;
this.question = question;
this.choices = choices;
this.selected = selected;
this.position = position;
this.help = help;
}
// The following class is used to place a bitmap on
// a wizard page.
class wizardPictureItem( picture, position )
{
this.type = "picture";
this.picture = picture;
this.position = position;
}
// The following class is used to make advanced wizard
// pages that contain more than one input field.
class wizardAdvanced( title, explanation, items, next ) {
this.type = "advanced";
this.title = title;
this.explanation = explanation;
// Items: An array of items to be placed on the wizard
// page. Each member of the array should be of type
// wizardItem or wizardPictureItem. Null may be passed
// in if you would like a wizard page with no input
// fields in it.
this.items = items;
this.next = next;
}
-->
Boolean. Returns true or false, indicating whether the user proceeded through the wizard or not.
This example shows how a script can use the site
object
to create a wizard. Each page contains a single item:
<!--SCRIPT
/*Simple wizard example */
class wizardPage( type, title, explanation, question, choices, selected, next, help ) {
this.type = type;
this.title = title;
this.explanation = explanation;
this.question = question;
this.choices = choices;
this.selected = selected;
this.next = next;
this.help = help;
}
var wiz;
// From "start" control passes to "page1".
wiz.start = new wizardPage( 'text',
'Customer Information',
'New customer data should be entered here.',
'What company do you represent?',
null, null,
'page1'
);
// From "page1" control passes to "productpage".
wiz.page1 = new wizardPage( 'text',
'Customer Information',
"You must provide a name for direct billing.",
'Please enter a first and last name.',
null, null,
'productpage'
);
var products;
products[0] = "widget";
products[1] = "hammer";
products[2] = "putty";
products[3] = "stripper";
wiz.productpage = new wizardPage( 'choice',
'Product',
'We have various products available for our customers. To place an order, select a product from the following list.',
'Choose a product.',
products
);
site.CreateWizard( wiz );
document.writeln( "Customer " + wiz.page1.value + " ordered a " + wiz.productpage.value );
-->
This example uses the wizardAdvanced class and the itemPosition class while creating a wizard that asks users for their mailing address. The wizardAdvanced class is used to create wizards that have multiple items per page:
<!--SCRIPT
var webRoot = site.GetRootDocument();
import ( webRoot.location + '/system/utils/wizard.ssc' );
var wiz;
var items;
var provinces;
provinces[0] = "Alberta";
provinces[1] = "British Columbia";
provinces[2] = "Manitoba";
provinces[3] = "New Brunswick";
provinces[4] = "Newfoundland";
provinces[5] = "Northwest Territories";
provinces[6] = "Nova Scotia";
provinces[7] = "Ontario";
provinces[8] = "Prince Edward Island";
provinces[9] = "Quebec";
provinces[10] = "Saskatchewan";
provinces[11] = "Yukon";
// third and fourth arguments to wizardItem are
// ignored by all types except "choice"
// if a null argument is passed to itemPosition, it
// uses the default
items.firstName = new wizardItem( "text", "First Name", null, null, new itemPosition( null, 20, 65, null ) );
items.lastName = new wizardItem( "text", "Last Name", null, null, new itemPosition( 160, 20, 100, null ) );
items.street = new wizardItem( "text", "Street" );
items.city = new wizardItem( "text", "City", null, null, new itemPosition( null, 75, 80, null ) );
items.province = new wizardItem( "choice", "Province", provinces, 0, new itemPosition( 175, 75, 85, null ) );
items.postalCode = new wizardItem( "text", "Postal Code", null, null, new itemPosition( null, null, 80, null ) );
// wizardAdvanced displays all the wizardItems in
// the items array on one page.
wiz.page = new wizardAdvanced( "Address", "Please enter your mailing address.", items );
if( site.CreateWizard( wiz ) ) {
with( wiz.page.items ) {
document.writeln( firstName.value + " " + lastName.value );
document.writeln( street.value );
document.writeln( city.value + ", " + province.value );
document.writeln( postalCode.value );
}
}
-->
This example uses the next
element
to conditionally choose which wizard page should be displayed next:
<!--SCRIPT
// This is a class we define for convenience that
// sets up a single wizard page. This class
// is available to users in the file
// /site/system/utils/wizard.ssc.
class wizardPage( type, title, explanation, question, choices, selected, next, help ) {
this.type = type;
this.title = title;
this.explanation = explanation;
this.question = question;
this.choices = choices;
this.selected = selected;
this.next = next;
this.help = help;
}
var wiz;
// This function gets executed when the user hits
// the Next button from the "wiz.start" page.
// It determines whether the next page should be
// "page1", or "page2".
function whichpage() {
var pagestr = "page";
pagestr += ( wiz.start.selected + 1 );
return pagestr;
}
function CreateCustomerId( name )
{
return 12345678;
}
// On this first page, the user chooses whether
// they are a new or returning
// customer. If new, "page1" is displayed next,
// otherwise "page2" is displayed next.
var choices;
choices[0] = 'New Customer';
choices[1] = 'Returning Customer';
wiz.start = new wizardPage( 'choice',
'Welcome',
'If you are a new customer select "New Customer". Otherwise, select "Returning Customer".',
'What kind of customer are you?',
choices,
0,
whichpage
);
// From "page1" control passes to "productpage".
wiz.page1 = new wizardPage( 'text',
'New Customer',
"Before you can purchase anything, you must have a customer ID. In order to get this, you must give us your name.",
'Please enter your name.',
null, null,
'productpage'
);
// From "page2" control passes to "productpage".
wiz.page2 = new wizardPage( 'text',
'Returning Customer',
'Welcome back. Before you can purchase anything, you must identify yourself by providing your customer ID' ,
'Please enter your customer ID.',
null, null,
'productpage'
);
var products;
products[0] = "hat";
products[1] = "shirt";
products[2] = "pogo stick";
products[3] = "ball of yarn";
wiz.productpage = new wizardPage( 'choice',
'Product',
'We have various products available for our customers. To place an order, select a product from the &
following list.',
'Choose a product.',
products
);
if( site.CreateWizard( wiz ) ) {
var id;
if( whichpage() == "page1" ) {
id = CreateCustomerId( wiz.page1.value );
} else {
id = wiz.page2.value;
}
document.writeln( "Customer #" + id + " ordered a " + wiz.productpage.value );
}
-->
site.DeleteConnection(connName)
Deletes the persistent connection defined by connName.
CreateConnection and DeleteConnection
You cannot delete a connection that
a script is actively referencing. Because of this, CreateConnection
and DeleteConnection should not be used in the same script unless the
connection object has gone out of scope, or has been set to null at
the time DeleteConnection is called.
Boolean. This method returns true or false, indicating whether the method succeeded or not.
Typical reasons for false to be returned include:
This example deletes the connection named MyConnection:
<!--SCRIPT
if ( site.DeleteConnection("MyConnection") ) {
document.WriteLn( "deleted" );
}else{
document.WriteLn( "unable to delete connection" );
}
-->
site.DeleteDocument(docName)
Deletes the document object defined by docName. docName may contain the wildcard characters * and ? and can be an absolute or relative path. The tilde (~) may also be used.
For information on the * and ? wildcards see "Wildcards".
CreateDocument and DeleteDocument
You cannot delete a document that
a script is actively referencing. Because of this, CreateDocument
and DeleteDocument should not be used in the same script unless the
document object has gone out of scope, or has been set to null at
the time DeleteDocument is called.
Boolean. This method returns true or false, indicating whether the method succeeded or not.
Typical reasons for false to be returned include:
This example deletes a document called MyDoc.stm from within the Site folder.
<!--SCRIPT
if ( site.DeleteDocument( "/Site/MyDoc.stm" )){
document.WriteLn( "deleted" );
} else {
document.WriteLn( "unable to delete document" );
}
-->
site.GetConnection(connName | connId)
Returns the connection object representing the persistent connection called connName[string], or having id connId[integer].
Note:
Connection IDs are not persistent.
If you restart Dynamo, connection IDs may not be the same. For this
reason, Sybase recommends the use of connection names whenever possible.
Connection object representing the specified connection, or null if the connection cannot be retrieved.
Typical reason for null to be returned include:
This example changes the database to which "myConnection" connects:
<!--SCRIPT
myConn = site.GetConnection ( "myConnection" );
myConn.database = "newDatabaseName";
-->
site.GetConnectionIdList( [true|false] )
Returns an array of IDs of connection objects. If true is specified, the list of connection IDs will include IDs representing the special connections <no connection> and <inherited>. If false is specified, the list of connection IDs does not include IDs representing the special connections. The default is true.
Array of integers.
To display a list of connection IDs.
<!--SCRIPT
document.WriteLn( site.GetConnectionIdList() );
-->
site.GetConnectionNameList( [true|false] )
Returns an array of names of connection objects. If true is specified, the list of connection names includes the two special connections <no connection> and <inherited>. If false is specified, the list does not include the special connections. The default is true.
Array of strings.
This script displays the list of connection names.
<!--SCRIPT
document.WriteLn( site.GetConnectionNameList() );
-->
site.GetDocument(docName | docId)
Returns the document object defined by docName [string] or docId [integer]. docName may be a relative or an absolute path or you can use the tilde (~) character. For more information on using the tilde please see "Paths".
Note:
IDs are not guaranteed to be the
same after restarting the Web server. For this reason, Sybase recommends
that you use the document name to identify documents.
Document object representing the specified document, or null if the document could not be retrieved. A typical reason for null to be returned is that the specified document does not exist.
This script retrieves the document MyDoc.stm from within the Site folder, passes a login name and password to MyDoc.stm, executes MyDoc.stm, and displays the output:
<!--SCRIPT
myDoc = site.GetDocument( '/Site/MyDoc.stm' );
myDoc.value.loginName = "homer";
myDoc.value.password = "doh";
document.WriteLn( myDoc.GetGenerated() );
-->
site.GetErrorCode( )
Returns the current error code.
Integer. Returns an error code associated with the last operation performed.
This example displays information as to why the connection was not created successfully:
<HTML>
<TITLE>sample.stm</TITLE>
<BODY>
<!--SCRIPT
myConn = new Connection( 'connection1', '', 'ASA 6.0 Sample', 'basUser', 'badPassword' );
if( myConn == null ) {
document.writeln( "Error Code: " + site.GetErrorCode() );
document.writeln( "Error Message: " + site.GetErrorInfo() );
document.writeln( "Error State: " + site.GetState() );
}
-->
</BODY>
</HTML>
site.GetErrorInfo( )
A description of the error associated with the last operation performed.
String.
This example displays information as to why the connection was not created successfully:
<HTML>
<TITLE>sample.stm</TITLE>
<BODY>
<!--SCRIPT
myConn = new Connection( 'connection1', '', 'ASA 6.0 Sample', 'basUser', 'badPassword' );
if( myConn == null ) {
document.writeln( "Error Code: " + site.GetErrorCode() );
document.writeln( "Error Message: " + site.GetErrorInfo() );
document.writeln( "Error State: " + site.GetState() );
}
-->
</BODY>
</HTML>>
site.GetEventList([controlType])
Returns an array of all controlType event
handlers currently installed (by OnEvent
).
If controlType is not specified, all installed
event handlers are returned.
controlType is described
in the OnEvent
method.
Each event handler object contains read-only
properties that correspond to the parameters of the OnEvent
method.
The only difference is the handlerScript property,
which always has an absolute path, regardless of how it was initially specified
with OnEvent
.
Array of event handler objects.
This example uses GetEventList
to
display all previously created event handlers with the control type
of Icon
.
<!--SCRIPT
// Show "Icon" event handlers for directories
eventList = site.GetEventList( 'Icon' );
i = 0;
while( exists( eventList[i]) ) {
event = eventList[i];
document.writeln( event.controlLabel );
i++;
}
-->
site.GetRootDocument( )
Returns the document object representing the
root document of the Web site (in most cases, the Site
folder).
Document object.
This script executes a template called MyDoc.stm which resides in the root directory of the Web site:
<!--SCRIPT
root = site.GetRootDocument();
myDoc = site.GetDocument( root.location + '/MyDoc.stm' );
document.WriteLn( myDoc.GetGenerated() );
-->
site.GetState( )
Returns information about the SQL state of the last query operation performed.
GetState is meaningful only if the most recent error was database-related.
This example displays the state of the most recent Dynamo database error:
<HTML>
<TITLE>sample.stm</TITLE>
<BODY>
<!--SQL
SELECT customer.fname, customer.lname, customer.phone, customer.id
FROM DBA.customer customeer
-->
<!--SCRIPT
queryState = site.GetState();
document.WriteLn( queryState );
queryInfo = site.GetErrorInfo();
document.WriteLn( queryInfo );
queryCode = site.GetErrorCode();
document.WriteLn( queryCode );
-->
</BODY>
</HTML>
site.Include(scriptName)
Executes the specified script and returns a string containing the generated output of scriptName (absolute or relative path).
String.
This executes the script sample.ssc and returns the generated output.
<!--SCRIPT
output = site.Include( 'Site/sample.stm' );
document.WriteLn( output );
-->
site.OnEvent(itemName, controlType, controlLabel, description, handlerScript)
Adds an event handler to the management interface (typically for creating an icon or menu item in Sybase Central), where:
connection
Any
connection.
connectionFolder
The
connection folder.
directory
Any
document folder.
image
Binary
data (not script or template).
script
Any
script.
site
The
Web site database (not the Web site folder).
text
Any
template.
Get
Command
that comes from the Web server when a document is requested. Applies
only to directory
, image
, script
,
and text
item types.
NewMenu
Displays
from a new menu option, within a menu.
ContextMenu
Menu
that appears when you right-click.
Icon
Only
for site
, directory
,
and connectionFolder
.
Status404
Occurs
when a request for a document is made that is not available.
Parser
Occurs
when a request for a document generates an error.
SessionTimeOut
Occurs
just before a session times out. This controlType applies to the site
itemType.
The parameters controlLabel
and description
are
not applicable.
Get,
Status404
, or SessionTimeOut
.
Get
or Status404
.
OnEvent
method
is called.
Boolean. This method returns true or false, indicating whether the method succeeded or not.
For example, the following code is added to
the autoexec.ssc file in the System folder
to create an icon to execute the wizard created in the site method CreateWizard
example.
//Example Wizard
site.OnEvent( 'directory','Icon','Dynamo Example for Creating Wizards','Wizard Example','NewLink.ssc' );
This example, if added to the autoexec.ssc file, would cause the execution of the cleanup.ssc script just before a session times out:
site.OnEvent( 'Site', 'SessionTimeOut', ' ', ' ', 'cleanup.ssc' );
This example, if added to the autoexec.ssc file, would cause the execution of error.ssc whenever a request was made for a document that generates an error:
site.OnEvent('','Parser','','','error.ssc');
This example, if added to the autoexec.ssc file, would cause the execution of notfound.ssc whenever a request was made for a document that could not be found:
site.OnEvent('','status404','','','notfound.ssc');
Execute from /system/autoexec.ssc
You
should only call the OnEvent
method
from /system/autoexec.ssc
or from
another script that is executed from within the autoexec script.
site.RenameDocument(source document, destination document)
Takes source document, renames and saves it in destination document (i.e. source document is moved). The specified path may be a relative or an absolute path or the tilde (~) character may be used. This is a method of the site object.
For information on using the tilde character, see "Paths".
Boolean.
This example moves forms.stm from the root of the Web site, renames it to test.stm and places it in the Sample location:
<!--SCRIPT
site.RenameDocument("~/form.stm","~/Sample/test.stm");
-->
site.ShowMessage (title, message)
Displays a message with an OK box. This method is supported only from within Sybase Central.
This example displays the message "Task complete".
<!--SCRIPT
site.ShowMessage("Request status", "Task complete");
-->
| Copyright © 1999 Sybase, Inc. All rights reserved. |
| |