9 Server-Side

Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

This chapter is a detailed reference of all the items and elements making up the server-side JavaScript language. This refers to the implementation available in the Netscape and iPlanet Web Server Enterprise Edition, which we will simply refer to as Enterprise Server (ES) from this point on, and within Microsoft's Active Server Pages (ASP) environment, which is available for their Internet Information Server (IIS) or Personal Web Server (PWS).

Because both Microsoft and Netscape have taken different approaches for their server-side implementation, be sure to check the supported environments for these entries. Additionally, be sure to read Chapter 5, "JavaScript on the Server-Side," for more information on how these implementations are used.

As in other chapters of Part III, the details of the language are covered in this chapter. Each entry includes the language version, syntax, description, and an example of each server-side–specific language element.

The chapter is in alphabetical order, by JavaScript objects, to provide you with quick, easy access to the methods, properties, functions, and event handlers of every server-side object. These appear alphabetically after the respective parent object using simple dot notation.

addClient()

ES2+

Syntax

addClient(URL)

Description

The addClient() function is a top-level function that is not associated with any core object. This function is used to preserve the property values of a client object when you generate dynamic links or use the redirect() function. The addClient() function takes a URL as its only parameter.

Example

This example demonstrates how you can use the addClient() function when dynamically building links. In Listing 9.1, a link is built by using a property of the project object.

Listing 9.1 Using the addClient() Function to Dynamically Build a Link

<a href='<server>addClient("/myApp/page" +
project.pagenum + ".html")</server>'>
Please proceed to the next page</a>

In Listing 9.2, the addClient() function is used in conjunction with the redirect() function. This will send the user to the URL specified in the addClient() function.

Listing 9.2 Using the addClient() Function with the redirect() Function

<server>
// Check to see if the browser is Internet Explorer.
if(request.agent.indexOf('MSIE') != -1){
redirect(addClient("/iepages/index.html"));
// Redirect to another page if it is not IE.
}else{
redirect(addClient("/defaultpages/index.html"));
}
</server>

addResponseHeader()

ES3+

Syntax

addResponseHeader(key, value)

Description

The addResponseHeader() function is a top-level function that is not associated with any core object. This function is used to add fields and values to the HTTP header sent back to the client. Because of when the actual header is sent in relation to the body of the data, you should be sure to set these fields and values before you call the flush() or redirect() functions.

Example

Listing 9.3 shows how you can send back a dynamically built external JavaScript source file to a browser with the proper content-type header field and value.

Listing 9.3 Using the addResponseHeader() Function to Set the content-type of a File Being Sent to a Browser

<server>

// Add a field to the header
addResponseHeader("content-type", "application/x-javascript");
</server>

Application

ASP1+

Syntax

Core ASP environment object

Description

The Application object is a core ASP environment object. It is used to share information across all users of a given application, which includes all .asp files as well as any virtual directories and their subdirectories. Table 9.1 contains the methods, collections, and events of this object.

Table 9.1 Methods, Collections, and Events of the Application Object

The ASPError object is a core ASP environment object. Its properties and methods are used to retrieve information about errors that have occurred on a given page. This object is returned by the Server.GetLastError() method and exposes read-only properties. Table 9.2 contains a list of properties for this object.

Table 9.2 Properties of the ASPError Object

BLOB data represents binary large objects that can be stored in a database. This allows you to store various types of information, such as images, movie files, and sounds in the database.

Note
Be sure to consult the documentation on your specific database to see whether there are any limitations to BLOB data types.

The blob() function is used to store BLOB data in your database. This function takes the path to a BLOB file as its only parameter. Note that this path must be an absolute pathname and not a relative one.

Example

In Listing 9.23, a cursor instance has been created to perform a query on the database to find a specific row. Focus is then placed on that row and the blob() function is used to assign the data to a column. The final step in the process is to use the updateRow()

method to commit the change.

Listing 9.23 Using the blob() Function to Insert BLOB Data into a Database

<server>

// SQL statement and instance of a cursor to execute it
var myStatement = 'SELECT * FROM family WHERE pic = null';
var myCursor = database.cursor(myStatement);

// Iterate through the returned rows.
while(myCursor.next()){

// Assign 'blank.gif' in the PIC column of the returned rows.
myCursor.pic = blob("/pictures/blank.gif");
myCursor.updateRow("family");
}

// Close the cursor and write it to the page if there was an error.
var dbError = myCursor.close();

if(dbError) write(myCursor.close());
</server>

blob (Object)

ES2+

Syntax

Core object is created with the blob.blobImage() and blob.blobLink() methods.

Description

