## random

Method. Returns a pseudo-random number between zero and one. This method is available on Unix platforms only.

#### Syntax

    Math.random()

#### Method of

Math

#### Examples

    //Returns a random number between 0 and 1

    function getRandom() {

       return Math.random()

    }

## read

Method. Reads data from a file into a string.

#### Syntax

    fileObjectName.read(count)

#### Parameters

fileObjectName is the name of a File object.

count is an integer specifying the number of characters to read.

#### Method of

File

#### Description

The read method reads the specified number of characters from a file, starting from the current position of the pointer. If you attempt to read more characters than the file contains, the method reads as many characters as possible. This method moves the pointer the number of characters specified by the count parameter. See the File object for a description of the pointer.

The read method returns the characters it reads as a string.

Use the read method to read information from a text file; use the readByte method to read data from a binary file.

#### Examples

The following example references the file `info.txt`, which contains the string "Hello World." The first read method starts from the beginning of the file and reads the character "H." The second read method starts from offset six and reads the characters "World."

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

    dataFile.open("r")

    write("The next character is " + dataFile.read(1) + "<BR>")

    dataFile.setPosition(6)

    write("The next five characters are " + dataFile.read(5) + "<BR>")

    dataFile.close()

This example displays the following information:

    The next character is H

    The next five characters are World

#### See also

readByte method, readln method, write method

## readByte

Method. Reads the next byte from an open file and returns its numeric value.

#### Syntax

    fileObjectName.readByte()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

The readByte method reads the next byte from a file, starting from the current position of the pointer. This method moves the pointer one byte. See the File object for a description of the pointer.

The readByte method returns the byte it reads as a number. If the pointer is at the end of the file when you issue readByte, the method returns -1.

Use the readByte method to read information from a binary file. You can use the readByte method to read from a text file, but you must use the byteToString method to convert the value to a string. Generally it is better to use the read method to read information from a text file.

You can use the writeByte method to write data read by the readByte method to a file.

#### Examples

This example creates a copy of a binary file. 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 byte from the source file, and the writeByte method writes it to the target file. The last readByte method positions the pointer past the end of the file, ending the while loop.

    // Create the source File object

    source = new File("c:/data/source.gif")

    // If the source file opens successfully, create a target file

    if (source.open("rb")) {

       target = new File("c:/data/target.gif")

       target.open("wb")

    // Copy the source file to the target

       while (!source.eof()) {

          data = source.readByte()

          target.writeByte(data);

       }

       source.close();

    }

    target.close()

#### See also

read, readln, writeByte methods

## readln

Method. Reads the current line from an open file and returns it as a string.

#### Syntax

    fileObjectName.readln()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

The readln method reads the current line of characters from a file, starting from the current position of the pointer. If you attempt to read more characters than the file contains, the method reads as many characters as possible. This method moves the pointer to the beginning of the next line. See the File object for a description of the pointer.

The readln method returns the characters it reads as a string.

The line separator characters ("r" and "n" on Windows platforms and "n" on Unix platforms) are not included in the string that the readln method returns. The r character is skipped; n determines the actual end of the line.

Use the readln method to read information from a text file; use the readByte method to read data from a binary file. You can use the writeln method to write data read by the readln method to a file.

#### Examples

See the example for the eof method.

#### See also

read, readByte, writeln methods

## redirect

Function. Redirects the client to the specified URL.

#### Syntax

    redirect(location)

#### Parameters

location is the URL to which you want to redirect the client.

#### Description

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

The redirect function redirects the client browser to the URL specified by the location parameter. The value of location can be relative or absolute.

When the client encounters a redirect function, it loads the specified page immediately and discards the current page. The client does not execute or load any HTML or script statements in the page following the redirect function.

Use the addClient function to preserve client object property values if using client URL maintenance. See addClient for more information.

#### Examples

The following example uses the redirect function to redirect a client browser:

    redirect("http://www.hardRain.com/lw/apps/newhome.html")

The page displayed by the `newhome.html` link could contain content such as the following:

    <H1>New location</H1>

    The URL you tried to access has been moved to:<BR>

    <LI><A HREF=http://www.hardRain.com/lw/apps/index.html>

       http://www.hardRain.com/lw/apps/index.html</A>

    <P>This notice will remain until 12/31/96.

#### See also

addClient function

## registerCFunction

Function. Registers an external function for use with a LiveWire application.

#### Syntax

    registerCFunction(JSFunctionName, libraryPath, externalFunctionName)

#### Parameters

JSFunctionName is the name of the function as it is called in JavaScript.

libraryPath is the full filename and path of the library, using the conventions of your operating system.

externalFunctionName is the name of the function as it is defined in the library.

#### Description

