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

In the following example, the user enters a number in the first text box and presses the Calculate button to display the absolute value of the number.

<FORM>
<P>Enter a number:
<INPUT TYPE="text" NAME="absEntry">

<P>The absolute value is:
<INPUT TYPE="text" NAME="result">

<P>
<INPUT TYPE="button" VALUE="Calculate"
   onClick="form.result.value = Math.abs(form.absEntry.value)">

</FORM>

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 0 and pi radians. If the value of number is outside the suggested range, the return value is always 0.

Examples

// Displays the value 0
document.write("The arc cosine of 1 is " + Math.acos(1))

// Displays the value 3.141592653589793
document.write("<P>The arc cosine of -1 is " + Math.acos(-1))

// Displays the value 0
document.write("<P>The arc cosine of 2 is " + Math.acos(2))

See also

asin, atan, cos, sin, tan methods

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, and protocol 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, then call write or writeln to display the anchor in a document.

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.

Anchors created with the anchor method become elements in the anchors array. See the anchor object for information about the anchors array.

Examples

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

var myString="Table of Contents"

msgWindow=window.open("","displayWindow")
msgWindow.document.writeln(myString.anchor("contents_anchor"))
msgWindow.document.close()
The previous example produces the same output as the following HTML:

<A NAME="contents_anchor">Table of Contents</A>

See also

link method

arguments array

Property. An array corresponding to elements within a user-defined 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 that are passed to the function, and then treat each argument by using the arguments array.

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

Properties

  • length

    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 indicated type of list. 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>
    

    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 the suggested range, the return value is always 0.

    Examples

    // Displays the value 1.570796326794897 (pi/2)
    document.write("The arc sine of 1 is " + Math.asin(1))
    
    // Displays the value -1.570796326794897 (-pi/2)
    document.write("<P>The arc sine of -1 is " + Math.asin(-1))
    
    // Displays the value 0 because the argument is out of range
    document.write("<P>The arc sine of 2 is " + Math.asin(2))
    

    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

    // Displays the value 0.7853981633974483
    document.write("The arc tangent of 1 is " + Math.atan(1))
    
    // Displays the value -0.7853981633974483
    document.write("<P>The arc tangent of -1 is " + Math.atan(-1))
    
    // Displays the value 0.4636476090008061
    document.write("<P>The arc tangent of .5 is " + Math.atan(.5))
    

    See also

    acos, asin, cos, sin, tan methods

    beginTransaction

    Method. Begins an SQL transaction.

    Syntax

    database.beginTransaction()
    

    Method of

    database

    Description

    The beginTransaction method starts a new database transaction.

    You can group methods 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.

    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 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, and see Managing Transactions for more information about transactions.

    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 0, 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 and 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.

    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>
    

    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.

    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>
    

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

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

    format is a string specifying the image format.

    altText is a string indicating text to display if the client browser does not display images.

    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.

    heightPixels is a string specifying the height of the image in pixels.

    borderPixels is a string specifying the size of the outline border in pixels if the image is a hyperlink.

    ismap is a Boolean value specifying whether the graphic is an image map.

    Method of

    cursorColumn array (see cursor object)

    Description

    The blobImage method displays a BLOb from a database column as if it were in an <IMG> tag. Most of the parameters of the blobImage method reflect an attribute of the <IMG> tag:

  • altText reflects the ALT attribute.
  • align reflects the ALIGN attribute.
  • widthPixels reflects the WIDTH attribute.
  • heightPixels reflects the HEIGHT attribute.
  • borderPixels reflects the BORDER attribute.
  • ismap reflects the ISMAP attribute. The format parameter can be "GIF", "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.

    If the client browser is not able to display the image format, you should specify the altText parameter to display a string instead of a graphic.

    The ismap parameter specifies whether the graphic is a clickable image map. If isamap is true, the graphic is an image map; otherwise, the graphic is not an image map.

    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 as if it were within an <A> tag.

    Syntax

    cursorName.cursorColumn.blobLink(mimeType, linkText)
    

    Parameters

    cursorName is the name of a cursor object.

    cursorColumn is 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 as if it were within an <A> tag.

    Use the blobLink method when you don't want to display all the 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 on 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 displays text as if it were created by 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. blobLink creates a link within an <A> tag to each of these temporary files.

    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.

    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>
    

    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. 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...)
    
    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:\\mypath\\mystuff.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

    //Displays the value 46
    document.write("The ceil of 45.95 is " + Math.ceil(45.95))
    
    //Displays the value -45
    document.write("<P>The ceil of -45.95 is " + Math.ceil(-45.95))
    

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

    See also

    indexOf, lastIndexOf methods

    clearError

    Method. Clears the current error status.

    Syntax

    fileObjectName.clearError()
    

    Parameters

    fileObjectName is the name of a File object.

    Method of

    File

    Description

    The clearError method clears both the 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 accesses the server. There may be hundreds or thousands of client objects active at a single time.

    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 pre-defined 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, and server objects

    close (cursor object)

    Method. Closes a cursor.

    Syntax

    cursorName.close()
    

    Parameters

    cursorName is the name of a cursor object.

    Method of

    cursor

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

    Method of

    cursor

    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

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

  • cursorColumn 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), any commitTransaction and rollbackTransaction statements are ignored.

    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 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, and see Managing Transactions for more information about transactions.

    Examples

    See the example for beginTransaction.

    See also

    beginTransaction and 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 "ILLUSTRA".

    server is the name of the database server. The server name is typically established when the database is installed.

    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 and 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 and 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 1, which represents the cosine of the angle.

    Examples

    //Displays the value 6.123031769111886e-017
    document.write("The cosine of PI/2 radians is " + Math.cos(Math.PI/2))
    
    //Displays the value -1
    document.write("<P>The cosine of PI radians is " + Math.cos(Math.PI))
    
    //Displays the value 1
    document.write("<P>The cosine of 0 radians is " + Math.cos(0))
    

    See also

    acos, asin, atan, sin, tan methods

    cursor method

    Method. Creates a cursor object.

    Syntax

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

    Parameters

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

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

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

    Method of

    database

    Description

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

    The cursor object lets you perform the following tasks:

  • 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 it does not let you modify data, navigate, or control the format of the output.

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

    If you create an updateable cursor object, the answer set returned by the sqlStatement parameter must be updateable. 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 updateable queries, consult your database vendor's documentation.

    Examples

    Example 1. The following example creates the updateable 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 an 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.

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

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

    propertyName is one of the properties below.

    methodName is one of the methods below.

    Property of

    The cursor object is a top-level object.

    The cursorColumn array is a property of cursor.

    Description

    A cursor object contains the data returned by an SQL SELECT statement. A cursor object lets you perform the following tasks:

  • 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. A cursor object lets you customize the display of the answer set by specifying which columns to display, which 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 as 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 0. 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:

    Methods

    The cursor object has the following methods:

  • close
  • columnName
  • columns
  • deleteRow
  • insertRow
  • next
  • updateRow 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 above 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.