The BinaryFile Object

A BinaryFile object provides access to a non text file from Active Web.

BinaryFile objects are of class BinaryFile.

BinaryFile Object Properties

Property

Description

error

An error message If an error has occurred. If no error has occurred then it will be null. The error messages are explained below:

File not found - The file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason

Access error - The file had an error when trying to read, write, get the length, use the file pointer or close it.

Can not write to file - An attempt is made to write to a read only file.

Write data not valid - The write function data was not a valid byte.

While reading or writing the file the operating system can generate various other error messages.

prototype

A reference to the ByteString Prototype. This property does not enumerate and can not be deleted but can be changed.

BinaryFile Object Functions

Function	Description
close()	Closes the file and frees resources. If an error occurs then this function returns false and the error property will be set. If the close is successful then this function returns true.
del()	Delete the file. Returns true if the file was deleted and false if the file did not exist.
eof()	Returns true if the file pointer is positioned at, or beyond, the end of the file. If an error occurs then this function returns true and the error property will be set.
exists()	Returns true if the file exists.
getLength()	Returns the current length of the file. If an error occurs then this function returns -1 and the error property will be set.
getPosition()	Returns the offset from the beginning of the file, in bytes, at which the next read or write occurs. If an error is detected then -1 will be returned and the error property will be set.
lastModified()	Returns a long value representing the time the file was last modified, measured in milliseconds. If the file does not exist the this function returns 0.
readByte()	Reads a signed eight-bit value from this file and returns it as a number. This function reads the byte, at the current file pointer, from the file. If an error is detected or end of file is reached then -1 will be returned and the error property will be set.
setPosition(offset[, mode])	Sets the file-pointer offset. This will then be the location at which the next read or write occurs. The mode argument is a number that defines how the file pointer is set as shown below. The default if mode is not supplied is mode 0. mode 0 - Set the file pointer to the offset supplied, measured from the beginning of this file. mode 1 - Set the file pointer to its current position plus the offset supplied. mode 2 - Set the file pointer to the current length of the file plus the offset supplied. any other mode - Use mode 0. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file. If an error occurs then this function returns false and the error property will be set. If the offset is set successfully then this function returns true.
writeByte(byte)	Writes the specified byte to this file. The write starts at the current file pointer. The byte is a signed 8-bit number (-127 to +127). If an error occurs then this function returns false and the error property will be set. If the byte is written successfully then this function returns true.

The BinaryFile Constructor

Using the new Operator with the BinaryFile Constructor

The BinaryFile constructor is used to create new BinaryFile objects. All BinaryFile objects are given the ByteString prototype.

var myFile1 = new BinaryFile(name);

A new BinaryFile object for the file identified by the name is created. The name uses the script file reference to identify the file. The file can be anywhere on the host filing system. If the file does not exist then it will be created. If the name argument is not present then a runtime error will be generated and the script page execution halted.

Shown below is the BinaryFile object prototype chain.

Calling the BinaryFile Constructor as a Function

When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.

BinaryFile Constructor Properties

Constructor properties are read only (they can not be changed or deleted) and it is not possible to add new properties to the Constructor.

Property	Description
prototype	A reference to the ByteString Prototype. This property does not enumerate and can not be changed or deleted.

BinaryFile Constructor Functions

The BinaryFile constructor has no predefined functions.

Write() Behaviour

When the response object is in binary mode; using the write() and writeln() functions to write a BinaryFile object will result in all the bytes in the file being written to the requesting client.

The ByteString Prototype

This prototype has functions to convert between numbers and strings. The numbers are all signed 8 bits. This prototype can be used by any object.

ByteString Prototype Properties

Property	Description
prototype	A reference to the Object Prototype. This property does not enumerate and can not be deleted but can be changed.

ByteString Prototype Functions

Function	Description
byteToString(number)	Return the signed eight-bit number as a single character string.
stringToByte(string)	Return the first character of the string as a signed eight-bit number.

Comment on this topic

Topic ID: 150035