## database

Object. Lets an application interact with a relational database.

#### Syntax

To create a database object:

    database.connect("type", "server", "user", "password", "database")

For details on creating a database, see the connect method.

To use a database object:

    database.methodName

#### Parameters

methodName is one of the methods described below.

#### Property of

None

#### Description

LiveWire creates a database object when an application connects to a database server. Each application can have only one database object. Use the database object to interact with the database on the server.

You can use the database object to perform the following tasks:

- Connect to the database server (connect, connected, disconnect methods).
- Display the results of a query as an HTML table (SQLTable method).
- Execute SQL statements on the database server (cursor, execute, SQLTable methods).
- Manage transactions (beginTransaction, commitTransaction, rollbackTransaction methods).
- Handle errors returned by the target database (majorErrorCode, majorErrorMessage, minorErrorCode, minorErrorMessage methods).

### Connecting to databases

LiveWire provides the following types of database connections:

- Standard connections occur when an application connects to a database without locking the project object.
- Serial connections occur when an application locks the project object before connecting to a database.

In the standard approach, the application contains a single connection statement that all clients use to establish a database connection. All clients connect to the database simultaneously, and they share the same database, user name, and so on. This approach usually features a connect method in the initial page of the application.

In the serial approach, the application allows one client at a time to connect to the database. Clients connect to the database sequentially, and they can use different databases, user names, and so on. This approach requires a lock and a connect method on each page that requires a database connection.

A standard connection lets LiveWire handle all the details of database connections, but it has the following possible disadvantages:

- The number of simultaneous database connections can reach the maximum number of processes or threads specified in the configuration file for your Netscape server.
- All database connections share the same user name and access privileges.
- You must have a vendor license that supports multiple database connections.

### Transactions

LiveWire provides the following types of transaction control:

- Implicit transactions are default transactions that LiveWire uses when you do not use explicit transaction control.
- Explicit transactions are transactions that you control with the database methods.

If you do not use any database methods to control transactions explicitly, LiveWire performs each database modification as a separate transaction. In this implicit transaction, LiveWire begins a transaction before a SQL statement and attempts to commit the transaction after the statement executes.

The scope of a transaction is limited to the current HTML page in an application. If the user exits the page before an application issues a commitTransaction or rollbackTransaction, then the transaction is automatically committed.

#### Properties

None

#### Methods

The database object has the following methods:

beginTransaction commitTransaction connect connected cursor method disconnect execute | majorErrorCode majorErrorMessage minorErrorCode minorErrorMessage rollbackTransaction SQLTable

#### Examples

Example 1: Standard connection. The following example creates a database object and opens a standard connection to the customer database on an Informix server. The name of the server is blue, the user name is ADMIN, and the password is MANAGER.

    database.connect("INFORMIX", "blue", "ADMIN", "MANAGER", "inventory")

In this example, many clients can connect to the database simultaneously, but they all share the same connection, user name, and password.

Example 2: Serial connection. In the following example, the connectInventory function is used to establish a serial connection to the inventory database. The user and password parameters of connectInventory are passed to the connect method to permit successive users to log in with different privileges.

    function connectInventory(user,password) {

       project.lock()

          database.connect("INFORMIX", "blue", user,

             password, "inventory")

          database.execute(sqlStatements...)

          database.disconnect(...)

       project.unlock()

    }

#### See also

cursor object, connect method

## Date

Object. Lets you work with dates and times.

#### Syntax

To create a Date object:

    1. dateObjectName = new Date()

    2. dateObjectName = new Date("month day, year hours:minutes:seconds")

    3. dateObjectName = new Date(year, month, day)

    4. dateObjectName = new Date(year, month, day, hours, minutes, seconds)

To use Date methods:

    dateObjectName.methodName(parameters)

Exceptions: The Date object's parse and UTC methods are static methods that you use as follows:

    Date.UTC(parameters)

    Date.parse(parameters)

#### Parameters

dateObjectName is either the name of a new object or a property of an existing object. When using Date methods, dateObjectName is either the name of an existing Date object or a property of an existing object.

month, day, year, hours, minutes, and seconds are string values for form 2 of the syntax. For forms 3 and 4, they are integer values.

methodName is one of the methods listed below.

