# 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:

- codeName is the code name of the client. For example, "Mozilla" specifies Navigator.
- releaseNumber is the version number of the client. For example, "2.0b4" specifies Navigator 2.0, beta 4.
- platform is the platform upon which the client is running. For example, "Win16" specifies a 16-bit version of Windows, such as Windows 3.11.
- country is either "I" for the international release or "U" for the domestic U.S. release. The domestic release has a stronger encryption feature than the international release.
- platformIdentifier is an optional identifier that further specifies the platform. For example, in Navigator 1.1, platform is "windows" and platformIdentifier is "32bit." In Navigator 2.0, both pieces of information are contained in the platform designation. For example, in Navigator 2.0, the previous platform is expressed as "WinNT."

#### 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:

close (cursor object) 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 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.