## File

Object. Lets an application interact with a physical file on the server.

#### Syntax

To create a File object:

    fileObjectName = new File("path")

To use a File object:

    fileObjectName.methodName

#### Parameters

fileObjectName is the name of the new File object.

path is the path and filename in the format of the server's file system (not a URL path).

methodName is any of the methods listed below.

#### Property of

None

#### Description

You can use the File object to write to or read from a file on the server. For security reasons, you cannot programmatically access the file system of client machines.

You can use the File object to generate persistent HTML or data files without using a database server. Information stored in a file, unlike information stored in a LiveWire object, is preserved when the server goes down.

Exercise caution when using the File object. An application can read and write files anywhere the operating system allows. If you create an application that writes to or reads from your file system, you should ensure that users cannot misuse this capability.

Specify the full path, including the filename, for the path parameter of the File object you want to create. The path must be an absolute path; do not use a relative path.

If the physical file specified in the path already exists, LiveWire references it when you call methods for the object. If the physical file does not exist, you can create it by calling the open method.

You can display the name and path of a physical file by calling the write function and passing it the name of the related File object.

A pointer indicates the current position in a file. If you open a file in the a or a+ mode, the pointer is initially positioned at the end of the file; otherwise, it is initially positioned at the beginning of the file. In an empty file, the beginning and end of the file are the same. Use the eof, getPosition, and setPosition methods to specify and evaluate the position of the pointer. See the open method for a description of the modes in which you can open a file.

#### Properties

None

#### Methods

The File object has the following methods:

byteToString clearError close (File object) eof error exists flush method getLength getPosition | open read readByte readln setPosition stringToByte write method writeByte writeln

#### Examples

Example 1. The following example creates the File object userInfo that references a physical file called `info.txt`. The `info.txt` file resides in the same directory as the application's `.web` file:

    userInfo = new File("info.txt")

Example 2. In the following example, the File object references a physical file with an absolute path:

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

Example 3. The following example displays the name of a File object on-screen.

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

    write(userInfom)

## fixed

Method. Causes a string to be displayed in fixed-pitch font as if it were in a TT tag.

#### Syntax

    stringName.fixed()

#### Parameters

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

#### Method of

string

#### Description

Use the fixed 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 the fixed method to change the formatting of a string:

    var worldString="Hello, world"

    document.write(worldString.fixed())

The previous example produces the same output as the following HTML:

    <TT>Hello, world</TT>

In LiveWire, you can generate this HTML by calling the write function instead of using `document.write`.

## floor

Method. Returns the greatest integer less than or equal to a number.

#### Syntax

    Math.floor(number)

#### Parameters

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

#### Method of

Math

#### Examples

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

    function getFloor(x) {

       return Math.floor(x)

    }

If you pass getFloor the value 45.95, it returns 45; if you pass it the value -45.95, it returns -46.

#### See also

ceil method

## flush function

Function. Sends data from previously issued write functions to the client.

#### Syntax

    flush()

#### Description

To improve performance, LiveWire buffers the output of the write function and sends it to the client in 64K blocks. The flush function sends to the client any data that is in the buffer as a result of previously issued write functions.

Use the flush function to control when data is sent to the client. For example, call the flush function before an operation that creates a delay, such as a database query. If a database query retrieves a large number of rows, you can flush the buffer after retrieving a small number of rows to prevent long delays in displaying data.

Because the flush function updates the client's cookie file as part of the HTTP header, you should perform any changes to the client object before flushing the buffer, if you are using client cookie to maintain the client object.

Do not confuse the flush method of the File object with the top-level flush function. The flush function is a top-level LiveWire function that is not associated with any object.

#### Examples

The following example iterates through a text file and outputs each line in the file, preceded by a line number and five spaces. The flush function then causes the client to display the output.

    while (!In.eof()) {

       AscLine = In.readln();

       if (!In.eof())

          write(LPad(LineCount + ": ", 5), AscLine, "n");

       LineCount++;

       flush();

    }

#### See also

write function

## flush method

Method. Writes the content of the internal buffer to a file.

#### Syntax

    fileObjectName.flush()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

When you write to a file with any of the File object methods (write, writeByte, or writeln), the data is buffered internally. The flush method writes the buffer to the physical file. The flush method returns true if it is successful; otherwise, it returns false.

Do not confuse the flush method of the File object with the top-level flush function. The flush function flushes a buffer of data and causes it to display in the client browser; the flush method flushes a buffer of data to a physical file.

#### Examples

See the write method for an example of the flush method.

#### See also

write method, writeByte method, writeln method

## fontcolor

Method. Causes a string to be displayed in the specified color as if it were in a FONT COLOR=color tag.

#### Syntax

    stringName.fontcolor(color)

#### Parameters

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

color is a string or a property of an existing object, expressing the color as a hexadecimal RGB triplet or as one of the string literals listed in "Color values."