#### Property of

None

#### Description

The Date object is a built-in JavaScript object.

Form 1 of the syntax creates today's date and time. If you omit hours, minutes, or seconds from form 2 or 4 of the syntax, the value will be set to zero.

The way JavaScript handles dates is very similar to the way Java handles dates: both languages have many of the same date methods, and both store dates internally as the number of milliseconds since January 1, 1970 00:00:00. Dates prior to 1970 are not allowed.

#### Properties

None

#### Methods

The Date object has the following methods:

getDate getDay getHours getMinutes getMonth getSeconds getTime getTimezoneOffset getYear parse | setDate setHours setMinutes setMonth setSeconds setTime setYear toGMTString toLocaleString UTC

#### Event handlers

None. Built-in objects do not have event handlers.

#### Examples

The following examples show several ways to assign dates:

    today = new Date()

    birthday = new Date("December 17, 1995 03:24:00")

    birthday = new Date(95,12,17)

    birthday = new Date(95,12,17,3,24,0)

## debug

Function. Displays a LiveWire expression in the trace facility.

#### Syntax

    debug(expression)

#### Parameters

expression is any valid LiveWire expression.

#### Description

The debug function is a top-level LiveWire function that is not associated with any object.

Use this function to display the value of an expression for debugging purposes. The value is displayed in the trace facility following the brief description "Debug message:".

#### Examples

The following example displays the value of the variable data:

    debug("The final value of data is " + data)

## deleteRow

Method. Deletes a row from a database table.

#### Syntax

    cursorName.deleteRow("tableName")

#### Parameters

cursorName is the name of a cursor object.

tableName is the name of a database table.

#### Method of

cursor object

#### Description

The deleteRow method uses an updatable cursor to delete the current row from the specified table. See the cursor method for information about creating an updatable cursor.

The deleteRow method returns a status code based on a database server message to indicate whether the method completed successfully. If successful, the method returns a zero; otherwise, it returns a nonzero integer to indicate the reason it failed. See "Database status codes." for an explanation of status codes.

#### Examples