The top-level blob object contains methods that allow you to store and retrieve blob data in a database. BLOB data represents binary large objects that can be stored in a database. This allows you to store various types of information, such as images, movie files, and sounds in the database.

The core blob object is created when you use the methods of this object. Table 9.3 has the methods of the blob object and a description of what they do when invoked.

Table 9.3 Methods of the blob Object

Example

Listing 9.24 queries a database for a specific image, creating an instance of a blob object when retrieved. The image is then written to the page using the write() and blobImage() methods. The actual tag written will be as follows:

Listing 9.24 Using the blobImage() Method to Format an <img= Tag

<server>

// Find the image you want to display.
myCursor = myConn.cursor("SELECT path FROM images WHERE img = 1");

// Write the <img> tag to the page with the following attributes set.
write(myCursor.path.blobImage("gif", "Click", "left", 468, 60, 0, false)); // Close the cursor.
myCursor.close();
</server>

blob.blobImage()

ES2+

Syntax

cursor.column.blobImage(fileType, altText, align, width, height, border, ismap)

Description

The blobImage() method retrieves and displays a BLOB image stored in a database. The method actually returns the HTML for the <img> tag used to display the image. The href attribute of the <img> tag references the instance of this image in memory and does not have to contain a “normal” URL of the image itself.

This method can take up to seven parameters that set the various attributes of the <img> tag. These attributes are contained in Table 9.4. At a minimum, you must pass the fileType of the image.

Table 9.4 Properties That Can Be Set with the blobImage() Method

Example

Listing 9.25 queries a database for a specific image. The image is then written to the page using the write() and blobImage() methods. The actual tag written will be as follows:

Listing 9.25 Using the blobImage() Method to Format an <img> Tag

<server>
// Find the image you want to display.
myCursor = myConn.cursor("SELECT path FROM images WHERE img = 1");

// Write the <img> tag to the page with the following attributes set.
write(myCursor.path.blobImage("gif", "Click", "left", 468, 60, 0, false));

// Close the cursor.
myCursor.close();
</server>

blob.blobLink()

ES2+

Syntax

cursor.column.blobLink(mimeType, text)

Description

The blobLink() method retrieves BLOB data stored in a database, stores it in memory, and creates a temporary link to it. The method actually returns the HTML for the <a> tag used to display the link. The href attribute of the <a> tag references the BLOB data type, which has been stored in a temporary memory location, and does not contain a “normal” URL of this attribute. The data is stored in memory until the user clicks the link or until 60 seconds have elapsed.

The parameters this method takes are the MIME type of the file referenced, and the text that is displayed to the user as a link.

Example

Listing 9.26 queries a database for a specific image. A link referencing the image is then written to the page using the write() and blobLink() methods. The actual tag written will be as follows:

<a href="LIVEWIRE_TEMP1">Click Here!</a>

Listing 9.26 Using the blobLink() Method to Format an <a> Tag

<server>

// Find the image you want to display.
myCursor = myConn.cursor("SELECT path FROM images WHERE img =1");