#### Method of

string

#### Description

Use the fontcolor 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.

If you express color as a hexadecimal RGB triplet, you must use the format rrggbb. For example, the hexadecimal RGB values for salmon are red=FA, green=80, and blue=72, so the RGB triplet for salmon is "FA8072."

The fontcolor method overrides a value set in the fgColor property.

#### Examples

The following example uses the fontcolor method to change the color of a string:

    var worldString="Hello, world"

    document.write(worldString.fontcolor("maroon") +

       " is maroon in this line")

    document.write("<P>" + worldString.fontcolor("salmon") +

       " is salmon in this line")

    document.write("<P>" + worldString.fontcolor("red") +

       " is red in this line")

    document.write("<P>" + worldString.fontcolor("8000") +

       " is maroon in hexadecimal in this line")

    document.write("<P>" + worldString.fontcolor("FA8072") +

       " is salmon in hexadecimal in this line")

    document.write("<P>" + worldString.fontcolor("FF00") +

       " is red in hexadecimal in this line")

The previous example produces the same output as the following HTML:

    <FONT COLOR="maroon">Hello, world</FONT> is maroon in this line

    <P><FONT COLOR="salmon">Hello, world</FONT> is salmon in this line

    <P><FONT COLOR="red">Hello, world</FONT> is red in this line

    <FONT COLOR="8000">Hello, world</FONT> is maroon in hexadecimal in this line

    <P><FONT COLOR="FA8072">Hello, world</FONT> is salmon in hexadecimal in this line

    <P><FONT COLOR="FF00">Hello, world</FONT> is red in hexadecimal in this line

In LiveWire, you can generate this HTML by calling the write function instead of using `document.write`.

## fontsize

Method. Causes a string to be displayed in the specified font size as if it were in a FONTSIZE=size tag.

#### Syntax

    stringName.fontsize(size)

#### Parameters

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

size is an integer between one and seven, a string representing a signed integer between one and seven, or a property of an existing object.

#### Method of

string

#### Description

Use the fontsize 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.

When you specify size as an integer, you set the size of stringName to one of the seven defined sizes. When you specify size as a string such as "-2," you adjust the font size of stringName relative to the size set in the BASEFONT tag.

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

big, small methods

## getDate

Method. Returns the day of the month for the specified date.

#### Syntax

    dateObjectName.getDate()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getDate is an integer between one and thirty-one.

#### Examples

The second statement below assigns the value twenty-five to the variable day, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    day = Xmas95.getDate()

#### See also

setDate method

## getDay

Method. Returns the day of the week for the specified date.

#### Syntax

    dateObjectName.getDay()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getDay is an integer corresponding to the day of the week: zero for Sunday, one for Monday, two for Tuesday, and so on.

#### Examples

The second statement below assigns the value 1 to weekday, based on the value of the Date object Xmas95. This is because December 25, 1995, is a Monday.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    weekday = Xmas95.getDay()

## getHours

Method. Returns the hour for the specified date.

#### Syntax

    dateObjectName.getHours()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getHours is an integer between zero and twenty-three.

#### Examples

The second statement below assigns the value twenty-three to the variable hours, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    hours = Xmas95.getHours()

#### See also

setHours method

## getLength

Method. Returns the length of a file.

#### Syntax

    fileObjectName.getLength()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

If this method is successful, it returns the number of bytes in a binary file or characters in a text file; otherwise, it returns -1.

#### Examples

The following example copies a file one character at a time. This example uses getLength as a counter in a for loop to iterate over every character in the file.

    // 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("a")

    // Copy the source file to the target

       for (var x = 0; x < source.getLength(); x++) {

       source.setPosition(x)

       data = source.read(1)

       target.write(data)

       }

       source.close()

    }

       target.close()

## getMinutes

Method. Returns the minutes in the specified date.

#### Syntax

    dateObjectName.getMinutes()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getMinutes is an integer between zero and fifty-nine.

#### Examples

The second statement below assigns the value fifteen to the variable minutes, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    minutes = Xmas95.getMinutes()

#### See also

setMinutes method

## getMonth

Method. Returns the month in the specified date.

#### Syntax

    dateObjectName.getMonth()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getMonth is an integer between zero and eleven. Zero corresponds to January, one to February, and so on.

#### Examples

The second statement below assigns the value eleven to the variable month, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    month = Xmas95.getDate()

#### See also

setMonth method

## getOptionValue

Function. Returns the text of a selected OPTION in a SELECT form element.

#### Syntax

    getOptionValue(name, index)

#### Parameters

name is specified by the NAME attribute of the SELECT tag, and index is the zero-based ordinal index of the selected option. The function returns a string containing the text for the selected option, as specified by the associated OPTION tag.

#### Description

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

The HTML SELECT tag allows multiple values to be associated with a single form element, with the MULTIPLE attribute. If your application requires select lists that allow multiple selected options, you must use the getOptionValue function to get the values of selected options in JavaScript.