In the following example, the deleteRow method removes a customer from the customer database. The cursor method creates the customerSet cursor containing a single row; the value for customer.ID is passed in as a request object property. The next method moves the pointer to the only row in the cursor, and the deleteRow method deletes the row.

    database.beginTransaction()

       customerSet = database.cursor("select * from customer where

          customer.ID = " + request.ID,true)

       customerSet.next()

       statusCode = customerSet.deleteRow("customer")

       customerSet.close()

       if (statusCode == 0) {

          database.commitTransaction() }

       else {

          database.rollbackTransaction() }

In this example, the deleteRow method sets the value of statusCode to indicate whether deleteRow succeeds or fails. If statusCode is zero, the method has succeeded and the transaction is committed; otherwise, the transaction is rolled back.

#### See also

insertRow, updateRow methods

## destroy

Method. Destroys a client object.

#### Syntax

    client.destroy()

#### Method of

client

#### Description

The destroy method explicitly destroys the client object that issues it and removes all properties from the client object. If you do not explicitly issue a destroy method, LiveWire automatically destroys the client object when its lifetime expires. The expiration method sets the lifetime of a client object; by default, the lifetime is ten minutes.

If you are using client-cookies to maintain the client object, destroy eliminates all client property values, but it does not affect what is stored in the Navigator's cookie file. Use expiration with an argument of zero seconds to remove all client properties stored in the cookie file.

When using client URL to maintain the client object, destroy will remove all client properties after the method call. However, any links in a page before the call to destroy will retain properties in their URLs. Therefore, you should generally call destroy either at the top or bottom of the page when using client URL maintenance. For more information, see the next section.

#### Examples

The following method destroys the client object that calls it:

    <SERVER>client.destroy()</SERVER>

#### See also

expiration method

## disconnect

Method. Disconnects an application from a database and destroys the database object.

#### Syntax

    database.disconnect()

#### Method of

database

#### Description

Use the disconnect method to close a database connection. When an application is disconnected from a database, it cannot create cursors or use database methods.

#### Examples

The following example uses an if condition to determine if an application is connected to a database server. If the application is connected, the application calls the disconnect method; if the application is not connected, the isNotConnected routine runs.

    if(database.connected()) {

       database.disconnect() }

    else {

       isNotConnectedRoutine() }

#### See also

connect, connected methods

## E

Property. Euler's constant and the base of natural logarithms, approximately 2.718.

#### Syntax

    Math.E

#### Property of

Math

#### Description

Because E is a constant, it is a read-only property of Math.

#### Examples

The following function returns Euler's constant:

    function getEuler() {

       return Math.E

    }

#### See also

LN2, LN10, LOG2E, LOG10E, PI, SQRT1_2, SQRT2 properties

## eof

Method. Determines whether the pointer is beyond the end of an open file.

#### Syntax

    fileObjectName.eof()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

Use the eof method to determine whether the position of the pointer is beyond the end of a file. See the File object for a description of the pointer.

A call to setPosition resulting in a location greater than `fileObjectName.getLength` places the pointer beyond the end of the file. Because all read operations also move the pointer, a read operation that reads the last byte of data (or character) in a file positions the pointer beyond the end of the file.

The eof method returns true if the pointer is beyond the end of the file; otherwise, it returns false.

#### Examples

In this example, a while loop executes until the pointer is positioned past the end of the file. While the pointer is not positioned past the end of the file, the readln method reads the current line, and the write method displays it. The last readln method positions the pointer past the end of the file, ending the while loop.

    x = new File("c:/data/userInfo.txt")

    if (x.open("r")) {

       while (!x.eof()) {

          line = x.readln()

          write(line+"<br>");

       }

       x.close();

    }

#### See also

getPosition, setPosition methods

## error

Method. Returns the current error status.

#### Syntax

    fileObjectName.error()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

The error method returns one of the following values:

If the file specified in fileObjectName is open, the error method returns the error status; otherwise, it returns -1. The error status is nonzero when an error occurs; otherwise, it is zero. Specific error status codes are platform-dependent. Refer to your operating system documentation for more information.

#### Examples

The following example uses the error method in an if statement to take different actions depending on whether a call to the open method succeeded. After the if statement completes, the error status is reset with the clearError method.

    userInput = new File("c:/data/input.txt")

    userInput.open("w")

    if (userInput.error() == 0) {

       fileIsOpen() }

    else {

       fileIsNotOpen() }

    userInput.clearError()

#### See also

clearError method

## escape

Function. Returns the hexadecimal encoding of an argument in the ISO Latin-1 character set.

#### Syntax

    escape("string")

#### Parameters

string is a string in the ISO Latin-1 character set or a property of an existing object.

#### Description

Use the escape and unescape functions to add property values to a URL manually.

The value returned by the escape function is one of the following:

- For characters other that space, a string of the form "%xx," where xx is the hexadecimal encoding of a character in the argument.
- For the space character, a + sign.

The escape function is a top-level LiveWire function that is not associated with any object.

#### Examples

The following example returns "%26":

    escape("&")

In the following example, the value of the variable theValue is encoded as a hexadecimal string and passed on to the request object when a user clicks the link:

    <A HREF=\Q"mypage.html?val1="+escape(theValue)\Q)>Click Here</A>

#### See also

unescape function

## eval

Function. The eval function evaluates a string and returns a value.

#### Syntax

    eval(string)

#### Parameters

string is any string representing a JavaScript expression, statement, or sequence of statements. The expression can include variables and properties of existing objects.

#### Description

The eval function is a built-in JavaScript function. It is not a method associated with any object, but is part of the language itself.

The argument of the eval function is a string. If the string represents an expression, eval evaluates the expression. If the argument represents one or more JavaScript statements, eval performs the statements. Do not call eval to evaluate an arithmetic expression; JavaScript evaluates arithmetic expressions automatically.

If you construct an arithmetic expression as a string, you can use eval to evaluate it at a later time. For example, suppose you have a variable x. You can postpone evaluation of an expression involving x by assigning the string value of the expression, say `"3 * x + 2"`, to a variable, and then calling eval at a later point in your script.

#### Examples

The following examples display output using `document.write`. In LiveWire, you can display the same output by calling the write function instead of using `document.write`.

