Web Crossing Server-side JavaScript (WCJS)

Table of Contents

» Overview

Web Crossing's JavaScript environment is specifically designed to build Web pages. Each request from a Web browser can be served by a combination of HTML text and JavaScript functions.

Special objects are provided to access the incoming request, work with input form variables, and produce a response page. You have total control over the response, including the ability to easily forward to another location, set cookies, and so on.

Web Crossing's JavaScript environment is nicely coupled to its built-in database, giving you access to a user directory and to hierarchical, extensible, object-oriented data items. (If you prefer, you can use external services for persistent storage. You are never required to exclusively use the tools built into Web Crossing.)

» JavaScript function library

Pre-loaded JavaScript functions can be used to process Web-Crossing-specific requests, or to define your own dynamic pages.

A file named webx.tpl is used for pre-loaded JavaScript functions. This file can include any number of function definitions and initialization functions.

The syntax for JavaScript functions in the webx.tpl file is

%% command name(args...){...} %% -or-
%% function name(args...){...} %%

For example, here is the classic "Hello world" application written in JavaScript for Web Crossing:

%%
command hello(){
    + "Hello world!";
}
%%

...webx?hello

» JavaScript reserved words

abstract
boolean
byte
char
class
double
extends
final
float
goto
implements
import
int
interface
long
native
package
private
protected
public
short
static
super
synchronized
throws
transient
volatile

» Including server-side JavaScript files

<!--#Include File="filename"-->

where filename is the file to include. You must use this syntax exactly: spaces, capitalization, and all.

It is often convenient to use separate files for each new JavaScript object or set of related functionality.

» Shorthand for appending to the response page

Any JavaScript statement that starts with a plus sign (+) is evaluated as an expression and then appended to the response page. That is, the statement

+"Hello world"; // or
+ "Hello world";

response.append( "Hello world" );

» Mixing HTML and JavaScript code

%% command test() {
    %%This is a test function that just puts text into the response page.%%
} %%