#### Examples

Suppose you have the following form element:

    <SELECT NAME="what-to-wear" MULTIPLE SIZE=8>

    	<OPTION SELECTED>Jeans

    	<OPTION>Wool Sweater

    	<OPTION SELECTED>Sweatshirt

    	<OPTION SELECTED>Socks

    	<OPTION>Leather Jacket

    	<OPTION>Boots

    	<OPTION>Running Shoes

    	<OPTION>Cape

    </SELECT>

You could process the input from this select list in server-side JavaScript as follows:

    var loopIndex = 0

    var loopCount = getOptionValueCount("what-to-wear") // 3 by default

    while ( loopIndex < loopCount ) {

    	var optionValue = getOptionValue("what-to-wear",loopIndex)

    	write("<br>Item #" + loopIndex + ": " + optionValue + "n")

    	loopIndex++

    }

If the user kept the default selections, this script would return

Item #1: JeansItem #3: SweatshirtItem #4: Socks

#### See also

getOptionValueCount

## getOptionValueCount

Function. Returns the number of options selected by the user in a SELECT form element.

#### Syntax

    getOptionValueCount(name)

#### Parameters

name is specified by the NAME attribute of the SELECT tag.

#### Description

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

Use this function with getOptionValue to process user input from SELECT form elements that allow multiple selections.

#### Examples

See the example for getOptionValue.

#### See also

getOptionValueCount

## getPosition

Method. Returns the current position of the pointer in an open file.

#### Syntax

    fileObjectName.getPosition()

#### Parameters

fileObjectName is the name of a File object.

#### Method of

File

#### Description

Use the getPosition method to determine the position of the pointer in a file. See the File object for a description of the pointer. The getPosition method returns the current pointer position; the first byte in a file is byte zero. This method returns -1 if there is an error.

#### Examples

The following examples reference the file `info.txt`, which contains the string "Hello World." The length of `info.txt` is eleven bytes.

Example 1. In the following example, the first call to getPosition shows that the default pointer position is zero in a file that is opened for reading. This example also shows that a call to the read method repositions the pointer.

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

    dataFile.open("r")

    write("The position is " + dataFile.getPosition() + "<BR>")

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

    write("The new position is " + dataFile.getPosition() + "<BR>")

    dataFile.close()

This example displays the following information:

    The position is 0

    The next character is H

    The new position is 1

Example 2. This example uses setPosition to position the pointer one byte from the end of the eleven-byte file, resulting in a pointer position of offset ten.

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

    dataFile.open("r")

    dataFile.setPosition(-1,2)

    write("The position is " + dataFile.getPosition() + "<BR>")

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

    dataFile.close()

This example displays the following information:

    The position is 10

    The next character is d

Example 3. You can position the pointer beyond the end of the file and still evaluate getPosition successfully. However, a call to eof indicates that the pointer is beyond the end of the file.

    dataFile.setPosition(1,2)

    write("The position is " + dataFile.getPosition() + "<BR>")

    write("The value of eof is " + dataFile.eof() + "<P>")

This example displays the following information:

    The position is 12

    The value of eof is true

#### See also

eof, open, setPosition methods

## getSeconds

Method. Returns the seconds in the current time.

#### Syntax

    dateObjectName.getSeconds()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getSeconds is an integer between zero and fifty-nine.

#### Examples

The second statement below assigns the value thirty to the variable secs, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:30")

    secs = Xmas95.getSeconds()

#### See also

setSeconds method

## getTime

Method. Returns the numeric value corresponding to the time for the specified date.

#### Syntax

    dateObjectName.getTime()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by the getTime method is the number of milliseconds since 1 January 1970 00:00:00. You can use this method to help assign a date and time to another Date object.

#### Examples

The following example assigns the date value of theBigDay to sameAsBigDay:

    theBigDay = new Date("July 1, 1999")

    sameAsBigDay = new Date()

    sameAsBigDay.setTime(theBigDay.getTime())

#### See also

setTime method

## getTimezoneOffset

Method. Returns the time-zone offset in minutes for the current locale.

#### Syntax

    dateObjectName.getTimezoneOffset()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The time-zone offset is the difference between local time and GMT. Daylight savings time prevents this value from being a constant.

#### Examples

    x = new Date()

    currentTimeZoneOffsetInHours = x.getTimezoneOffset()/60

## getYear

Method. Returns the year in the specified date.

#### Syntax

    dateObjectName.getYear()

#### Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

#### Method of

Date

#### Description

The value returned by getYear is the year less 1900. For example, if the year is 1976, the value returned is seventy-six.

#### Examples

The second statement below assigns the value ninety-five to the variable year, based on the value of the Date object Xmas95.

    Xmas95 = new Date("December 25, 1995 23:15:00")

    year = Xmas95.getYear()

#### See also

setYear method