Objects, methods, properties, and functions


abs

Method. Returns the absolute value of a number.

Syntax

Math.abs(number)

Parameters

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

Method of

Math

Examples

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

function getAbs(x) {
   return Math.abs(x)
}

acos

Method. Returns the arc cosine (in radians) of a number.

Syntax

Math.acos(number)

Parameters

number is a numeric expression between -1 and 1, or a property of an existing object.

Method of

Math

Description

The acos method returns a numeric value between zero and pi radians. If the value of number is outside this range, it returns zero.

Examples

The following function returns the arc cosine of the variable x:

function getAcos(x) {
   return Math.acos(x)
}
If you pass getAcos the value -1, it returns 3.141592653589793; if you pass it the value two, it returns zero because two is out of range.

See also

asin, atan, cos, sin, tan methods

addClient

Function. Preserves client object property values when generating dynamic URLs or using redirect if using URL encoding for client object maintenance.

Syntax

addClient(URL)

Parameters

URL is a string representing a URL.

Description

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

Use addClient to preserve client object property values when you use redirect or generate dynamic links if an application is using client URL encoding or server URL encoding to maintain the client object.

If an application does not use a URL encoding scheme, you do not have to use the addClient function. Because an application may be modified to use a URL encoding scheme in the future, however, it is safer to code the application "defensively" with addClient.

See "Techniques for maintaining the client object." for information about using URL encoding to maintain client properties.

Examples

In the following example, addClient is used with the redirect function to redirect a browser:

redirect(addClient("mypage.html"))
In the following example, addClient preserves client object property values when a link is dynamically generated:

<A HREF=\QaddClient("page" + project.pageno + ".html")\Q>
   Jump to new page</A>

See also

redirect function

agent

Property. Provides name and version information about the client software.

Syntax

request.agent

Property of

request

Description

The agent property identifies the client software. Use this information to conditionally employ certain features in an application.

agent is a read-only property.

The value of the agent property is the same as the value of the userAgent property of the client-side navigator object. The agent property specifies client information in the following format:

codeName/releaseNumber (platform; country [; platformIdentifier])

The values contained in this format are the following:

Examples

The following example displays client information for Navigator 2.0 on Windows NT:

write(request.agent)
Displays "Mozilla/2.0 (WinNT;I)"
The following example evaluates the request.agent property and runs the oldBrowser procedure for clients other than Navigator 2.0. If the browser is Navigator 2.0, the currentBrowser function executes.

<SERVER>
var agentVar=request.agent
if (agentVar.indexOf("2.0")==-1)
   oldBrowser()
else
   currentBrowser()
</SERVER>

See also

ip, method, protocol (request object) properties

anchor method

Method. Creates an HTML anchor that is used as a hypertext target.

Syntax

text.anchor(nameAttribute)

Parameters

text is any string or a property of an existing object.

nameAttribute is any string or a property of an existing object.

Method of

string

Description

Use the anchor method with the write or writeln methods to programmatically create and display an anchor in a document. Create the anchor with the anchor method, and then call write or writeln to display the anchor in a document. In LiveWire, use the write function to display the anchor.

In the syntax, the text string represents the literal text that you want the user to see. The nameAttribute string represents the NAME attribute of the A tag.

Examples

The following example opens the msgWindow window and creates an anchor for the Table of Contents:

var myString="Table of Contents"

msgWindow.document.writeln(myString.anchor("contents_anchor"))
The previous example produces the same output as the following HTML:

<A NAME="contents_anchor">Table of Contents</A>
In LiveWire, you can generate this HTML by calling the write function instead of using document.writeln.

See also

link method

arguments array

Property. An array corresponding to elements of a function.

Syntax

1. functionName.arguments[index]
2. functionName.arguments.length

Parameters

functionName is the name of a function you have created.

index is an integer representing an element of a function.

Property of

The arguments array is a property of any user-defined function.

Description

You can call a function with more arguments than it is formally declared to accept by using the arguments array. This technique is useful if a function can be passed a variable number of arguments. You can use arguments.length to determine the number of arguments passed to the function, and then treat each argument by using the arguments array.

The arguments array is available only within a function declaration. Attempting to access the arguments array outside a function declaration results in an error.

Properties

The arguments array has one property, length, that reflects the number of arguments to the function.

Examples

