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. The database object lets you perform the following tasks:

Connecting to databases
LiveWire provides the following types of connections 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. Each client connects 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:

    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 an 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

  • beginTransaction
  • commitTransaction
  • connect
  • connected
  • cursor
  • 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 simultaneosly, but they all share the same connection, use 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

  • 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

    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)
    
    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

    Description

    The deleteRow method uses an updateable cursor to delete the current row from the specified table. See the cursor method for information about creating an updateable 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 0; otherwise, it returns a non-zero integer to indicate the reason it failed. See Interpreting Database Status Codes for an explanation of the individual 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 0, the method has succeeded and the transaction is committed; otherwise, the transaction is rolled back.

    See also

    insertRow and 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 10 minutes.

    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 and 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 example displays Euler's constant:

    document.write("Euler's constant is " + 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 if 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 and 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 non-zero when an error occurs; otherwise, it is 0. 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

    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. Do not call eval to evaluate an arithmetic expression. JavaScript evaluates arithmetic expressions automatically. If the argument represents an expression, eval evaluates the expression. If the argument represents one or more JavaScript statements, eval performs the statements.

    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

    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 opens an alert dialog box and assigns z a value of 42 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 an SQL statement that does not return an answer set.

    Syntax

    database.execute(sqlStatement)
    

    Parameters

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

    Method of

    database

    Description

    The execute method lets you execute an 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 an 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 0; otherwise, it returns a non-zero integer to indicate the reason it failed. See Interpreting Database Status Codes for an explanation of the individual 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 and SQLTable methods

    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

    //Displays the value 2.718281828459045
    document.write("The value of e<SUP>1</SUP> is " + Math.exp(1))
    

    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 10 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.

    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