Use registerCFunction to make an external function available to a LiveWire application. The function can be written in any language, but you must use C calling conventions.

To use an external function in a LiveWire application, register the function with registerCFunction, and then call it with the callC function. Once an application registers a function, you can call the function any number of times.

The registerCFunction function returns true if the external function is registered successfully; otherwise, it returns false. For example, registerCFunction can return false if LiveWire cannot find either the library or the specified function inside the library.

To use a backslash () character as a directory separator in the libraryPath parameter, you must enter a double backslash (). The single backslash is a reserved character.

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

#### Examples

See the example for the callC function.

#### See also

callC function

## request

Object. Contains data specific to the current client request.

#### Syntax

To use a request object:

    1. request.propertyName

    2. request.methodName

#### Parameters

propertyName is one of the properties listed below or a property that you create.

methodName is a method that you create.

#### Property of

None

#### Description

LiveWire creates a request object each time the client makes a request of the server. LiveWire destroys the request object after the server responds to the request, typically by providing the requested page.

The properties listed below are read-only properties that are initialized automatically when a request object is created. In addition to these predefined properties, you can create custom properties to store application-specific data about the current request.

### Custom properties

You can create a property for the request object by assigning it a name and a value. For example, you can create a request property to store the date and time that a request is received so you can enter the date into the page content.

You can also create request object properties by encoding them in a URL. When a user navigates to the URL by clicking its link, the properties are created and instantiated to values that you specify. The properties are valid on the destination page.

Use the following syntax to encode a request property in a URL:

    <A HREF="URL?propertyName=value[&propertyName=value...]">

where:

- URL is the URL the page that will get the new request properties.
- propertyName is the name of the property you are creating.
- value is the initial value of the new property.

Use escape to encode non-alphanumeric values in the URL string.

#### Properties

The following properties are initialized automatically when a request object is created:

agent inputName ip | method protocol (request object)

You can also create custom properties for the request object.

#### Methods

None

#### Examples

Example 1. This example displays the values of the predefined properties of the request object. In this example, an HTML form is defined as follows:

    <FORM METHOD="post" NAME="idForm" ACTION="hello.html">

    <P>Last name:

       <INPUT TYPE="text" NAME="lastName" SIZE="20">

    <BR>First name:

       <INPUT TYPE="text" NAME="firstName" SIZE="20">

    </FORM>

The following code displays the values of the request object properties that are created when the form is submitted:

    agent = <SERVER>write(request.agent)</SERVER><BR>

    ip = <SERVER>write(request.ip)</SERVER><BR>

    method = <SERVER>write(request.method)</SERVER><BR>

    protocol = <SERVER>write(request.protocol)</SERVER><BR>

    lastName = <SERVER>write(request.lastName)</SERVER><BR>

    firstName = <SERVER>write(request.firstName)</SERVER>

When it executes, this code displays information similar to the following:

    agent = "Mozilla/2.0 (WinNT;I)"

    ip = "165.327.114.147"

    method = "GET"

    protocol = "HTTP/1.0"

    lastName = "Schaefer"

    firstName = "Jesse"

Example 2. The following example creates the requestDate property and initializes it with the current date and time:

    request.requestDate = new Date()

Example 3. When a user clicks the following hyperlink, the `info.html` page is loaded, `request.accessedFrom` is created and initialized to "hello.html," and `request.formId` is created and initialized to "047."

    Click here for

       <A HREF="info.html?accessedFrom=hello.html&formId=047">

       additional information</A>.

#### See also

client, project, server objects

## rollbackTransaction

Method. Rolls back the active transaction.

#### Syntax

    database.rollbackTransaction()

#### Method of

database

#### Description

The rollbackTransaction method rolls back the current transaction and undoes all modifications since the previous beginTransaction.

If there is no active transaction (that is, if the application has not issued a beginTransaction), rollbackTransaction is ignored.

The rollbackTransaction 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 a description of database status codes.

#### Examples

See the example for the beginTransaction method.

#### See also

beginTransaction, commitTransaction methods

## round

Method. Returns the value of a number rounded to the nearest integer.

#### Syntax

    Math.round(number)

#### Parameters

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

#### Method of

Math

#### Description

If the fractional portion of number is .5 or greater, the argument is rounded to the next highest integer. If the fractional portion of number is less than .5, the argument is rounded to the next lowest integer.

#### Examples

    //Displays the value 20

    document.write("The rounded value is " + Math.round(20.49))

    //Displays the value 21

    document.write("<P>The rounded value is " + Math.round(20.5))

    //Displays the value -20

    document.write("<P>The rounded value is " + Math.round(-20.5))

    //Displays the value -21

    document.write("<P>The rounded value is " + Math.round(-20.51))

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