// Write the <a> tag to the page with the attributes set.
write(myCursor.path.blobLink("image/gif=, "Click Here!"));

// Close the cursor.
myCursor.close();
</server>

callC()

ES2+

Syntax

callC(JSFuncName, arg1, arg2, …, argN)

Description

The callC() function, which returns string values, is a top-level function that is not associated with any core object. callC() is used to call a JavaScript function that references a C function in a shared library. These libraries are the pre-built .dll files on Windows machine and .so files on Unix machines. callC() takes the JavaScript name you have assigned to the C function and any arguments the function needs as arguments.

Before you can call this function, you must register the C library using the server-side JavaScript registerCFunction(). RegisterCFunction() takes the JavaScript name with which you want to reference the function, the path to the library, and the C function name as parameters.

Example

Listing 9.27 registers an external C library, extlib.dll, that contains a function named getMyDate. The registration of this function assigns the name JSExtLib to be used within the script. If the function successfully registers, the callC() function is used to call the C function and pass it two parameters. The results are written to the user’s page. If the function does not register properly, an error is written to the user’s page.

Listing 9.27 Using a C Function with callC That Has Been Registered

<server>

// Register the library and function, assigning it a JavaScript
// function name.
var myExternalLib = registerCFunction("JSExtLib", "c:/winnt/extlib.dll",
"getMyDate")
// If the library registered without error, then call it using the
// callC function. If it failed, then write an error to the page.
if (myExternalLib) {
write(callC("getMyDate", 1999, 2000));
}else{
write("There was an error processing this external library function");
}

</server>

client

ES2+

Syntax

Core object is created with each connection of a client to your application.

Description

An instance of the client object is created with each connection of a user to your application. This object is used to maintain session variables for that user as she moves through your application’s pages. Because the object is not created until a user connects to your application, you cannot use the object on the first page of your application.

Note
The client object is created for each user’s connection to each application you have built using Server-side JavaScript, so a single user connected to two applications will have two client objects created.

The object itself is held until the user is inactive for a set period of time or the object is destroyed. At that time, the JavaScript runtime engine cleans up the object. The default timeout is ten minutes, but this can be changed by using the expiration()

method or can be destroyed manually by using the destroy() method.

client objects do not have any default properties, but properties can be created for them. Do note that because of the method used to maintain user sessions, these properties are all converted to strings. If you have created a property that must be evaluated as a numeric value, use the parseInt() and parseFloat() methods for processing.

If you must store an object as a property, you will have to create an array of objects in the project or server objects. Then you can create a property to hold the index of your object in the client object.

Example

Listing 9.28 contains a form the user fills out with her name, e-mail address, and phone number. When the Submit button is clicked, the form is sent back to itself and the script sees information being passed in. This information is then assigned to three created properties of the client object and is then written to the user’s page.

Listing 9.28 Assigning Properties to the client Object

<html>
<head>
<title>Using the client object</title>
</head>
<body>
<server>

// See if they have submitted or just need the form.
if(request.method == "POST"){

// Assign the client properties their values.
client.name = request.name;
client.email = request.email;
client.phone = request.phone;

// Write the user's information to the page.
write('Hello ' + client.name + '!<br>'),
write('Please confirm your email, ' + client.email + ', and '),
write('phone number, ' + client.phone);
}else{

// If this page was called and a form was not submitted
write('<form name="myForm" method="post">'),
write('<table border="1"><tr><td>'),
write('<table border="0">'),
write('<tr align="left" valign="top">'),
write('<td><b>Name:</b></td>'),
write('<td><input type="text" name="name" size="30"></td>'),
write('</tr>'),
write('<tr align="left" valign="top">'),
write('<td><b>E-mail:</b></td>'),
write('<td><input type="text" name="email" size="30"></td>'),
write('</tr>'),
write('<tr align="left" valign="top">'),
write('<td><b>Phone:</b></td>'),
write('<td><input type="text" name="phone" size="30"></td>'),
write('</tr>'),
write('<tr align="left" valign="top">'),
write('<td colspan="2" align="right"><input type="submit"'),
write(' value="Submit"></td>'),
write('</tr>'),

write('</table>'),
write('</td></tr></table>'),
write('</form>'),
}
</server>
</body>
</html>

client.destroy()

ES2+

Syntax

client.destroy()

Description

The destroy() method of the client object explicitly destroys that instance of the object and all its associated properties. If this method is not called, the JavaScript runtime will destroy the object after 10 minutes or after the time specified with the client.expiration() method.

If you are using cookies to maintain your client object, calling the destroy() method acts in the same manner but does not remove information stored in the browser’s cookie file. To remove the cookie information, set the expiration to 0 seconds by using the client.expiration() method.

When using URL encoding to maintain the client object, the destroy() method will destroy all information with the exception that the links created before the method call will retain their properties. Because of this, good programming practice warrants calling the method at the top or bottom of a page.

Example

Listing 9.29 shows how to destroy the properties of your user’s client object.

Listing 9.29 Using the destroy() Method to Destroy the client Object Properties

<server>

// Destroy the client properties.
client.destroy()

</server>

client.expiration()

ES2+

Syntax

client.expiration(seconds)

Description

Description

The Connection object represents a given connection, pulled from a “pool”, to a database. This object has only one property, the prototype property, which you can use to add properties to the object. Table 9.5 shows the methods associated with this object.

Note
If you only need a single connection to the database and do not need to create a pool, use the database object for your connection.

Table 9.5 Methods of the Connection Object

Example

Listing 9.34 creates a pool of connections to an Oracle database and initializes a connection from that pool. It takes a user’s UID and name that was passed in, runs a query (based on the UID) against the database to find that user’s information, and updates the user’s name. If a connection is not made, the error code and message is returned to the screen.

Listing 9.34 Creating and Using a Connection Object

connection .connected()

Description

The connected() method of the Connection object tells if the pool of connections to the database is still connected.

Example

Listing 9.37 creates a pool of connections and pulls a connection from the pool for processing. If the connection is made, any code within that section is executed. If the connection fails, the error is written to the page.

Listing 9.37 Testing a Connection with the connected() Method

Connection.cursor()

ES3+

Syntax

connection.cursor( (sql)

connection.cursor( sql, boolean)

Description

The cursor() method of the Connection object creates a Cursor object that can be used to run SQL queries against the database. The method takes the sql statement as a parameter, as well as an optional boolean value that specifies whether the cursor is updateable.

Example

Listing 9.38 shows how you would run a query against the database using the cursor() method. The while loop is used to write the results to the user’s page.

Listing 9.38 Using the cursor() Method to Run a Query Against the Database

<server>

// Set the query to run.
var mySQL = myConn.cursor('SELECT name,title FROM employees'),

// Iterate through the results and write them to the page.
while(mySQL.next()){
write(mySQL.name + ': ' + mySQL.title + '<br>'),
}

</server>

Connection.execute()

ES3+

Syntax

connection.execute( statement)

Description

The execute() method of the Connection object enables your application to execute a DDL (Data Definition Language) or DML (Data Manipulation Language) query, which does not return a Cursor, supported by your database. This includes statements such as CREATE, ALTER, and DROP.

Example

Description

The prototype property of the Connection object allows you to add methods and properties to the Connection object. If you are adding a method, you set the instance equal to the name of the method you have defined.

Example

Listing 9.44 creates a new property and method of the Connection object. An instance is created and the new property is set. The new method is then called to verify the property and, if it is incorrect (which it is), an error message is written to the page.

Listing 9.44 Using the prototype Property to Create a New Property and Method

connection.SQLTable((sql)

Description

The SQLTable() method of the Connection object takes a sql SELECT statement as a parameter and executes a query through the connection from which it was called. It returns the result formatted in an HTML table for easy writing to a client’s page. This is a simple table in the following format:

<table border="1">
<tr>
<th>column 1 </th>
<th>column 2 </th>
…
<th>column N </th>
</tr>
<tr>
<td>value 1 of column 1 </td>
<td>value 1 of column 2 </td>
…
<td>value 1 of column N </td>
</tr>
<tr>
<td>value 2 of column 1 </td>
<td>value 2 of column 2 </td>
…
<td>value 2 of column N </td>
</tr>
…
</table>

Example

Listing 9.47 runs a user passed query and formats the result using the SQLTable() method. This information is then written to the user’s page.

Listing 9.47 Using the SQLTable() Method to Format the Results of a SELECT Query

<server>

// Assign the user submitted query to the client object.
client.sql = request.sql;

// Create a pool of connections.
var myPool = new DbPool("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

// Open a connection from the pool. Give error if connection could
// not be made.
var myConn = myPool.connection('Employees', 15);
if(myConn.connected()){

  // Start a new transaction and write the results to a page, formatting
  // them with the SQLTable method.
  myConn.beginTransaction();
  write(myConn.SQLTable(client.sql));

  // Commit the transaction.
  myConn.commitTransaction();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

// Release the connection.
myConn.release();

</server>

Connection.storedProc()

ES3+

Syntax

connection.storedProc(procName)

connection.storedProc(procName, arg1, arg2, …, argN)

Description

The storedProc() method of the Connection object creates a Stproc object that allows you to execute a database-specific stored procedure using the connection from which it was invoked.

As shown in the syntactical definition, you can also pass any arguments needed to the method for processing. If you are using a stored procedure that requires arguments, or if you want to have the procedure run using default arguments, you must pass /Default/ as the argument. The following shows an example of passing a default value:

var myStproc = myConn.storedProc("sp_employees", "/Default/");

The scope of this procedure is restricted to the current page. Any methods of the Stproc object must be invoked on the current page. If this is not possible, a new object will have to be created on subsequent pages to access the properties needed.

Example

Listing 9.48 creates a pool of connections and pulls one of the connections. When the connection has been verified, the storedProc() method is used to invoke the fictitious sp_employees stored procedure.

Listing 9.48 Using the storedProc() Method to Invoke a Stored Procedure on a Database

Connection.toString()

ES3+

Syntax

connection.toString()

Description

The toString() method of the Connection object returns a text value of the object. When invoked on an instance of a Connection object, the string is returned in the following format:

"dbName" "uid" "dbType" "dbInstance"

If the parameter is unknown, an empty string is returned. Table 9.6 contains the value of these returned values.

Table 9.6 Return Values of thetoString() Method

Example

Listing 9.49 creates an instance of the Connection object. Once created, the write() method is used to write its string value to the page.

connection.cursor()

database.cursor()

Description

The Cursor object is a core object created when the cursor() method of the Connection or database object is called. A database query is said to return a cursor, so this object contains references to the rows returned from a query.

When working with cursor objects, you should explicitly close them using the close() method when you are finished. Not doing so will cause the JavaScript runtime to hold the cursor in memory until the connection or pool to which the cursor was tied goes out of scope.

The Cursor object has several methods and properties associated with it. These are listed in Table 9.7.

Table 9.7 Properties and Methods of the Cursor Object

The next() method of the Cursor object moves the point in the current row to the next row in the cursor. This method is used to iterate through each of the rows returned by the cursor. This method returns true, unless it is the last row of the cursor, at which time it returns false.

Example

Listing 9.59 creates an instance of the Cursor object and iterates through its results, deleting each row. This is performed by using the next()method.

Listing 9.59 Using the next() Method to Iterate Through the Rows in a Cursor

<server>

var currRow = myConn.cursor('SELECT * FROM employees WHERE uid <= 200'),

// Delete each row in the cursor.
while(currRow.next(){
currRow.delete("employees");
}

// Close the cursor.
currRow.close();

</server>

Cursor.prototype

ES2+

Syntax

Syntax

Core object is created when the database.connect() method is called.

Description

The database object represents a given connection to a database. This object has only one property, the prototype property, which you can use to add properties to the object. Table 9.8 lists the methods associated with this object.

Table 9.8 Methods of the database Object

Example

Listing 9.64 creates a connection to an Oracle database. It takes a user’s UID and name that was passed in, runs a query (based on the UID) against the database to find that user’s information, and updates her name. If a connection is not made, the error code and message are returned to the screen.

Listing 9.64 Creating and Using a database Object

<server>

// Assign the user submitted ID and name to the client object as properties.
client.uid = request.uid;
client.name = request.name;

// Open a connection.
var myConn = database.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

if(myConn.connected()){

  // Start a new SQL transaction to perform a SELECT.
  myConn.beginTransaction();
  var currRow = myConn.cursor('SELECT * FROM employees WHERE uid = '
+ client.uid);

  // Focus on that line, change the name column for that user,
  // and update the row.
  currRow.next();
  currRow.name = client.name;
  currRow.updateRow("employees");
  myConn.commitTransaction();

  // Close the cursor and drop the connection.
  currRow.close();
  myConn.disconnect();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

database.beginTransaction()

ES2+

Syntax

database.beginTransaction()

Description

The beginTransaction() method of the database object begins a new SQL transaction. This groups all the actions against the database together until the user exits the page or either the commitTransaction() or rollbackTransaction() methods are called. In the instance of the user exiting the page, the transaction is either committed or rolled back, depending on the setting of the commit flag when the database object instance is created.

Example

Listing 9.65 creates a connection to an Oracle database. After the connection has been verified, the beginTransaction() method is called and a SQL query is performed. The results are formatted in a table with the SQLTable() method and written to the user’s page.

Listing 9.65 Starting a New Transaction with the beginTransaction() Method

<server>

// Assign the user submitted ID to the client object as properties.
client.uid = request.uid;

// Open a connection.
var myConn = database.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

if(myConn.connected()){

  // Start a new transaction and write the results to a page, formatting
  // them with the SQLTable method.
  myConn.beginTransaction();
  write(myConn.SQLTable('SELECT * FROM employees WHERE uid >= ' + client.uid));

  // Commit the transaction.
  myConn.commitTransaction();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

database.commitTransaction()

ES2+

Syntax

database.commitTransaction()

Description

The commitTransaction() method of the database object commits a new SQL transaction. This commits all the actions against the database since the last commit. If the commit is successful, 0 is returned. If a non-zero number is returned, an error was encountered. In this case, you can use the various methods of the database object to retrieve the code and message of the error.

Example

Listing 9.66 creates a connection to an Oracle database. After the connection has been verified, the beginTransaction() method is called and a SQL query is performed. The results are formatted in a table with the SQLTable() method and written to the user’s page.

Listing 9.66 Starting a New Transaction with the commitTransaction() Method

database.connect()

ES2+

Syntax

database.connect(dbType, dbInstance, uid, pwd, dbName)

database.connect(dbType, dbInstance, uid, pwd, dbName, maxConn)

database.connect(dbType, dbInstance, uid, pwd, dbName, maxConn, commitFlag)

Description

The connect method of the database object is the actual method that connects to a database given the parameters passed. Before you open a connection to a database and have the ability to run queries against it, you should create an instance of this object. Each parameter is defined in Table 9.9.

Table 9.9 Parameters of the connect Method

Depending on your database, it is possible to create an instance of this object by passing a limited set of these parameters. See your database documentation for this information.

Example

Listing 9.67 creates a connection to an Oracle database. It takes a user’s UID and name that was passed in, runs a query (based on the UID) against the database to find that user’s information, and updates her name. If a connection is not made, the error code and message are returned to the screen.

Listing 9.67 Connecting to a Database Using the connect() Method

<server>

// Assign the user submitted ID and name to the client object as properties.
client.uid = request.uid;
client.name = request.name;

// Open a connection.
var myConn = database.connect("ORACLE","mySID","myApp","appsPWD","myTNS",true);

if(myConn.connected()){

  // Start a new SQL transaction to perform a SELECT.
  myConn.beginTransaction();
  var currRow = myConn.cursor('SELECT * FROM employees WHERE uid = '
+ client.uid);

  // Focus on that line, change the name column for that user,
  // and update the row.
  currRow.next();
  currRow.name = client.name;
  currRow.updateRow("employees");
  myConn.commitTransaction();

  // Close the cursor and the connection.
  currRow.close();
  myConn.disconnect();

// If the connection fails, write an error message.
}else{
  write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

database.connected()

ES2+

Syntax

database.connected()

Description

The connected() method of the database object tells whether the connection to the database is still active.

Example

Listing 9.68 creates a connection to a database. If the connection is made, any code within that section is executed. If the connection fails, the error is written to the page.

Listing 9.68 Testing a Connection with the connected() Method

<server>

// Open a connection.
var myConn = database.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");
if (myConn.connected()) {

  // You are connected, so perform any tasks here.

}else{

  // There was an error connecting to the database.
  write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

database.cursor()

ES2+

Syntax

database.cursor(sql)

database.cursor(sql, boolean)

Description

The cursor() method of the database object creates a Cursor object that can be used to run SQL queries against the database. The method takes the sql statement as a parameter, as well as an optional boolean value that specifies whether the cursor is updateable.

database.prototype.method = name

database.prototype.property = value

Description

The prototype property of the database object allows you to add methods and properties to the database object. If you are adding a method, you set the instance equal to the name of the method you have defined.

Example

Listing 9.76 creates a new property and method of the database object. An instance is created and the new property is set. The new method is then called to verify the property, and, if it is incorrect (which it is), an error message is written to the page.

Listing 9.76 Using the prototype Property to Create a New Property and Method

database.storedProc(procName)

database.storedProc(procName, arg1, arg2, …, argN)

Description

The storedProc() method of the database object creates a Stproc object that allows you to execute a database-specific stored procedure using the connection from which it was invoked.

var myStproc = myConn.storedProc("sp_employees", "/Default/");

Example

Listing 9.79 creates a connection to a database. When the connection has been verified, the storedProc() method is used to invoke the fictitious sp_employees stored procedure.

Listing 9.79 Using the storedProc() Method to Invoke a Stored Procedure on a Database

<server>

// Open a connection.
var myConn = database.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

if(myConn.connected()){

  myConn.beginTransaction();

  // Run the stored procedure.
  var myStproc = myConn.storedProc("sp_employees");

  // Commit the transaction.
  myConn.commitTransaction();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

// Release the connection.
myConn.release();

</server> >

database.storedProcArgs()

ES3+

Syntax

database.storedProcArgs(procName)

database.storedProcArgs(procName, type1, type2, …, typeN)

Description

The storedProcArgs() method of the database object creates a Stproc object that allows you to execute a database-specific stored procedure using the connection from which it was invoked on DB2, ODBC, and Sybase databases. If this method is invoked on Informix or Oracle databases, it has no effect. The difference between this method and the storedProc() method is that this method takes a type as a parameter for the arguments passed. These types can be IN, OUT, or INOUT. The following shows an example of passing these types:

var myStproc = myConn.storedProc("sp_employees", "INOUT", "OUT");

Example

Listing 9.80 creates a connection to a database. After the connection has been verified, the storedProc() method is used to invoke the fictitious sp_employees stored procedure, and the storedProcArgs() method is used to specify the argument types.

Listing 9.80 Using the storedProcArgs() Method to Set the Argument Types of a Stored Procedure

<server>

// Open a connection.
var myConn = database.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

if(myConn.connected()){

    myConn.beginTransaction();

    // Run the stored procedure.
    var myStprocArgs = myConn.storedProcArgs("sp_employees", "IN", "INOUT");
    var myStproc = myConn.storedProc("sp_employees", 3, "%John%");

    // Commit the transaction.
    myConn.commitTransaction();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

// Release the connection.
myConn.release();

</server>

database.toString()

ES2+

Syntax

database.toString()

Description

The toString() method of the database object returns a text value of the object. When invoked on an instance of a database object, the string is returned in the following format:

"dbName" "uid" "dbType" "dbInstance"

If the parameter is unknown, an empty string is returned. Table 9.10 contains the value of these returned values.

Table 9.10 Return Values of the toString() Method

Example

Listing 9.81 creates an instance of the database object. Once created, the write() method is used to write its string value to the page.

Listing 9.81 Write the Results of Calling the toString() Method to a Page

new DbPool()

new DbPool(dbType, dbInstance, uid, pwd, dbName)

new DbPool(dbType, dbInstance, uid, pwd, dbName, maxConn)
new DbPool(dbType, dbInstance, uid, pwd, dbName, maxConn, commitFlag)

Description

The DbPool object is an object that holds a “pool” of connections to a database. Before you open a connection to a database and have the ability to run queries against it, you should create an instance of this object. After the instance is created, connections can be obtained from the pool as needed. The pool object itself takes all the parameters necessary to make the connection. It is possible to create a pool without specifying any parameters; however, you must pass the parameters when the first connection is attempted.

The creation of a DbPool object is done using the format defined in the syntax definition. Each parameter is defined in Table 9.11.

Table 9.11 Parameters of the DbPool Object

Depending on your database, it is possible to create an instance of this object by passing a limited set of these parameters, as well as passing none. The object itself has the methods listed in Table 9.12.

Table 9.12 Methods of the DbPool Object

Example

Listing 9.84 creates a pool of connections to an Oracle database and initializes a connection from that pool. It takes a user’s UID and name that was passed in, runs a query (based on the UID) against the database to find that user’s information, and updates her name. If a connection is not made, the error code and message are returned to the screen.

Listing 9.84 Creating and Using a DbPool Object

<server>

// Assign the user submitted ID and name to the client object as properties.
client.uid = request.uid;
client.name = request.name;

// Create a pool of connections.
var myPool = new DbPool("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

// Open a connection from the pool. Give error if connection could
// not be made.
var myConn = myPool.connection('Employees', 15);
if(myConn){
    // Start a new SQL transaction to perform a SELECT.
    myConn.beginTransaction();
    var currRow = myConn.cursor('SELECT * FROM employees WHERE uid = '
  + client.uid);
    // Focus on that line, change the name column for that user,
    // and update the row.
    currRow.next();
    currRow.name = client.name;
    currRow.updateRow("employees");

    // Close the cursor.
    currRow.close();

// If the connection fails, write an error message.
}else{
    write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

DbPool.connect()

ES3+

Syntax

dbpool.connect(dbType, dbInstance, uid, pwd, dbName)

dbpool.connect(dbType, dbInstance, uid, pwd, dbName, maxConn)

dbpool.connect(dbType, dbInstance, uid, pwd, dbName, maxConn, commitFlag)

Description

The connect method of the DbPool object is used to connect to a database when the connection was not made with the initialization of the original DbPool object. The method takes all the parameters necessary to connect to the database. Each parameter is defined in Table 9.9.

Table 9.13 Parameters of the connect() Method

Depending on your database, it is possible to create an instance of this object by passing a limited set of these parameters. See your database documentation for this information.

Example

Listing 9.85 creates a connection pool. The connect() method is then called to open the pool to an Oracle database. If a connection is not made, the error code and message are returned to the screen.

Listing 9.85 Connecting to a Database Using the connect() Method

<server>
// Assign the user submitted ID and name to the client object as properties. client.uid = request.uid; client.name = request.name; // Create a pool of connections. var myPool = new DbPool(); // Create a connection for the pool. myPool.connect("ORACLE", "mySID", "myApp", "appsPWD", "myTNS"); // Open a connection from the pool. Give error if connection could // not be made. var myConn = myPool.connection('Employees', 15); if(myConn.connected()){ // Do any database stuff here.
// If the connection fails, write an error message.
}else{
write('Error ('+myConn.majorErrorCode()+'): '' + myConn.majorErrorMessage();
}

</server>

DbPool.connected()

ES3+

Syntax

dbpool.connected()

Description

The connected() method of the DbPool object tells whether the pool of connections to the database is still connected.

Example

Listing 9.86 creates a pool of connections and pulls a connection from the pool for processing. If the connection is made, any code within that section is executed. If the connection fails, the error is written to the page.

Listing 9.86 Testing a Connection with the connected() Method

DbPool.connection()

ES3+

Syntax

dbpool.connection(name, seconds);

Description

The connection() method of the DbPool object pulls a connection from the pool. The connection is returned from the method and can be stored in a variable to be used for processing.

The method takes two parameters. The first parameter is a name, which is a name you can give your connection. Because you actually store the connection in a variable, this name’s primary function becomes one for debugging purposes. The second parameter is a seconds value for the number of seconds you give the instance to connect.

Example

Listing 9.87 creates a pool of connections to an Oracle database and initializes a connection from that pool. It takes a user’s UID and name that was passed in, runs a query (based on the UID) against the database to find that user’s information, and updates her name. If a connection is not made, the error code and message are returned to the screen.

Listing 9.87 Creating and Using a connection() Method

DbPool.DbPool()

ES3+

Syntax

new DbPool()

new DbPool(dbType, dbInstance, uid, pwd, dbName)

new DbPool(dbType, dbInstance, uid, pwd, dbName, maxConn)

new DbPool(dbType, dbInstance, uid, pwd, dbName, maxConn, commitFlag)

Description

The DbPool() method of the DbPool object is the underlying method that creates a “pool” of connections to a database. The creation of a DbPool object is done using the format defined in the syntax definition. Each parameter is defined in Table 9.14.

Table 9.14 Parameters of the DbPool() Method

Depending on your database, it is possible to create an instance of this object by passing a limited set of these parameters.

database.storedProcArgs(procName) database.storedProcArgs(procName, type1, type2, …, typeN)

Description

The storedProcArgs() method of the database object creates a Stproc object that allows you to execute a database-specific stored procedure using the connection from which it was invoked on DB2, ODBC, and Sybase databases. If this method is invoked on Informix or Oracle databases, it has no affect. The difference between this method and the storedProc() method is that this method takes a type as a parameter for the arguments passed. These types can be IN, OUT, or INOUT. The following shows an example of passing these types:

var myStproc = myConn.storedProc("sp_employees", "INOUT", "OUT");

Example

Listing 9.95 creates a pool of connections to a database. The storedProc() method is used to invoke the fictitious sp_employees stored procedure, and the storedProcArgs() method is used to specify the argument types.

Listing 9.95 Using the storedProcArgs() Method to Set the Argument Types of a Stored Procedure

<server>
// Create a pool of connections.
var myPool = new DbPool("ORACLE", "mySID", "myApp", "appsPWD", "myTNS");

// Set the stored procedure arguments.
var myStprocArgs = myPool.storedProcArgs("sp_employees", "IN", "INOUT");
var myStproc = myPool.storedProc("sp_employees", 3, "%John%");
</server>

DbPool.toString()

ES3+

Syntax

dbpool.toString()

Description

The toString() method of the DbPool object returns a text value of the object. When invoked on an instance of a DbPool object, the string is returned in the following format:

"dbName" "uid" "dbType" "dbInstance"

If the parameter is unknown, an empty string is returned. Table 9.15 contains the value of these returned values.

Table 9.15 Return Values of the toString() Method

Example

Listing 9.96 creates an instance of the DbPool object. Once created, the write()

The usage of the File object is very straightforward. The methods provided allow you to perform the various tasks needed on the files on your file system. Part of this functionality of working with these files is to allow programmers to specify how they want to open the files. A file can be opened to read, write, append, or open in binary mode. These options are specified in the open() method in the following form:

myFile.open("option");

Table 9.17 gives a list and description of these options.

Table 9.17 Options of the open() Method

Table 9.18 Options of the open() Method

Example

Listing 9.112 shows how to open a file in read mode.

Listing 9.112 Using the open() Method to Open a File

<server>
// Initialize a file
var myLog = new File("/data/logs/today.log");

// Open the file in read mode
myLog.open("r");

// Close the file
myLog.close();

</server>

File.prototype

ES3+

Syntax

file.prototype.method = name
file.prototype.property = value

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for 9 Server-Side

Create new playlist

Sign In

Sign Up

Chapter 9 Server-Side

addClient()

Syntax

Description

Example

addResponseHeader()

Syntax

Description

Example

Application

Syntax

Description

Example

Application.Application_OnEnd

Syntax

Description

Example

Application.Application_OnStart

Syntax

Description

Example

Application.Contents

Syntax

Description

Example

Application.Contents.Remove()

Syntax

Description

Example

Application.Contents.RemoveAll()

Syntax

Description

Example

Application.Lock()

Syntax

Description

Example

Application.StaticObjects

Syntax

Description

Example

Application.Unlock()

Syntax

Description

Example

ASPError

Syntax

Description

Example

ASPError.ASPCode

Syntax

Description

Example

ASPError.ASPDescription

Syntax

Description

Example

ASPError.Category

Syntax

Description

Example

ASPError.Column

Syntax

Description

Example

ASPError.Description

Syntax

Description

Example

ASPError.File

Syntax

Description

Example

ASPError.Line

Syntax

Description

Table of Contents for
9 Server-Side