This example defines a function that creates HTML lists. The only formal argument for the function is a string that is "U" if the list is to be unordered (bulleted), or "O" if the list is to be ordered (numbered). The function is defined as follows:

function list(type) {
   document.write("<" + type + "L>")
   for (var i=1; i<list.arguments.length; i++) {
   document.write("<LI>" + list.arguments[i])
   document.write("</" + type + "L>") }
}
You can pass any number of arguments to this function, and it displays each argument as an item in the type of list indicated. For example, the following call to the function

list("U", "One", "Two", "Three")
results in this output:

<UL>
<LI>One
<LI>Two
<LI>Three
</UL>
In LiveWire, you can display the same output by calling the write function instead of using document.write.

arguments property

Property. An array of elements in a function. See the arguments array for information.

asin

Method. Returns the arc sine (in radians) of a number.

Syntax

Math.asin(number)

Parameters

number is a numeric expression between -1 and 1, or a property of an existing object.

Method of

Math

Description

The asin method returns a numeric value between -pi/2 and pi/2 radians. If the value of number is outside this range, it returns zero.

Examples

The following function returns the arc sine of the variable x:

function getAsin(x) {
   return Math.asin(x)
}
If you pass getAsin the value one, it returns 1.570796326794897 (pi/2); if you pass it the value two, it returns zero because two is out of range.

See also

acos, atan, cos, sin, tan methods

atan

Method. Returns the arc tangent (in radians) of a number.

Syntax

Math.atan(number)

Parameters

number is either a numeric expression or a property of an existing object, representing the tangent of an angle.

Method of

Math

Description

The atan method returns a numeric value between -pi/2 and pi/2 radians.

Examples

The following function returns the arc tangent of the variable x:

function getAtan(x) {
   return Math.atan(x)
}
If you pass getAtan the value 1, it returns 0.7853981633974483; if you pass it the value .5, it returns 0.4636476090008061.

See also

acos, asin, cos, sin, tan methods

beginTransaction

Method. Begins a SQL transaction.

Syntax

database.beginTransaction()

Method of

database

Description

The beginTransaction method starts a new database transaction.

You can group actions that modify the database within this transaction and then either commit or roll back the transaction with the commitTransaction or rollbackTransaction methods.

A nested transaction occurs when you issue a second beginTransaction method before committing or rolling back the first transaction. LiveWire does not support nested transactions. If you create a nested transaction, the next commitTransaction or rollbackTransaction commits or rolls back all actions since the first beginTransaction. For more information about transactions, see "Managing transactions."

The beginTransaction 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. For an explanation of status codes, see "Database status codes."

Examples

This example updates the rentals table within a transaction. The values of customerID and videoID are passed into the cursor method as properties of the request object. When the videoReturn cursor object opens, the next method navigates to the only record in the answer set and updates the value in the returnDate field.

The variable x is assigned a database status code to indicate if the updateRow method is successful. If updateRow succeeds, the value of x is zero, and the transaction is committed; otherwise, the transaction is rolled back.