Example 1. Both of the write statements below display 42. The first evaluates the string "x + y + 1," and the second evaluates the string "42."

    var x = 2

    var y = 39

    var z = "42"

    document.write(eval("x + y + 1"), "<BR>")

    document.write(eval(z), "<BR>")

Example 2. In the following example, the getFieldName(n) function returns the name of the nth form element as a string. The first statement assigns the string value of the third form element to the variable field. The second statement uses eval to display the value of the form element.

    var field = getFieldName(3)

    document.write("The field named ", field, " has value of ", eval(field + ".value"))

Example 3. The following example uses eval to evaluate the string str. This string consists of JavaScript statements that open an Alert dialog box and assigns z a value of forty-two if x is five, and assigns zero to z otherwise. When the second statement is executed, eval will cause these statements to be performed, and it will also evaluate the set of statements and return the value that is assigned to z.

    var str = "if (x == 5) {alert('z is 42'); z = 42;} else z = 0; "

    document.write("<P>z is ", eval(str))

Example 4. In the following example, the setValue function uses eval to assign the value of the variable newValue to the text field textObject:

    function setValue (textObject, newValue) {

       eval ("document.forms[0]." + textObject + ".value") = newValue

    }

## execute

Method. Executes a SQL statement that does not return an answer set.

#### Syntax

    database.execute(sqlStatement)

#### Parameters

sqlStatement is an expression that evaluates to a SQL statement supported by the database server.

#### Method of

database

#### Description

The execute method lets you execute a SQL statement that does not return an answer set, such as INSERT, UPDATE, and DELETE statements. The SQL statement passed as a parameter to the execute method is committed automatically, unless you explicitly start a transaction with the beginTransaction method.

Use the cursor or SQLTable methods to execute a SQL statement that returns an answer set.

The execute method returns a status code based on a database server message to indicate whether the method completed successfully. If successful, the method returns a zero; otherwise, it returns a nonzero integer to indicate the reason it failed. See "Database status codes" on page 162 for an description of status codes.

#### Examples

In the following example, the execute method is used to delete a customer from the customer table.

    if(request.ID != null)

       {

       database.execute("delete from customer

          where customer.ID = " + request.ID)

       }

In this example, `customer.ID` represents the unique ID of a customer that is in the ID column of the customer table. The value for `customer.ID` is passed into the DELETE statement as the value of the ID property of the request object.

#### See also

cursor method, SQLTable method

## exists

Method. Determines if a file exists.

#### Syntax

    fileObjectName.exists()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

The exists method returns true if the file exists; otherwise, it returns false.

#### Examples

The following example uses an if statement to take different actions depending on whether a physical file exists. If the file exists, LiveWire opens it and calls the writeData function. If the file does not exist, LiveWire calls the noFile function.

    dataFile = new File("c:/data/mytest.txt")

    if (dataFile.exists() ==true)

       {

       dataFile.open("w")

       writeData()

       dataFile.close()

       }

    else

       {

       noFile()

       }

## exp

Method. Returns enumber, where number is the argument, and e is Euler's constant, the base of the natural logarithms.

#### Syntax

    Math.exp(number)

#### Parameters

number is any numeric expression or a property of an existing object.

#### Method of

Math

#### Examples

The following function returns the exp value of the variable x:

    function getExp(x) {

       return Math.exp(x)

    }

If you pass getExp the value 1, it returns 2.718281828459045.

#### See also

log, pow methods

## expiration

Method. Specifies the duration of a client object.

#### Syntax

    client.expiration(seconds)

#### Parameters

seconds is an integer representing the number of seconds of client inactivity before the client object expires.

#### Method of

client

#### Description

By default, LiveWire destroys the client object after the client is inactive for ten minutes. This default lifetime lets LiveWire clean up client objects that are no longer necessary.

Use the expiration method to explicitly control the expiration of a client object, making it longer or shorter than the default. You must use expiration in each page of an application for which you want a client expiration other than the default. Any page that does not specify an expiration will use the default of ten minutes.

Client expiration does not apply if using client URL to maintain the client object; see "Techniques for maintaining the client object."

#### Examples

The following example extends the amount of client inactivity before expiration to one hour. This code is issued when an application is first launched.

    <SERVER>client.expiration(3600)</SERVER>

#### See also

destroy method