%% command test {
    response.append( "This is a test function that just puts text into the
response page." );
} %%

In addition, you can use the \ character to suppress the end-of-line characters, so you can break up long HTML lines into smaller pieces for readability. Leading tabs are stripped from text lines, again so you can write readable HTML. For example, the text

%% Hello \
    there%%

response.append( "Hello there" );

%% command processRequest(){
    %% many lines of html ... %%
    if( form.accept == "true" ){
      %% You have accepted the software license. %%
    } else {
      %% You have chosen to decline the software license. %%
    }
    %% many more lines of html ... <img
src="%%site.imagesUrl%%/example5.gif"> ... %%
} %%

» Initialization and pre-defined classes

This means that you can use an init_ function to pre-build an object class, adding functions and data constants to the constructor's prototype. For example,

%% function Def(...){
    ...
}

function init_Def() {
    /* Define Def class */
    a = new Def(...); /* Results in a prototype for Def constructor */
    Def.prototype.Value1 = 12345; /* Assign prototype values, etc */
    ...
    function Def_checkIt() {
    ...
    }
    Def.prototype.checkIt = Def_checkIt;
} %%

A global propery named libraryGlobal is available to reference the global context that is copied to become the intial global object for each incoming request.

» Variable scope

In practice, this means that you can use global variables as desired, and each request will have its own set of gobals.

The following table shows a more detailed outline of variable resolution in Web Crossing, compared to client-side usage.

Resolution steps	Web Crossing usage (server-side)	Browser usage (client-side)
First	If the variable is defined in a var statement, it is local to the current execution of the function and is read/write.	Same.
Second	Lookup the variable as a property of the current function.	Same.
Third	Lookup the variable in the current request's global scope. These variables are read-write.	Lookup the variable in the window in which the function was defined. These variables are read-write.

» Grouped JavaScript functions

%% macro style1 %%
    %% macro folder %%
      ... folder layout for style1
    %% endmacro %%

    %% macro discussion %%
      ... discussion layout for style1
    %% endmacro %%
%% endmacro %%

With JavaScript functions, you can use the same structure:

%% macro style1 %%
    %% command folder {
      ... folder layout for style1
    } %%

    %% command discussion {
      ... discussion layout for style1
    } %%
%% endmacro %%

Functions grouped in this manner are placed into JavaScript container objects that correspond to the macro grouping. In the example above, the full names of the functions would be

style1.folder and
style1.discussion

» Mixing JavaScript and WCTL

JavaScript and WCTL can both set properties of stored objects, and pass data to each other this way. However, WCTL cannot reference any JavaScript types except strings. In other words, if WCTL accesses a path.var that was stored by a JavaScript "node.var = value;" statement, the WCTL program will get the correct value if it is a string, but will get the empty string as the value for any other JavaScript type.

You can access WCTL variables from JavaScript by using wctlVar( variable ) and setWctlVar( variable, value ).

» Calling JavaScript from WCTL

string.jsEval

%% "1+2".jsEval %%

%% jsError %%

string.jsEvalOrError

» Calling WCTL from JavaScript

wctlEval( expression ) or
wctlEvalTemplate( template )

wctlEval( "1+2" ) will return "3",
wctlEvalTemplate( "xxxx %" + "% 1+2 %" + "%" ) will return "xxxx 3"

wctlEval( "xxxx %% 1+2 %%" )

» Debugging

Run-time errors will return the page to the point of the error, followed by the error message and a stack trace. You sometimes need to do a "View as source" in order to see the error messages.

» Processing an HTTP Request

A JavaScript function must be enabled to respond to incoming URLs.

Each incoming request is run in its own private global context. The global properties are:

request	top-level object, default scope for variables. For example, "request.certificate" is the same as "certificate"
top	during initialization, top is the same as libraryGlobal. During request processing, top is the same as request.
response	ByteBuffer accumulating the response page to return to the browser
cgi	object with a string property for each CGI variable
form	object with a string property for each input-form field
user	user for current session (read/write variable)
location	the Node object specified in the location parameter of the URL, or null if none (read/write variable)
locationArray	array of parents for the location object, with location as the last element. (read/write variable)
site	current global site settings
topLevelFolder	top-level folder for the site
session	object with read/write property strings for the current user's persistent session information
certificate	certificate string for the current user/session (read/write variable)
error	some methods indicate errors by setting this error message. It is the error from last such command, or null for no error

» Enabling JavaScript functions to serve URLs

function myLookup(){
...
}
function init_myLookup(){
    myLookup.urlEnable = true; // Enable URL processing
}

command myLookup(){
...
}

» URL syntax

.../webx...?functionName@certificate@location!formName=value&...

.../webx...?	directs the URL to the Web Crossing server, however this is configured.
functionName	is the name of the JavaScript function or method
certificate	is the optional certificate for this session (WCTL automatically keeps track of user and per-session variables, see the following discussion of the "session" object.)
location	is an optional location in the WCTL object-oriented database (OODB)
formName=value	is an optional list of input fields. Each formName and value must be URL quoted.

If the location has a method with the specified functionName, then that method is called. This is the same as

var n = Node.lookup( "location" );
n.functionName();

If there is no method or function with the right name, then an error message is displayed.

» request

For example, request.certificate is the same as certificate unless there is a local variable named "certificate".

» response

To add HTML text to the response page, just use

response.append( text );

javascript code...;
%% text %%
more javascript code...;

You can also append text to the response by putting a plus sign as the first character of a JavaScript statement, as

+ "hello there " + user.userName + ".<br>";

To embed URLs for Web Crossing functions, see the built-in command makeUrl.

The final response value will direct Web Crossing to take appropriate action:

response page	action
non-empty response, not starting with HTTP/	This is a normal HTML page, and Web Crossing will automatically generate the HTTP header for the response. (Responses to a Web browser are an HTTP header, a blank line, then the page itself. So if you provide the page, Web Crossing will provide the HTTP header and blank line.)
response starting with HTTP/	Whenever a response page evaluates to text starting with HTTP/, that page is returned as is, without adding the standard HTTP response heading. For example, the following function forwards the incoming request to <http://mysite.com/test.html>.  %% function forward { response.append( "HTTP/1.0 302 Redirect" ); response.crlf(); response.append( "Location: http://mysite.com/test.html" ); response.crlf(); response.crlf(); } %% This is because HTTP/1.0 302 Redirect has a response code of 302, which asks the browser to temporarily forward the original URL to a new location. Note that the forwarding response must end with a final blank line, because this blank line marks the end of the response HTTP header. The page itself, following this blank line, is empty.
empty response page	Web Crossing assumes that the user needs to login before this function can run correctly, and will return a login page. After the user successfully logs in, the current function will be reexecuted with the same input-form values.

» cgi

You can enumerate the available properties. For example, the following function will show a list of cgi properties:

%% function showCgi(){
    for( i in cgi )
      response.append( i + ": " + cgi[i] + "<br>" );
} %%

Typical cgi properties and their use are:

cgi property	use
query_string	The query string from the incoming URL, the portion following the first question mark in the URL. This string is URL-quoted, so the query string from the request "http://test.webcrossing.com/webx?showCgi@@" becomes a cgi.query_string of "showCgi%40%40". To remove the URL-quoting, use cgi.query_string.fromUrl().
script_name	Incoming request, following the server domain and before any question mark and query string. For example, the request "http://test.webcrossing.com/webx?showCgi@@" has a cgi.script_name of "/webx".
https	Set to "on" if the request is via a secure SSL connection, otherwise is not defined.
http_Referer	The URL of the page that contained the link to the current request
http_User_Agent	Type of client browser, such as "Mozilla/4.05 (Macintosh; U; PPC, Nav)"
http_Connection	Type of connection, such as "Keep-Alive"
http_Host	Domain name or IP address of the host serving this request, such as "www.webcrossing.com"
http_Accept	The mime-types that the browser will accept, such as "image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*"
http_Accept_Language	Languages that the browser will accept, such as "en" for English
http_Accept_Charset	Charsets that the browser will accept, such as "iso-8859-1,*,utf-8"
request_method	Request type, "GET" or "POST"
remote_addr	IP address of the client Web browser, such as "1.2.3.4".
server_name	Domain name or IP address of this server, such as "test.webcrossing.com".
url_scheme	If you need to know whether a request came in over a secure SSL connection or not, use cgi.url_scheme. In direct web-service mode, this will be "https" for a secure connection, or "http" for a non-secure connection. For FastCGI mode, this will be set per the originating server, so may be missing or null; instead of url_scheme, Apache servers set https if the request was over an SSL connection. In CGI mode, no information is available.

Note that cgi properties starting with "http_" are fields from the incoming HTTP heading. So "http_xxxx" properties are whatever the client browser has sent. Properties without an "http_" prefix are provided by the server and are known to be valid.

» form

For example, if the incoming URL is

http://test.webcrossing.com/webx?showForm@@!test=abc&name2=value2

form.test == "abc" and
form.name2 == "value2"

If the same field is input more than once, form.inputField is the last one. Using the last value allows you to set defaults using hidden fields, as in

<input type=hidden name=myCheckBox value=false>
<input type=checkbox name=myCheckBox value=true>

When a post is done in multipart MIME format, you can access the header component of each value through the Mime.formHeader() function.

» user

» newMessages

» location

» locationArray

» site

» topLevelFolder

» session

The properties of a session can only have string values. You can enumerate over these properties.

In order for an incoming request to have the same session as an earlier request, the certificate component of the URL must be the same as for the earlier request. This means that you should dynamically generate all session-linked URLs as

...?command@certificate@...

» certificate

» error

» Object-Oriented Database (OODB)

Discussions contain Messages, which are accessible as either a chronological conversation or a hierarchy of threaded messages.

At the lowest level, there are primitive Stored objects. These are the same as a JavaScript Object, except that they are stored into the database.

All objects stored in the OODB can be accessed through JavaScript objects. Setting new property values for stored objects stores the values into the OODB and saves them on disk. Fetching values from stored objects loads them from disk automatically.

You can create your own kinds of objects derived from the built-in classes, giving you an extremely powerful tool for extending and customizing Web Crossing.

» Defining New Classes of Objects

For example, suppose you wanted to define an "auction item". You decide to derive this from the built-in Node object, because you want auction items to be listed in a folder. So, just define an AuctionItem constructor and its init logic:

function AuctionItem( folder, title, ...){
    // Constructor function for AuctionItem
    // AuctionItem objects inherit from Node
    ...init a new auction-item object as appropriate
}

function init_AuctionItem(){
    // Initialization for the AuctionItem class
    // (called one time at startup because its name starts with "init")

    // AuctionItem objects inherit from Node, accomplished
    // by setting AuctionItem.prototype to be a
    // newUnattached Node object:
    AuctionItem.prototype = Node.newUnattached();
    
    // Set up AuctionItem so that you can derive new object types from it
    AuctionItem.newUnattached = Stored.newUnattached();

    // Other inits for AuctionItem.prototype:
    ...attach default properties and methods to AuctionItem.prototype;
}

var obj = new AuctionItem( folder, title, ... );

Now new AuctionItem objects can use all of the built-in Node and Stored methods and properties, plus all of the default properties and methods that you assign to AuctionItem.prototype.

When a previously created AuctionItem object is referenced, it is automatically loaded from the OODB as necessary, with the correct class.

You can use the same technique to define your own object classes based on any built-in object class: Stored, Node, Folder, Discussion, Message, Chat, Link, or User, as well as the new classes you have defined.

This is an extremely powerful technique for creating new kinds of objects and extending the Web Crossing environment.

» Stored Object

A Stored object can hold any primitive JavaScript data-type: null, strings, numbers, booleans, and Dates, and can also hold other stored objects. (Storing any other kind of object will generate a run-time error.) For example,

var s = new Stored();
s.date = new Date();
s.reminder = form.reminder;
user.reminder = s;

This code will create a new Stored object, save the current date/time and a "reminder" from the input form, and save this into the current user's record. All of this information is available later:

if( user.reminder != null ){
    // Now user.reminder.date is the date the reminder was created
    // And user.reminder.reminder is the reminder message text
    ...process reminder;
}

By default, all non-built-in property values are automatically stored into the OODB. You can specify that some properties are local (not stored at all) or transactional (stored by storedCommit).

Properties and methods	Usage
Stored.lookup( id )	Looks up an existing Stored object and returns it. id is a string which is either a pathname in the OODB folder hierarchy, or the s.storedUniqueId label for some object. This method will return an object with the same type that it was created with, as long as that type is available in your current JavaScript templates. (If the correct type is not available, then the type will be the underlying type of the original object, such as Folder, Node, Stored, etc.) If the object could not be located in the OODB, then returns null and sets error.
Stored.newUnattached()	Returns a new unattached Stored object, suitable for deriving new classes from Stored.
storedIsAttached	Returns true if the stored object is attached to the OODB
storedUniqueId	Returns the uniqueId string for a stored object. This can be used in a later Stored.lookup( id ).
storedDetach()	detaches a JavaScript Stored object from the OODB.
storedConstructor	(read-only) the name of the constructor for the class (from the OODB, so if this class does not exist in the current run-time, then the default base constructor was used)
storedSetConstructor( newType )	Changes the type of an object in the OODB. newType is a string that is the name of the constructor function for the new class. Detaches the old object, and returns an object of the new type.
storedIsLocal( propName )	Returns true if propName is for a local property (e.g. not stored into the OODB).
storedIsTransact( propName )	Returns true if propName is for a transaction-type property (e.g. stored into the OODB on command).
storedIsAuto( propName )	Returns true if propName is for an auto-stored property (e.g. stored into the OODB).
storedMakeLocal( propName )	Makes the specified property to be local
storedMakeTransact( propName )	Makes the specified property to be transaction-oriented
storedMakeAuto( propName )	Makes the specified property to be auto-stored
storedCommit()	Saves all modified transaction-oriented properties into the OODB
storedRollback()	Reverts all transaction-oriented properties to the old value from the OODB
storedIsFolder	Returns true if the stored object is also a Folder
storedIsDiscussion	Returns true if the stored object is also a Discussion
storedIsMessage	Returns true if the stored object is also a Message
storedIsNode	Returns true if the stored object is also a Node
storedIsChat	Returns true if the stored object is also a Chat
storedIsDocument	Returns true if the stored object is also a Document
storedIsLink	Returns true if the stored object is also a Link
storedIsUser	Returns true if the stored object is also a User
storedIsStoredArray	Returns true if the stored object is also a StoredArray
OTHERS	all other property names are user-defined, and are stored in the Web Crossing database (except when specified as local)

» StoredArray Object

A StoredArray object is an array of any primitive JavaScript data-type: null, strings, numbers, booleans, and Dates, and can also hold other Stored objects. (Storing any other kind of object into a StoredArray will convert it to a string and store the string.) For example,

var s = new StoredArray();
s[0] = new Date();
s[1] = form.reminder;
user.tracking = s;

This code will create a new StoredArray object, save the current date/time and a "reminder" from the input form, and save this into the current user's record.

» Node Object

You can create Node objects and place them into Folders, and you can derive your own classes from the Node class.

Properties and methods	Usage
-- Static Functions --
new Node( parentFolder, title )	creates a new node with the specified title. parentFolder can be a Folder object or a pathname string.
Node.lookup( pathname )	returns the object located by the specified pathname. Same as Stored.lookup( id ).
Node.lookupArray( pathname )	returns an array of parents of the specified pathname, with the specified item the last one in the array. The first item in the returned array is always the top-level folder.
Node.lookupMessageId( id )	returns Message object specified by id.
Node.newUnattached()	returns a new unattached Node object, suitable for use as a prototype in a class definition.
-- Properties and Methods--
nodeAuthor	user who posted this location
nodeBackground	background for non-message items (if "", then inherited from its parent) (deprecated - see nodeBodyTag)
nodeBanner	same as nodeHeader.
nodeBodyTag	Background for non-message items (if "", then inherited from its parent). The following path variables are now automatically tied into nodeBodyTag: path.wrap_Background path.wrap_BgColor path.wrap_TextColor path.wrap_LinkColor path.wrap_ALinkColor path.wrap_VLinkcolor path.wrap_BgOther for other kw=value... items All of these path variables are just the value, except for path.wrap_BgOther, which is a series of keyword=value settings, added into nodeBodyTag exactly as is. For example: path.wrap_BgColor = "#000000" path.wrap_BgOther = "onload='...'" will result in a nodeBodyTag of "BGCOLOR=#000000 onload='...'
nodeChildren	(not implemented) Array of child nodes
nodeClearCounts()	clears hits and posts counts for node and all nested items (not for Message).
nodeContentType	content type.
nodeDateCreated	date this location was created
nodeDateModified	date this location was modified
nodeExport(fileName)	export node to fileName (which can be any expression). Will append to an existing file.  Not for Message Item.
nodeFolderItemOther	additional html text following the node's title in a folder listing
nodeFooter	footer (if "", then inherited from its parent)
nodeHeader	banner (if "", then inherited from its parent)
nodeHier(fieldName)	returns user defined node property. Checks all parents. fieldName is a user defined property name.
nodeHits	hits count, not for Message location (read only).
nodeHitsDec()	decrement hits count (calling this function for Message will decrement hits count for its Discussion).
nodeHitsInc()	increment hits count (calling this function for Message will increment hits count for its Discussion).
nodeHostDir()	get/set the host directory mapping for a folder .
nodeHttpDownloads	true iff the node supports Web-based downloads.
nodeHttpDownloadsLocal	true iff Web-based attachments can be downloaded, not for Message object.
nodeHttpUploads	true iff the node supports Web-based downloads.
nodeHttpUploadsLocal	true iff Web-based attachments can be downloaded, not for Message object.
nodeInheritsAttachments	true iff node inherits attachments (not for Message object).
nodeIsTop	true iff node is top level folder (read only).
nodeName	the name of an item in its parent Folder, must be unique in that Folder. Changing this name changes the static-style URL used to reference this object. The default (initial) name for a folder is the same as its title. The default (initial) name for any other kind of folder item is a unique integer. The property is read only for a Message.
nodeNameFullUri	name URI (read only).
nodeNestedHits	nested hits count, not for Message object (read only).
nodeNestedPosts	nested posts count, not for Message object (read only).
nodeNetHasObjectionable	true if node has an objectionable word list or is checking for phone numbers in posts, not for Message object (read only).
nodeNetObjectionable	actual objectionable-word list used for node, not for Message object (read only).
nodeNetObjectionablePhone	true if node is checking for phone numbers, not for Message object (read only).
nodeObjectionable	objectionable word list for the node in the pathname hierarchy, not for Message object.
nodeOwnerDocument	Top-level folder node
nodeParent	parent Folder, or parent Discusson for a Message, or null for the top-level Folder object
nodeParentTitle(level)	parent title at specified level.
nodeParentTitleUrl(level)	URL quoted parent title at specified level.
nodeParentUrl(certificate, level)	parent URL at specified level. certificate is a string that is the certificate for the current user/session.
nodePathname	Full pathname for this node. Each component of the pathname is URL-quoted, separated by "/" delimiters.
nodePosts	posts count, not for Message object (read only).
nodePostsDec()	decrement posts count (calling this function for Message will decrement posts count for its Discussion).
nodePostsInc()	increment posts count (calling this function for Message will increment posts count for its Discussion).
nodeShowAuthor	true to show the author of this location
nodeTemplate	template envelope for this location, not for Message object.
nodeTitle	title of the item. The title is the same as nodeName for Folders. Because a Folder's title must be unique, setting nodeTitle for a folder may not work. For all other Node objects, setting nodeTitle will always work.
nodeTitleUrl	URL quoted (blanks as %20, etc.) title of the item.
nodeUrl	URL for this location, using current session certificate, etc
nodeValue	data for folder/discussion heading, or message body
nodeVirtualArea	true if the node is a virtual area (e.g. backpaths stop with this node)
OTHERS	all other property names are user-defined, and are stored in the Web Crossing database (except when specified as local)
-- Display --
nodeDestroy()	destroys an open folder, discussion, message, chat, or link
nodeDisplay()	constructs the display page for a node. Only used for actual Node objects and user-defined objects derived from Node. The built-in method just calls this.nodeDisplayHeader, this.nodeDisplayContent, and this.nodeDisplayFooter
nodeDisplayHeader(showBanner, showTitle )	constructs the header for a display page for a node. Only used for actual Node objects and user-defined objects derived from Node. The built-in method puts up the initial <HTML> tag and heading, a <BODY> tag, and the standard banner for the page, the title and backpath. showBanner and showToolbar are optional and default to true. If set to false, then the page banner and node title are not displayed.
nodeDisplayContent()	constructs the content area for a display page for a node. Only used for actual Node objects and user-defined objects derived from Node. The built-in method doesn't display anything.
nodeDisplayFooter( showToolbar )	constructs the footer for a display page for a node. Only used for actual Node objects and user-defined objects derived from Node. The built-in method displays <p> followed by the standard footing and closing BODY and HTML tags.  showToolbar is optional and defaults to true. If set to false, then the default toolbar is not added by nodeDisplayFooter.
nodeIcon( extra )	<img...> tag for the default icon for this location. An optional parameter can be specified which is additional text to add to the <img...> tag.
nodeIconFilename	Returns the filename of the icon to use in a folder listing. This is the same icon as returned by nodeIcon, but nodeIcon returns the full <img...> tag.
nodeListItems	true iff node items are to be listed.
nodeMarkAsRead(userObj)	mark node as having been read. userObj parameter is a User object.
nodeMarkAsReadAll(userObj)	mark node and all of its children as having been read. userObj parameter is a User object.
nodeSortSeq	sort sequence in the item's parent folder. Higher numbers are sorted to the top. Not for Message object.
-- Structure --
nodeMoveTo( toFolder )	moves any non-Message object to a new Folder. Returns null if no error, or an error message string.
nodeMoveTreeTo(destFolder)	Move entire node-tree to another Folder. Not for Message item. destFolder is a Folder object where the tree will be moved.
nodeInsertBefore( newChild, refSibling )	(not implemented)
nodeReplaceChild( newChild, oldChild )	(not implemented)
nodeRemoveChild( child )	(not implemented)
nodeAppendChild( newChild )	(not implemented)
nodeHasChildren()	(not implemented)
nodeFirstChild()	(not implemented)
nodeLastChild()	(not implemented)
nodePreviousSibling()	(not implemented)
nodeNextSibling()	(not implemented)
nodeAttachments	list of node's attachments.
nodeAddAttachment( attachment )	Add an attachment to a node object; return value is the attachment object. The parameter attachment may be a document object, the storedUniqueId of a document object, or a MIME container using CRLF line delimiters. Using a storedUniqueId as the parameter permits attaching the same object to more than one node. A MIME container starts with a partial heading that must Content-Type and Content-Transfer-Encoding, and may include other header lines. The heading is followed by a blank line, followed by the data. For example, the following is a short text file attachement: Content-Type: text/plain; name="test.doc" Content-Transfer-Encoding: 8bit This is a text file attachement example body. The following example will take an uploaded file and add it as an attachment to the current location. %% macro showUpload %% %% nop // Display an upload form to add an attachment to the current location %% %% if !location %% No location to upload to. %% return %% %% endif %% Test enclosure uploads. This form will add an attachment to the current location. <p> <FORM name=addDiscussionForm METHOD="POST" enctype="multipart/form-data" %%nop %% ACTION="%% urlBase %%processUpload@%% certificate %%@%% location %%">%%nop%% Attachment: <input type=file name=attachment size=30> <p> <input type=submit value=" Add Attachment "> </FORM> %% endmacro %% %% command processUpload(){ // Process an upload to add an attachment to the current location if( location == null ){ + "No location for the attachment"; return; } if( location == topLevelFolder ){ + "Cannot add the attachment to the top-level folder"; return; } var h = Mime.formHeader( "attachment" ); if( h == null || h.indexOf( 'filename=""' ) > 0 ){ + "No attachment"; return; } var attach = new ByteBuffer(); attach.append( h ); attach.crlf(); attach.crlf() attach.append( form.attachment ); location.nodeAddAttachment( attach ); + "Attachment added"; } %%
nodeRemoveAttachment(attID)	removes attachment.
-- Access Control --
nodeClearAccess()	clears node's access list.
nodeHasAccess	returns true if the node has its own access list. Set this property to true to create an access list if there isn't one already, or to false to remove any existing access list.
nodeHostIds	Host users Ids list (read only property).
nodeHosts(delim)	returns list of Host users names separated by delim
nodeModeratedUserIds	Moderated users Ids list (read only property).
nodeModeratedUsers(delim)	returns list of Moderated users names separated by delim
nodeNoAccessUserIds	No Access users Ids list  (read only property).
nodeNoAccessUsers(delim)	returns list of No Access users names separated by delim
nodeParticipantIds	Participant users Ids list  (read only property).
nodeParticipants(delim)	returns list of Participant users names separated by delim
nodeReadOnlyUserIds	Read Only users Ids list  (read only property).
nodeReadOnlyUsers(delim)	returns list of Read Only users names separated by delim
nodeUserAccess( user )	returns the user access to a node. The returned access is "host", "participant", "moderated", "readOnly", or "none". If the node does not have its own access list, then the parent's access list is used.
nodeSetUserAccess( user, mode )	sets the user access to a node. The access mode can be "host", "participant", "moderated", "readOnly", or "none". If the node does not have its own access list, one is added automatically.
nodeUserCanView( user )	returns true if the user can view this location.
nodeUserCanPost( user )	returns true if the user can post to this location (this will return true even if the user posts are moderated).
nodeUserIsModerated( user )	returns true if the user posts are moderated at this location.
nodeUserIsHost( user )	returns true if the user is a host for this location.

» Folder Object

» Discussion

    http -- posted through a web browser
    stmp -- posted to an inbox from an incoming smtp
email message
    pop3 -- from a mirrored email list, pulled from
the list's pop3 mailbox
    imap -- posted to an imap folder via an imap client
    nntp -- posted via a news client
    local -- created by WCTL or JavaScript scripts 
    direct -- created by a direct-access-protocol request

» Message Object

   http -- posted through a web browser
   stmp -- posted to an inbox from an incoming smtp email message
   pop3 -- from a mirrored email list, pulled from the
list's pop3 mailbox
   imap -- posted to an imap folder via an imap client
   nntp -- posted via a news client
   local -- created by WCTL or JavaScript scripts
   direct -- created by a direct-access-protocol request

» Chat Object

» Link Object

» Document Object

» User Object

» NewMessages Object

» Site Object

» Global Functions and Properties

  a=allowPattern  -or-
    d=denyPattern

(site.siteUrlBase+"abc@"+certificate+"@"+parameter)

makeUrl( "abc" )

(site.siteUrlBase+"abc@"+certificate+"@"+location)

	filterMessageRcpt.length = 0;
	filterMessageRcpt.append( newValue );

	filterMessageIndividual.append( filterMessageFull ).crlf().append( footer );

	% % function emailFilterIndividual(){
		line = new ByteBuffer( "" );
		line.crlf().append( "--emailFilterIndividual--" ).crlf();
		fileAppend( "testLog", line );
		line.length = 0;
		line.append( "--filterMessagePath:" );
		line.append( filterMessagePath ).crlf();
		fileAppend( "testLog", line );
		line.length = 0;
		line.append( "--filterMessageFull:" ).crlf();
		line.append( filterMessageFull ).crlf();	
		fileAppend( "testLog", line );	
		line.length = 0;	
		line.append( "--filterMessageUrl:" ).crlf();
		line.append( filterMessageUrl ).crlf();	
		fileAppend( "testLog", line );	
		line.length = 0;	
		line.append( "--filterMessageIndividual:" );
		line.append( filterMessageIndividual ).crlf();	
		fileAppend( "testLog", line );	
		line.length = 0;	
		var u = Stored.lookup( filterMessageUser );	
		line.append( "--filterMessageUser:" )
		line.append( filterMessageUser );
		line.append( " name:" );
		line.append( u.userName ).crlf();	
		fileAppend( "testLog", line );	
		line.length = 0;	
		line.append( "--filterMessagePath:" );
		line.append( filterMessagePath ).crlf();	
		fileAppend( "testLog", line );	
		line.length = 0;	
		filterMessageIndividual.append( filterMessageFull ).crlf();
		filterMessageIndividual.append( "this is a test" ).crlf();	
	} % % 

  EmailHandler.support = MySupportEmailHandler;
      // Handles all email sent to "support" and "support.xxxx"

  EmailHandler["support.abc"] = function; 

  incoming         matches
    ---------        -----------------
    Support@         support (but not supportx or support_abc)

    support.abc@     support or support.abc (but not support.abcd)
                     If both support and support.abc are present, it
                     matches support.abc

handler( rcptArray, message, from )

%% function loginNotify(){ 
var line = new ByteBuffer(), d = new Date(); 
line.append( d ).append( " login  " );
line.append( loginUserId ).append( " " );
line.append( loginCertificate ).crlf(); 
fileAppend( "testLog", line ); 
}%% 

%%function logoutNotify(){ 
var line = new ByteBuffer(), d = new Date(); 
line.append( d ).append( " logout " );
line.append( logoutUserId ).append( " " );
line.append( logoutCertificate ).crlf(); 
fileAppend( "testLog", line ); } 
%% 

id = queueWctl( "myFunction", 1000 )

%% function testQueueStart(){
    // queue testQueueWctl to run in 1 second
    queueWctl( "testQueueWctl", 1000, "abc" );
} %%

%% macro testQueueWctl %%
    %% // queue WCTL macro, just calls a JS function %%
    %% "testQueue".jsEval %%
%% endmacro %%

%% function testQueue(){
    // Just appends the first parameter to testFile
    fileAppend( "testFile", queueWctlParam( 0 ) );
} %%

» Helper Objects

There are also some extensions to standard JavaScript objects to assist with server-side operations.

» ByteBuffer Object

A ByteBuffer is used for the output response buffer, but these objects can also be created and used for other purposes. The ByteBuffer object only uses one byte per character in the output string and allows you to append to the buffer object. By contrast, the standard JavaScript string object catenates strings and thus requires a memory allocation for each catenation. The ByteBuffer allocates a larger buffer and simply adds characters to it, doing a reallocation only when the buffer space overflows. As a result ByteBuffers are dramatically more memory- and performance-effective and thus preferred for significant string-handling operations.

Properties and methods	Usage
-- new ByteBuffers --
new ByteBuffer()	Creates a new empty ByteBuffer
new ByteBuffer( initialValue )	Creates a new ByteBuffer whose initial value is as specified.
-- length --
length	(read/write) the current length of the ByteBuffer
-- string compares, NOT case sensitive --
eqNc( obj )	returns true if the obj string of ByteBuffer is equal
ltNc( obj )	returns true if the obj string of ByteBuffer is less-than obj
leNc( obj )	returns true if the obj string of ByteBuffer is less-than-or-equal obj
gtNc( obj )	returns true if the obj string of ByteBuffer is greater-than obj
geNc( obj )	returns true if the obj string of ByteBuffer is greater-than-or-equal obj
neNc( obj )	returns true if the obj string of ByteBuffer is not-equal obj
-- string compares, case sensitive --
eq( obj )	returns true if the obj string of ByteBuffer is equal
lt( obj )	returns true if the obj string of ByteBuffer is less-than obj
le( obj )	returns true if the obj string of ByteBuffer is less-than-or-equal obj
gt( obj )	returns true if the obj string of ByteBuffer is greater-than obj
ge( obj )	returns true if the obj string of ByteBuffer is greater-than-or-equal obj
ne( obj )	returns true if the obj string of ByteBuffer is not-equal obj
-- access --
byteAt( ix )	number
charAt( ix )	string
substring( ix [, count] )	string
subString( ix [, count] )	same as substring
subBuffer( ix [, count] )	ByteBuffer
duplicate()	returns a copy of the ByteBuffer
-- modify/parse --
append( data, ix, count )	appends a string to the ByteBuffer, and returns the modified ByteBuffer. ix and count are optional and pick a substring of the data. ix defaults to 0, count defaults to the rest of the input data.
appendByte( number )	appends a character where "number" is the numeric value of the character, and returns the modified ByteBuffer
emailGetAddress( )	returns returns the email address portion of an email list entry (see emailHead()). For example: "Test User ".emailGetAddress() --> "test@test.com"
emailGetUsername( )	returns returns the username portion of an email list entry (see emailHead()). For example: "Test User ".emailGetUsername() --> "Test User"
emailHead( )	returns the next full entry from a list of email addresses (as in the From and CC fields of an email message) and removes it from the ByteBuffer
head( [delimiter] )	returns ByteBuffer to left of delim (default is space), removes the head and delimiter from the buffer
insert( ix, obj )	inserts obj.toString() at "ix", sliding the character at "ix" and all following characters down to make room, and returns the modified ByteBuffer
insertByte( ix, number )	insterts a single character at "ix", and returns the modified ByteBuffer, slides down following bytes
newValue( obj )	sets the ByteBuffer to a new value, and returns the modified ByteBuffer
none()	returns NULL (used to have a series of appends, etc evaluate to NULL
popKeyword()	finds the first keyword in the byteBuffer, returns it as a string, and removes the keyword and its trailing delimiter. Delimiters between keywords are commas, semicolons, and white space. Leading/trailing whitespace is skipped. For example, if the byteBuffer is " key1, key2", the call to popKeyword() will return the string "key1" and set the byteBuffer to "key2".
remove( ix [, count] )	removes characters from ix through ix+count-1, and slides the following characters up. Returns the modified ByteBuffer
set( ix, obj )	sets the character at "ix", and returns the modified ByteBuffer. Uses first character of obj.toString(), or is a no-op if obj is a 0-length string
setByte( ix, number )	sets the character at "ix" where "number" is the numeric value of the character to store, and returns the modified ByteBuffer
stripEdges()	removes leading and trailing whitespace and control characters and returns the modified ByteBuffer
tail( [delimiter] )	returns ByteBuffer to right of delim (default is space), removes the tail and delimiter from the buffer
toLowerCase()	converts ByteBuffer to all lower-case, returns the modified buffer
toUpperCase()	converts ByteBuffeer to all upper-case, returns the modified buffer
translate( mapByteBuffer )	remaps ByteBuffer, each char in ByteBuffer is replaced by mapByteBuffer( byteAt[ix] )
-- URL and SGML quoting --
toUrl()	converts the ByteBuffer to be URL-quoted and returns the modified buffer
fromUrl()	converts the ByteBuffer to be URL-dequoted and returns the modified buffer
toSgml()	converts the ByteBuffer to be SGML-quoted and returns the modified buffer
fromSgml()	converts the ByteBuffer to be SGML-dequoted and returns the modified buffer
-- hashing --
toMD5()	calculates the MD5 hash of the ByteBuffer and returns the modified buffer
-- character appends --
crlf()	append carriage return, line-feed characters (CR/LF are the standard Internet end-of-line)
cr()	append a CR character
lf()	append a LF
newline()	append a host-specific end-of-line (for writing local files)
-- lookup --
indexOfNc( obj [, ix [, count]] )	not case sensitive, returns start index or -1
indexOf( obj [, ix [, count]] )	case sensitive, returns start index or -1
lastIndexOfNc( obj[, ix [, count]] )	not case sensitive, returns last start index or -1
lastIndexOf( obj[, ix [, count]] )	case sensitive, returns last start index or -1

» Date Object

For example,

date.format("Www, D2 Mmm Y4 H4:I2:S2 G$MTtoutc")

"Tue, 16 Feb 1999 13:06:05 GMT-0700"

Format specifier	Usage
Y2	2 character year
Y4	4 character year
M1	1 or 2 digit month
M2	2 digit month
M3	2 digit month, leading blank instead of 0
MMM	3 character month, all caps
Mmm	3 character month, leading cap
M	full month name, leading cap
D1	1 or 2 digit day of month
D2	2 digit day of month
D3	1st, 2nd, 3rd, 4th...
D4	2 digit day of month, leading blank instead of 0
WWW	3 character day of week, all caps
Www	3 character day of week, leading cap
W	full day of week, leading cap
H1	1 or 2 digit hour, 12 hour clock
H2	2 digit hour, 12 hour clock
H3	1 or 2 digit hour, 24 hour clock
H4	2 digit hour, 24 hour clock
H5	2 digit hour, 24 hour clock, leading blank instead of 0
I1	1 or 2 digit minutes
I2	2 digit minutes
S1	1 or 2 digit seconds
S2	2 digit seconds
L1	1, 2, or 3 digit milliseconds
L2	3 digit milliseconds
A	AM/PM, upper case
a	am/pm, lower case
toutc	delta from local time to GMT/UTC, as +HHMM or -HHMM
$c	escape to embed any character "c" into the output string

» String Object

» MIME Processing

» Remote Procedure Calls

Note: in order to support XML-RPC, Web Crossing must be providing direct Web service. You can not pass XML-RPC calls through CGI or FastCGI interfaces.

Remote procedure calls (RPCs) allow client programs to make calls to your Web Crossing server, with your server using the appropriate JavaScript functions to process these calls.

You can also make remote procedure calls from Web Crossing's server-side JavaScript to any RPC-based server.

This remote-procedure-call mechanism uses normal HTTP requests and responses, with special XML-based formatting of the body of the message to pass parameters and receive the returned value. All of the XML-RPC machinery is handled by Web Crossing, so you don't need to know the format of these calls to use it in Web Crossing.

» Calling Remote Procedures

rpc( url, function, p1, p2... ) -or-
rpcTimeout( url, function, p1, p2..., timeoutSecs )

where:

url	is the URL of the server that is going to process the procedure call. This can be a server address only (e.g. webcrossing.com), or it can be a full URL, including the remote pathname (e.g. http://webcrossing.com/RPC2). If the remote pathname is omitted, then /RPC2 is used, so specifying just a server address is the same as http://serveraddress/RPC2. To use SSL for the RPC connection, you must be running an SSL-enabled Web Crossing server, and specify https in the URL. For example, https://webcrossing.com/RPC2 would use HTTPS instead of HTTP. The default port for HTTPS is 443 and the default port for HTTP is 80. The default timeout to receive a response from the server is 10 seconds. Use rpcTimeout to specify some other timeout.
function	is the name of the remote function, such as mainResponder.discuss.newMessage.
p1, p2...	are optional parameters. Primitive values (strings, numbers, Dates) are passed exactly, except that null is passed as an empty string. ByteBuffers are passed as strings. Arrays are passed as arrays of values. All other objects are passed as primitive Objects, with all their enumerable properties passed to the remote procedure.
returns	the object passed back from the remote procedure. Returned values use the same rules as for sending parameters to the remote procedure. So returned values can be primitive values, or can be JavaScript Arrays or Objects. Any error in the call, or in the remote processing, will return a Fault object. This object has properties faultCode, a numeric error code, and faultString, a descriptive error message.

» Processing Remote Procedure Calls

To enable a function for RPC processing, just set

myFunction.rpcEnable = true;

The rpcEnable property can be either a boolean or a function. If this property is a function, then this rpcEnable function is called prior to executing the XML-RPC function, with the first parameter the function name and the following parameters the same as the XML-RPC function. The rpcEnable function can return one of the following:

true	then the normal XML-RPC processing is done
false	a "not enabled" fault is returned
other	returned to the caller instead of calling the normal XML-RPC function (e.g. "short-circuits" the normal XML-RPC call)

You can return a Fault object if you detect some error in the request or during processing. To return a fault, just use

return new Fault( errCode, errMsg );

where errCode is a numeric error code (there is no standard, you just make them up for your usage), and errMsg is a descriptive error message.

Checking the incoming request

» Examples

%%
function testAdd( a, b){
    // The RPC function: it just adds two numbers and returns the result
    return a + b;
}
command testRpc(){
    // The test function: it makes a remote procedure call to testAdd()
    var ret = rpc( cgi.http_Host/*self*/, "testAdd", 1, 2 );
	if( ret == "[object Fault]") {
		+ ret.faultString;
	} else {
   		+ "Should say 3: " + ret;
   	}
}
function init_testAdd(){
    // An init function: it enables testAdd to process RPC calls
    testAdd.rpcEnable = true;
}
%%

To invoke the test function, copy this to your standard.tpl file, reset the webx.tpl cache, and use the URL

...webx?testRpc

where ...webx is the access to your Web Crossing server.

A Second XML-RPC Example - Checking a User's Existence at a Remote Site

This XML-RPC example queries another Web Crossing site to see if a user with the same user name as the current user exists there or not.

The results are shown here (a folder at the Web Crossing Education Center). Try it! If you are logged in to the Education Center and also registered at WebX Harbor (under the same userName) then the folder header will report that a user with the same name as you is also at WebX Harbor. Otherwise it will report that your name was not found at the remote server.

Contents of the Folder Header

The folder header contains a call to a local WCJS function, remoteUserQuery(): %% "remoteUserQuery()".jsEval %%

This function calls a function at WebX Harbor. That remote function returns the boolean value true or false depending on whether or not the user is there.

remoteUserQuery

The function remoteUserQuery() (see below) uses the WCJS rpc command to call the function remoteUserRespond() at WebX Harbor.

The current user's name is passed as a parameter to remoteUserRespond.

remoteUserRespond

Meanwhile, on the WebX Harbor site, the function remoteUserRespond (below) receives the remote procedure call and checks to see if the user exists or not. If the user exists, true is returned. Otherwise false is returned. In either case, a record of the rpc call is logged to a file, logxmlrpc.

Note that init_remoteUserRespond sets the .rpcEnable property of the remoteUserRespond function - otherwise it would not be able to receive XML-RPC calls.

The Results

When user doug visits the folder he sees this result, because he (or at least somebody with his name) is registered at WebX Harbor.

However, when Pia Zadora takes a break from her singing career to visit the same folder, she is told that no user with her name exists at WebX Harbor.

Meanwhile, at WebX Harbor, this log is retained to keep track of the remote calls to remoteUserRespond().

Third Example - A Form-based XML-RPC Client

Web Crossing can act as both an XML-RPC server and client. The code sample here can be used to create your own handy XML-RPC Client with a form interface. This is useful for testing XML-RPC functions on various servers.

Calling rpcClient

You can "rpcClient".jsEval or call the command from a URL, using the standard Web Crossing URL command syntax. The Client looks like this (with some sample data):

You can have any number of arguments, separated by commas.

What rcpClient Returns

Here is what rpcClient returns using the sample data in the previous message.

The returned value's typeOf and value are given.Return values of boolean, string, number, Array and any Object are reported. Arrays of Object types are also supported.

The Source Code for rpcClient

Here is the source code. A few notes:

• rpcClientProcess receives the data from the form, builds an rpc call command depending on the number of arguments, reports the results and calls rpcClient again to allow input of another form.
• rpcClientForm is the Client form innards.
• rpcClient can be called directly to use the Client form.
• Our friend, the RegExp (regular expression) is used when splitting the arguments into an array: form.rpcArgs.split(/\s*,\s*/). This allows us to delimit each argument by commas separated by any amount of white space.
• The JS eval command is used to evaluate the rpc command string created.

» External Databases (Oracle, etc.)

Using an external database requires a working knowledge of SQL, which is not covered in this document. If you need to learn SQL, get a copy of Sql in a Nutshell by Kline and Kline, which is a good introduction and covers most common usage.

» db Object

You start by creating a new db object and using connect to open a connection to the external database. You can check to see whether a db is connected by using the connected method.

To access/update the db, use execute to execute arbitrary SQL statements, insert to insert rows, delrow to delete rows, and update to update database rows. You can use rowsprocessed to tell how many rows were affected by these operations.

The db supports a cursor to access the results of database SELECT operations. Use cursoropen to create a new cursor control structure, cursor to issue a SELECT statement to fill the cursor with row data, columns to find out how many colums are in the current selection, nextrow to iterate over selected rows, nextcol to iterate over columns in the currently selected row, and cursorclose to close the cursor control structure when you are through with it. You can get information about the columns in a cursor through colnumforselect to get the number of columns that will be returned by a SELECT operation and colname to iterate over column names for a select operation.

You can get information about the database through colnum to get the number of columns in a table, colname to iterate over column names in a table, and colattr to iterate over column attributes for a table.

To control transactions and rollback, use begintrans to start a transaction, endtrans to end a transaction, and either commit to make the changes in the previous transaction or rollback to cancel it. You can also use autocommit to control autocommit mode (normally off).

Error checking is done through errorcode to get the error code for the most recent operation, errormessage to get the error message, errorsqlstatement to get the most recent SQL statement, and errorvarinfo to get the most recent SQL variable information (if supported by the external database).

When you are through with a database connection, use disconnect to close the connection.

Methods	Usage
new db	Creates a new db object.
mydb.autocommit()	Turns on autocommit mode. Using this function will automatically commit every transaction within the scope of the running JS script. autocommit is turned off by default. Generally speaking, you don't want to commit transactions, especially a large group of transactions, if one those transactions happens to fail. If autocommit is called, it will nullify the functionality of begintrans/endtrans. Typically, transactions are committed explicitly, thus allowing for rollback in the event of an error or undesired transaction result. Returns true on success, false on failure.
mydb.begintrans()	Starts a transaction, a series of related operations on the external database. You must call mydb.endtrans() to end the transaction.
mydb.colattr( table, columName, attrType )	Returns the attribute description for a column in a table. attrType can be 0 or 1.
mydb.colname( tableOrSqlSelectStatement )	Returns column names for a table or select operation, in order until all columns have been returned, then returns the empty string. For example, employeesNames = new Object; for( i = 0; i < mydb.colnum( "employees" ); i++ ){ employeesNames[i] = mydb.colname( "employees" ); }
mydb.colnum( table )	Returns the number of columns in a table.
mydb.colnumforselect( sqlSelectStatement )	Returns the number of columns that will be returned by a SELECT statement. For example, cols = mydb.colnumforselect( "select * from employees" );
mydb.columns()	Returns the number of columns in the current cursor selection.
mydb.commit()	Commits changes from the previous transaction to the database. Returns true if committed successfully, false if not.
mydb.connect( "connectionString" )	Connect to the database. For example, if( !mydb.connect( "scott/tiger" ) ){ + "database connection failed: " + mydb.errormessage(); return false; } Returns true on success, false on failure.
mydb.connected()	Returns true if connected, false if not.
mydb.cursor( sqlSelectStatement )	Fills in a cursor data structure with the results of a select statement. For example, mydb.cursor( "Select * from employees" ); Returns true if the select was successful, false if not.
mydb.cursorclose()	Closes a cursor and releases the memory allocated for it. Returns true if the cursor close was successful, false if not.
mydb.cursoropen()	Allocates a cursor data structure for subsequent cursor operations. Returns true if the cursor open was successful, false if not.
mydb.delrow( sqlDeleteStatement )	Deletes rows of data from a database. For example, mydb.delrow( "delete from employees where empno > 85" ); Returns true if updated successfully, false if not.
mydb.disconnect()	Disconnect from the database. Returns true on success, false on failure.
mydb.endtrans()	Turns on autocommit mode. Ends a transaction. You must call commit or rollback after you call endtrans.
mydb.errorcode()	Returns the error code for the last operation.
mydb.errormessage()	Returns the error message for the last operation. If an empty string is returned, then the last operation executed correctly.
mydb.errorsqlstatement()	Returns the last SQL statement executed.
mydb.errorvarinfo()	Returns the variable information for the last SQL statement. This function is db-vendor dependent, and is not usually implemented by the vendor.
mydb.execute( sqlStatement )	Execute an SQL statement. For example, mydb.execute( "drop table whatever" ); Returns true if the statement was executed successfully, false if not.
mydb.insert( table, columnNames..., values... )	Inserts a row of data into a table. For example, mybd.insert( "employees", "empno", "ename", "job", 200, "john smith", "freelance" ); Returns true if inserted successfully, false if not.
mydb.nextcol()	Returns the value of the next column in the current row in the current cursor selection.
mydb.nextrow()	Advances to the next row in the current cursor selection. Retuns true if another row was available, or false if not.
mydb.rollback()	Explicitly discards changes from the previous transaction. Returns true if rolled back successfully, false if not.
mydb.rowsprocessed()	Returns the number of rows affected by the previous SQL operation.
mydb.update( sqlUpdateStatement )	Updates rows of data. Returns true if updated successfully, false if not.

» Example

// Create a new database object
print ("creating new db object");
var my_db = new db;

my_db.connected();

// try and connect with a bad login

my_db.connect("bad/login");

// see what errors came from a bad connection

my_db.errorcode();
my_db.errormessage();
my_db.errorsqlstatement();

// automatically commit every db transaction - by DEFAULT
transactions must be committed explicitly
// NOTE turning this on autocommits everything!! for the duration of
the JS script running
// and nullifies the functionality of
// begintrans() and endtrans() with explicit commit and rollback,
similar to SQL*Plus
// hence the reason it is TURNED OFF by default and must be
explicitly turned on

if (my_db.autocommit())
     print ("autocommit set ");

my_db.connect("scott/tiger");
if (my_db.connected())
      print("scott/tiger connected");

my_db.errorcode();
my_db.errormessage();
my_db.errorsqlstatement();

my_db.execute("drop table whatever");

my_db.errorcode();
my_db.errormessage();
my_db.errorsqlstatement();

my_db.execute("create table whatever (f1 number, f2
varchar2(60), f3 varchar2(255), f4 varchar2(10))");

In this example, pass in the name of the table:

my_db.colnum("whatever");

my_db.colnumforselect("select f2,f3 from whatever");
my_db.colnumforselect("select * from whatever");

my_db.delrow("delete from bob where f1 > 85");
my_db.errorcode();
my_db.errormessage();
my_db.errorsqlstatement();

my_db.rollback();

my_db.delrow("delete from data_types where col5_int > 85");
my_db.errorcode();
my_db.errormessage();
my_db.errorsqlstatement();

my_db.rowsprocessed();

// Step through the column names via a loop

print ("columns from table emp with a loop");
print ("======================");
for (i=0; i <= my_db.colnum("emp"); i++)
{
    mycol=my_db.colname("emp");
    // print(my_db.colattrib("EMP", mycol, 0));
    print ("my col = "+mycol);
}

// Step through the column names on single lines

print ("columns from table emp with single calls");
print ("======================");
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print(my_db.colname("emp"));
print("");

my_db.colattrib("EMP", "EMPNO", 0);
my_db.colattrib("EMP", "EMPNO", 1);

my_db.cursoropen();
my_db.cursor("Select bad_column from emp");

if (my_db.errorcode() == 0)
{
     print("in cursor select ");
     print(my_db.columns());
// my_db.nextrow()

     my_db.cursorclose();
}
print ("error messages from bad cursor")
print(my_db.errorcode())
print(my_db.errormessage())

my_db.cursoropen();
my_db.cursor("Select * from emp");

print(my_db.errorcode())
if (my_db.errorcode() == 0)
{
     print("Column Names");
     for (i=0; i <= my_db.columns(); i++)
     {
        mycol=my_db.colname("emp");
        print (mycol);
     }

     while (db.nextrow())
     {
        for (i=0; i <= my_db.columns(); i++)
        {
           mycol=my_db.nextcol(i);
           print (mycol);
        }
     }
     my_db.cursorclose();
}

my_db.disconnect();

my_db.connect("scott/tiger");
if (my_db.connected())
      print("scott/tiger connected");

my_db.begintrans();

      my_db.insert("emp","empno","ename","job",200,"jeff kent","freelanc");
      my_db.insert("emp","empno","ename","job",200,"rod kent","coder");
      my_db.insert("emp","empno","ename","job",200,"davejones","manager")

my_db.endtrans();

my_db.rollback();

// my_db.insert("emp","empno","ename","job",200,"jeff
kent","freelance");
// print(my_db.errorcode())
// print(my_db.errormessage())

// bad insert - will generate an error

     my_db.insert("bad_table","empno","ename","job",20000,"Tim Lundeen","CEO");
     print(my_db.errorcode())
     print(my_db.errormessage())

// the errorcode since it will be the errorcode from the last db transaction
// in a loop you'd want to do this programmatically, i.e. after every db
// transaction, check error code, if it err'd and you were using begin/end
// then you'd roll back  and immediately exit the loop

my_db.endtrans();
my_db.rollback();  // rollback all the inserts

// insert data in to a row in a loop - hacked JS interpreter
doesnt handle it correctly
// only iterates through the loop 1X
for (i=0; i <= 10; i++)
{
     my_db.insert("emp","empno","ename","job","mgr",200,"johndoe","geek",100);
     print(my_db.errorcode());
     print(my_db.errormessage());
}
my_db.commit();

print ("number of rows in table emp");
print ("===========================");
my_db.rownum("emp");