// Begin a transaction
database.beginTransaction();
// Create a Date object with the value of today's date
today = new Date();
// Create a cursor with the rented video in the answer set
videoReturn = database.cursor("SELECT * FROM rentals WHERE
   customerId = " + request.customerID + " AND
   videoId = " + request.videoID, true);
// Position the pointer on the first row of the cursor
// And update the row
videoReturn.next()
videoReturn.returndate = today;
x = videoReturn.updateRow("rentals");
// End the transaction by committing or rolling back
if (x == 0) {
   database.commitTransaction() }
else {
   database.rollbackTransaction() }
// Close the cursor
videoReturn.close();

See also

commitTransaction, rollbackTransaction methods

big

Method. Causes a string to be displayed in a big font as if it were in a BIG tag.

Syntax

stringName.big()

Parameters

stringName is any string or a property of an existing object.

Method of

string

Description

Use the big method with the write or writeln methods to format and display a string in a document. In LiveWire, use the write function to display the string.

Examples

The following example uses string methods to change the size of a string:

var worldString="Hello, world"

document.write(worldString.small())
document.write("<P>" + worldString.big())
document.write("<P>" + worldString.fontsize(7))
The previous example produces the same output as the following HTML:

<SMALL>Hello, world</SMALL>
<P><BIG>Hello, world</BIG>
<P><FONTSIZE=7>Hello, world</FONTSIZE>
In LiveWire, you can generate this HTML by calling the write function instead of using document.write.

See also

fontsize, small methods

blink

Method. Causes a string to blink as if it were in a BLINK tag.

Syntax

stringName.blink()

Parameters

stringName is any string or a property of an existing object.

Method of

string

Description

Use the blink method with the write or writeln methods to format and display a string in a document. In LiveWire, use the write function to display the string.

Examples

The following example uses string methods to change the formatting of a string:

var worldString="Hello, world"

document.write(worldString.blink())
document.write("<P>" + worldString.bold())
document.write("<P>" + worldString.italics())
document.write("<P>" + worldString.strike())
The previous example produces the same output as the following HTML:

<BLINK>Hello, world</BLINK>
<P><B>Hello, world</B>
<P><I>Hello, world</I>
<P><STRIKE>Hello, world</STRIKE>
In LiveWire, you can generate this HTML by calling the write function instead of using document.write.

See also

bold, italics, strike methods

blob

Function. Assigns BLOb data to a column in a cursor.

Syntax

cursorName.cursorColumn=blob(blobFileName)

Parameters

cursorName is the name of a cursor object.

cursorColumn is the name of a column in the cursor containing BLOb data.

blobFileName is the full path and name of a file containing BLOb data.

Method of

cursorColumn array (see cursor object)

Description

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

The blob function assigns BLOb data to a column by specifying the name and path of a file that contains the BLOb. Use the blob function to update or insert a row in a cursor that contains a BLOb column.

Examples

The following example updates a photograph in the photo column of the customerSet cursor. The cursor contains a single row, specified by the customer.ID value.

// Create a cursor
customerSet = database.cursor("SELECT * FROM customer WHERE
   customer.ID = " + request.customerID
// Position the pointer on the row
customerSet.next()
// Assign the blob data
customerSet.photo = blob("c:/data/customer/photo/johnson.gif")
// And update the row
customerSet.updateRow("customer")

See also

blobImage, blobLink methods

blobImage

Method. Displays a BLOb from a database as if it were in an IMG tag.

Syntax

cursorName.cursorColumn.blobImage(format [, altText] [, align]
   [, widthPixels] [, heightPixels] [, borderPixels] [,ismap])

Parameters

cursorName is the name of a cursor object, and cursorColumn is the name of a column in the cursor containing BLOb data.

format is a string specifying the image format. This can be "GIF," "JPEG," or any other MIME image format. Acceptable formats are specified in the "type=image" section of the file /ns-home/httpd-80/config/mime.types in your Netscape server's root directory.

altText is a string indicating text to display as an alternative to the image; this will be the value of the ALT attribute.

align is a string specifying the value of the ALIGN attribute of the image tag. This can be "left," "right," or any other value supported by the client browser.

widthPixels is a string specifying the width of the image in pixels; this will be the value of the WIDTH attribute.

heightPixels is a string specifying the height of the image in pixels; this will be the value of the HEIGHT attribute.

borderPixels is a string specifying the size of the outline border in pixels if the image is a hyperlink; this will be the value of the BORDER attribute. Use "0" to display no border.

ismap is a Boolean value specifying whether the graphic is an image map. If ismap is true, LiveWire adds an ISMAP attribute to the IMG tag. Otherwise, it doesn't.

Method of

cursorColumn array (see cursor object)

Description

The blobImage method retrieves BLOb image data from a database column and displays it in an IMG tag. Most of the parameters of blobImage correspond to attributes of the IMG tag:

Examples

The following example creates a cursor from the rockStarBios table and uses blobImage to display an image retrieved from the photos column:

cursor = database.cursor("SELECT * FROM rockStarBios
   WHERE starID = 23")
while(cursor.next()) {
   write(cursor.photos.blobImage("gif", , left, 30, 30, ,false))
}
cursor.close()
This example displays an image as if it were created by the following HTML:

<IMG SRC="livewire_temp.gif" ALIGN=LEFT WIDTH=30 HEIGHT=30>
The livewire_temp.gif file in this example is the file that the rockStarBios table stores the BLOb data in.

See also

blob function, blobLink method

blobLink

Method. Creates a hyperlink to an image or another type of binary data.

Syntax

cursorName.cursorColumn.blobLink(mimeType, linkText)

Parameters

cursorName is the name of a cursor object.

cursorColumn is the name of a column in the cursor containing BLOb data.

mimeType is a string specifying the MIME type of the binary data.

linkText is any JavaScript string expression representing the text to display in the link.

Method of

cursorColumn array (see cursor object)

Description

The blobLink method places the BLOb from the specified row and column of the cursor into a temporary file in memory and creates a hyperlink to the BLOb data, in an A tag.

Use the blobLink method when you don't want to display graphics immediately (to reduce bandwidth requirements), or to provide a link to an audio clip or other multimedia content that is not viewable inline.

The mimeType parameter is a string specifying the MIME type of the binary data. This can be "image/gif," "image/jpeg," or any other MIME image format. The acceptable formats are specified in the "type=image" section of the file /ns-home/httpd-80/config/mime.types in your Netscape server's root directory.

LiveWire releases the temporary file that blobLink creates after either of the following has occurred:

  • The user clicks the link.
  • Sixty seconds following the request processing have elapsed.

    Because LiveWire keeps the binary data that blobLink retrieves from the database in active memory, requests that retrieve a large amount of binary data can exceed dynamic memory on the server. Use discretion when retrieving binary data from databases.

    Examples

    The following example creates a cursor from the rockStarBios table and uses blobLink to create links to images retrieved from the photos column:

    write("Click a link to display an image:<P>")
    cursor = database.cursor("select * from rockStarBios")
    while(cursor.next()) {
       write(cursor.photos.blobLink("image/gif", "Image " + cursor.id))
       write("<BR>")
    }
    cursor.close()
    
    This example generates the following HTML:

    Click a link to display an image:<P>
    <A HREF="LIVEWIRE_TEMP1">Image 1</A><BR>
    <A HREF="LIVEWIRE_TEMP2">Image 2</A><BR>
    <A HREF="LIVEWIRE_TEMP3">Image 3</A><BR>
    <A HREF="LIVEWIRE_TEMP4">Image 4</A><BR>
    
    The LIVEWIRE_TEMP files in this example are temporary files created in memory by the blobLink method.

    See also

    blob function, blobImage method

    bold

    Method. Causes a string to be displayed as bold as if it were in a B tag.

    Syntax

    stringName.bold()
    

    Parameters

    stringName is any string or a property of an existing object.

    Method of

    string

    Description

    Use the bold method with the write or writeln methods to format and display a string in a document. In LiveWire, use the write function to display the string.

    Examples

    The following example uses string methods to change the formatting of a string:

    var worldString="Hello, world" 
    document.write(worldString.blink())
    document.write("<P>" + worldString.bold())
    document.write("<P>" + worldString.italics())
    document.write("<P>" + worldString.strike())
    
    The previous example produces the same output as the following HTML:

    <BLINK>Hello, world</BLINK>
    <P><B>Hello, world</B>
    <P><I>Hello, world</I>
    <P><STRIKE>Hello, world</STRIKE>
    
    In LiveWire, you can generate this HTML by calling the write function instead of using document.write.

    See also

    blink, italics, strike methods

    byteToString

    Method. Converts a number that represents a byte into a string.

    Syntax

    File.byteToString(number)
    

    Parameters

    number is a number that represents a byte.

    Method of

    File

    Description

    Use the stringToByte and byteToString methods to convert data between binary and ASCII formats. The byteToString method converts the number argument into a string. This is a static method of the File object; you call this method without specifying the name of a specific File object.

    If the argument you pass into the byteToString method is not a number, the method returns an empty string.

    Examples

    The following example creates a copy of a text file, one character at a time. 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 readByte method reads the current character from the source file, and the byteToString method converts it into a string; the write method writes it to the target file. The last readByte method positions the pointer past the end of the file, ending the while loop. See the File object for a description of the pointer.

    // Create the source File object
    source = new File("c:/data/source.txt")
    
    // If the source file opens successfully, create a target file
    if (source.open("r")) {
       target = new File("c:/data/target.txt")
       target.open("w")
    
    // Copy the source file to the target
       while (!source.eof()) {
          data = File.byteToString(source.readByte())
          target.write(data);
       }
       source.close()
    }
       target.close()
    
    This example is similar to the example used for the write method of File. However, this example reads bytes from the source file and converts them to strings, instead of reading strings from the source file.

    See also

    stringToByte method

    callC

    Function. Calls an external function and returns the value the external function returns.

    Syntax

    callC(JSFunctionName, arguments...)
    

    Parameters

    JSFunctionName is the name of the function as it is identified with RegisterCFunction.

    arguments is a comma-separated list of arguments to the external function. The arguments can be any JavaScript values: strings, numbers, or Boolean values. The number of arguments must match the number of arguments required by the external function.

    Description

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

    The callC function returns the string value that the external function returns; callC can only return string values.

    Examples

    The following example assigns a value to the variable isRegistered according to whether the attempt to register the external function echoCCallArguments succeeds or fails. If isRegistered is true, the callC function executes.

    var isRegistered =
       registerCFunction("echoCCallArguments",
       "c:mypathmystuff.dll",
       "mystuff_EchoCCallArguments")
    if (isRegistered == true) {
       var returnValue =
       callC("echoCCallArguments","first arg", 42,true,"last arg")
       write(returnValue)
    }
    

    See also

    registerCFunction function

    ceil

    Method. Returns the least integer greater than or equal to a number.

    Syntax

    Math.ceil(number)
    

    Parameters

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

    Method of

    Math

    Examples

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

    function getCeil(x) {
       return Math.ceil(x)
    }
    
    If you pass getCeil the value 45.95, it returns 46; if you pass it the value -45.95, it returns -45.

    See also

    floor method

    charAt

    Method. Returns the character at the specified index.

    Syntax

    stringName.charAt(index)
    

    Parameters

    stringName is any string or a property of an existing object.

    index is any integer from zero to stringName.length - 1, or a property of an existing object.

    Method of

    string

    Description

    Characters in a string are indexed from left to right. The index of the first character is zero, and the index of the last character is stringName.length - 1. If the index you supply is out of range, JavaScript returns an empty string.

    Examples

    The following example displays characters at different locations in the string "Brave new world":

    var anyString="Brave new world"
    
    document.write("The character at index 0 is " + anyString.charAt(0))
    document.write("The character at index 1 is " + anyString.charAt(1))
    document.write("The character at index 2 is " + anyString.charAt(2))
    document.write("The character at index 3 is " + anyString.charAt(3))
    document.write("The character at index 4 is " + anyString.charAt(4))
    
    In LiveWire, you can display the same output by calling the write function instead of using document.write.

    See also

    indexOf, lastIndexOf methods

    clearError

    Method. Clears the current file error status.

    Syntax

    fileObjectName.clearError()
    

    Parameters

    fileObjectName is the name of a File object.

    Method of

    File

    Description

    The clearError method clears both the file error status (the value returned by the error method) and the value returned by the eof method.

    Examples

    See the example for the error method.

    See also

    error method

    client

    Object. Contains data specific to an individual client.

    Syntax

    To use a client object:

    1. client.propertyName
    2. client.methodName
    

    Parameters

    propertyName is a property that you create.

    methodName is one of the methods listed below or a method that you create.

    Property of

    None

    Description

    LiveWire automatically creates a client object each time an unknown client accesses an application. LiveWire creates a separate client object for each individual client that requests a page from the server. LiveWire has five different ways of maintaining client property values; for more information, see "Techniques for maintaining the client object."

    All requests by one client use the same client object, as long as those requests occur within the lifetime of that client object. By default, a client object persists until the associated client has been inactive for ten minutes. You can use the expiration method to change this default lifetime or the destroy method to explicitly destroy the client object.

    Use the client object to maintain data that is specific to an individual client. Although many clients can access an application simultaneously, the individual client objects keep their data separate. Each client object can track the progress of an individual client across multiple requests to the same application.

    Properties

    The client object has no predefined properties. You create custom properties to contain any client-specific data that is required by an application. LiveWire does not save client objects that have no property values.

    You can create a property for the client object by assigning it a name and a value. For example, you can create a client property to store a customer ID at the beginning of an application so a user does not have to enter it with each request.

    Methods

  • destroy
  • expiration

    Examples

    Example 1. This example dynamically assigns a customer ID number that is used for the lifetime of an application session. The assignId function creates an ID based on the user's IP address, and the customerId property saves the ID.

    <SERVER>client.customerId = assignId(request.ip)</SERVER>
    
    See also the examples for the project object for a way to sequentially assign a customer ID.

    Example 2. This example creates a customerId property to store a customer ID that a user enters into a form. The form is defined as follows:

    <FORM NAME="getCustomerInfo" METHOD="post">
    <P>Enter your customer ID: 
       <INPUT TYPE="text" NAME="customerNumber">
    </FORM>
    
    The following code assigns the value entered in the customerNumber field from the temporary request.clientNumber to the more permanent client.customerId:

    <SERVER>client.customerId=request.customerNumber</SERVER>
    

    See also

    project, request, server objects

    close (cursor object)

    Method. Closes a cursor.

    Syntax

    cursorName.close()
    

    Parameters

    cursorName is the name of a cursor object.

    Method of

    cursor object

    Description

    The close method closes a cursor and releases the memory it uses. If you do not explicitly close a cursor with the close method, LiveWire automatically closes all open cursors at the end of each client request.

    Examples

    The following example creates the rentalSet cursor, performs certain operations on it, and then closes it with the close method.

    // Create a cursor object
    rentalSet = database.cursor("SELECT * FROM rentals")
    
    // Perform operations on the cursor
    cursorOperations()
    
    //Close the cursor
    rentalSet.close()
    

    See also

    cursor method

    close (File object)

    Method. Closes an open file on the server.

    Syntax

    fileObjectName.close()
    

    Parameters

    fileObjectName is the name of a File object.

    Method of

    File

    Description

    When your application is finished with a file, you should close the file by calling the close method. If the file is not open, the close method fails. This method returns true if it is successful; otherwise, it returns false.

    Examples

    See the examples for the open method.

    See also

    open method

    columnName

    Method. Returns the name of a column in a cursor.

    Syntax

    cursorName.columName(index)
    

    Parameters

    cursorName is the name of a cursor object.

    index is an integer representing the ordinal number of the column, starting with zero.

    Method of

    cursor object

    Description

    The columnName method returns the name of each column in a cursor.

    Examples

    The following example assigns the name of the first column in the customerSet cursor to the variable header:

    customerSet=database.cursor(SELECT * FROM customer ORDER BY name)
    header = customerSet.columnName(0)
    

    See also

    columns method, cursorColumn object

    columns

    Method. Returns the number of columns in a cursor.

    Syntax

    cursorName.columns()
    

    Parameters

    cursorName is the name of a cursor object.

    Method of

    cursor object

    Description

    The columns method returns the number of columns in a cursor object. You can use the columns method with the cursorColumn array to iterate over each column in a cursor.

    Examples

    See Example 2 of the cursor object for an example of using the columns method with the cursorColumn array.

    The following example returns the number of columns in the cursor called custs:

    custs.columns()
    

    See also

    columnName method, cursor object

    commitTransaction

    Method. Commits the active transaction.

    Syntax

    database.commitTransaction()
    

    Method of

    database

    Description

    The commitTransaction method ends the current database transaction and commits all actions since the previous beginTransaction method. If there is no active transaction (that is, if the application has not issued a beginTransaction), commitTransaction is ignored. See "Managing transactions."

    The commitTransaction 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

    See the example for beginTransaction.

    See also

    beginTransaction, rollbackTransaction methods

    connect

    Method. Connects an application to a database and creates a database object.

    Syntax

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

    Parameters

    type is the database type, either "INFORMIX," "ORACLE," "SYBASE," or "ODBC."

    server is the name of the database server. The server name typically is established when the database is installed. For ODBC, this is the name of the ODBC service.

    user is the user name you use to log in to the database. Some RDBMS systems require this to be the same as your operating system login name; other systems maintain their own collections of valid user names.

    password is the password you use to log in to the database. If the database does not require a password, use an empty string.

    database is the name of the database you want to access, if your database server supports multiple databases. If multiple databases are not supported, use an empty string.

    Method of

    database

    Description

    To connect to a database, use the database object's connect method.

    LiveWire provides the following types of connections to a database:

  • 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. See the database object for a description of the types of connections.

    Examples

    The following if condition determines if an application is already connected to a database. If not, the connect method connects to an Informix database named mydb, on a server named blue, with user name ADMIN, and the password MANAGER.

    if (database.connected()) {
       isConnectedRoutine() }
    else {
       database.connect("INFORMIX", "blue", "ADMIN", "MANAGER", "mydb") }
    
    See the database object for examples of standard and serial connections.

    See also

    connected, disconnect methods; database object

    connected

    Method. Determines whether an application is connected to a database.

    Syntax

    database.connected()
    

    Method of

    database

    Description

    The connected method determines if an application is currently connected to a database. This method returns true if the application is connected; otherwise, it returns false.

    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 isConnectedRoutine function runs; if the application is not connected, the isNotConnected routine runs.

    if(database.connected()) {
       isConnectedRoutine() }
    else {
       isNotConnectedRoutine() }
    

    See also

    connect, disconnect methods

    cos

    Method. Returns the cosine of a number.

    Syntax

    Math.cos(number)
    

    Parameters

    number is a numeric expression representing the size of an angle in radians, or a property of an existing object.

    Method of

    Math

    Description

    The cos method returns a numeric value between -1 and one, which represents the cosine of the angle.

    Examples

    The following function returns the cosine of the variable x:

    function getCos(x) {
       return Math.cos(x)
    }
    
    If x equals Math.PI/2, getCos returns 6.123031769111886e-017; if x equals Math.PI, getCos returns -1.

    See also

    acos, asin, atan, sin, tan methods

    cursor method

    Method. Creates a cursor object.

    Syntax

    cursorName = database.cursor("sqlStatement",[updatable])
    

    Parameters

    cursorName is the name of the cursor object you are creating.

    sqlStatement is a JavaScript string representing a SQL SELECT statement supported by the database server.

    updatable is a Boolean parameter indicating if the cursor is updatable.

    Method of

    database

    Description

    The cursor method creates a cursor object that contains the answer set returned by a SQL SELECT statement. The SELECT statement is passed to the cursor method as the sqlStatement argument.

    You can perform the following tasks with the cursor object:

  • Modify data in a server table.
  • Navigate in a server table.
  • Customize the display of the answer set returned by a database query. The cursor method does not automatically display the data returned in the answer set. To display this data, you must create custom HTML code. This code usually displays the answer set in an HTML table, as shown in Example 3. The SQLTable method is an easier way to display the output of a database query, but you cannot navigate, modify data, or control the format of the output.

    The optional parameter updatable specifies whether you can modify the cursor object you create with the cursor method. To create a cursor object you can modify, specify updatable as true. If you do not specify a value for the updatable parameter, it is false by default.

    If you create an updatable cursor object, the answer set returned by the sqlStatement parameter must be updatable. For example, the SELECT statement in the sqlStatement parameter cannot contain a GROUP BY clause; in addition, the query usually must retrieve key values from a table. For more information on constructing updatable queries, consult your database vendor's documentation.

    Examples

    Example 1. The following example creates the updatable cursor custs and returns the columns ID, CUST_NAME, and CITY from the customer table:

    custs = database.cursor("SELECT ID, CUST_NAME, CITY
       FROM customer", true)
    
    Example 2. You can construct the SELECT statement with the string concatenation operator (+) and string variables such as client or request property values, as shown in the following example:

    custs = database.cursor("select * from customer
       where customerID = " + request.customerID);
    
    Example 3. The following example demonstrates how to format the answer set returned by the cursor method as an HTML table. This example first creates the videoSet cursor object, and then displays two columns of its data (videoSet.title and videoSet.synopsis).

    // Create the videoSet cursor
    <SERVER>
    videoSet = database.cursor("select * from videos
       where videos.numonhand > 0 order by title");
    </SERVER>
    
    // Begin creating an HTML table to contain the answer set
    // Specify titles for the two columns in the answer set
    <TABLE BORDER>
    <CAPTION> Videos on Hand </CAPTION>
    <TR>
       <TH>Title</TH>
       <TH>Synopsis</TH>
    </TR>
    
    // Use a while loop to iterate over each row in the cursor
    <SERVER>
    while(videoSet.next()) {
    </SERVER>
    
    // Use write statements to display the data in both columns
    <TR>
       <TH><A HREF=\Q"rent.html?videoID="+videoSet.id\Q>
                   <SERVER>write(videoSet.title)</SERVER></A></TH>
       <TD><SERVER>write(videoSet.synopsis)</SERVER></TD>
    </TR>
    
    // End the while loop
    <SERVER>
    }
    </SERVER>
    
    // End the HTML table
    </TABLE>
    
    The values in the videoSet.title column are displayed within the HTML A tag so a user can click them as links. When a user clicks a title, the rent.html page opens and the column value videoSet.id is passed to it as the value of request.videoID.

    See also

    SQLTable method, cursor object

    cursor object

    Object. Contains the answer set returned by a SQL SELECT statement.

    Syntax

    To create a cursor object:

    cursorName = database.cursor("sqlStatement",[updateable])
    
    For details on creating a cursor object, see the cursor method.

    To use a cursor object:

    cursorName.propertyName
    cursorName.methodName
    
    To use a cursorColumn object:

    1.cursorName.cursorColumn
    2.cursorName[index]
    3.cursorName.cursorColumn.methodName
    4.cursorName[index].methodName
    

    Parameters

    cursorName is the name you give the cursor object.

    index is an integer representing the ordinal number of the column, starting with zero.

    cursorColumn is the name of a column in the cursor; it is the same as the name of the column in the table.

    propertyName is one of the properties listed below.

    methodName is one of the methods listed below.

    Property of

    The cursor object is a top-level object.

    The cursorColumn array is a property of cursor object.

    Description

    A cursor object contains the data returned by a SQL SELECT statement. You can perform the following tasks with the cursor object:

  • Modify data in a server table (deleteRow, insertRow, and updateRow methods).
  • Navigate in a server table (next method).
  • Customize the display of the answer set returned by a database query.

    You can use a cursor object to customize the display of the answer set by specifying which columns and rows to display and how to display them. The cursor object does not automatically display the data returned in the answer set. To display this data, you must create HTML code such as that shown in Example 3 for the cursor method.

    A pointer indicates the current row in a cursor. When you create a cursor, the pointer is initially positioned before the first row of the cursor. The next method makes the following row in the cursor the current row.

    Use the close method to close a cursor and release the memory it uses. If you do not explicitly close a cursor with the close method, LiveWire automatically closes all open cursors at the end of each client request.

    The cursorColumn array

    Each of the columns in a cursor is a property of the cursor, and also an object with its own properties. cursorColumn is a variable that represents the name of a column in a cursor object. Unlike other properties in JavaScript, the cursorColumn property is not case sensitive, because SQL is not case sensitive.

    You can also refer to columns in a cursor object as elements of an array. Columns in the cursor are assigned indexes in the array sequentially; the first column is index zero. You can use the columns method with this array to iterate over every column in a cursor.

    When you create a cursor column by using an aggregate function, you must refer to the column by its index, because the column does not have a name. See Example 3 for more information.

    Properties

    The cursor object has the following properties:

  • cursorColumn The cursorColumn array has the following properties:

  • None

    Methods

    The cursor object has the following methods:

    The cursorColumn array has the following methods:

  • blobImage
  • blobLink

    Examples

    See the cursor method for examples of creating a cursor object and displaying its data in an HTML table.

    Example 1: Using column titles as cursorColumn properties. The following example creates the customerSet cursor object containing the id, name, and city rows from the customer table. The next method moves the pointer to the first row of the cursor.

    // Create a cursor object
    customerSet = database.cursor("SELECT id, name, city FROM customer")
    
    // Navigate to the first row
    customerSet.next()
    
    write(customerSet.id + "<BR>")
    write(customerSet.name + "<BR>")
    write(customerSet.city + "<BR>")
    
    // Close the cursor
    customerSet.close()
    
    The id, name, and city columns become the cursorColumn properties customerSet.id, customerSet.name, and customerSet.city. Because the pointer is in the first row of the cursor, the write method displays the values of these properties for the first row.

    Example 2: Iterating with the cursorColumn array. In this example, the cursorColumn array is used in a for statement to iterate over each column in the customerSet cursor.

    // Create a cursor object
    customerSet = database.cursor("SELECT id, name, city FROM customer")
    
    // Navigate to the first row
    customerSet.next()
    
    // Start a for loop
    for ( var i = 0; i < customerSet.columns(); i++) {
    write(customerSet[i] + "<BR>") }
    
    // Close the cursor
    customerSet.close()
    
    Because the next statement moves the pointer to the first row, the preceding code displays values similar to the following:

    1
    Barnes, Allie
    Newport
    
    Example 3. Using the cursorColumn array with an aggregate. In this example, the salarySet cursor contains a column created by the aggregate function MAX.

    salarySet=database.cursor("SELECT name, MAX(salary) FROM employee")
    
    Because the aggregate column does not have a name, you must use the cursorColumn array to refer to it, as follows:

    write(salarySet[1])
    

    See also

    blob function, cursor method

    cursorColumn

    Property. An array of objects corresponding to the columns in a cursor. See the cursor object for information.