The Offline Service Class

The service class Offline transfers binary information to and from persistent storage. It allows the user to manipulate files whose size extends beyond the normal bounds of single precision integers. It provides all the basic I/O operations needed by the information management system to physically transfer information between memory and persistent offline storage.

At this level, a file is viewed as consisting of a series of fixed length blocks numbered from 1 to n. The block number itself is stored in an unsigned integer which as of this writing means 32 bits on most platforms. Thus a file can contain from 1 to 4 gigabyte blocks. Since the typical block sizes are 4096 or 8192 bytes, the largest files supportable in theory are in the 16 to 32 terabyte range.

Note that this class is intended to operate most efficiently if it deals with unbuffered files, though this is not required. Special code is provided for Windows platforms, MSCPLAT, to do unbuffered I/O. As implemented here, other platforms simply use the standard C binary I/O methods.

The method Offline_CloseFile

Prototype

The Offline_CloseFile method closes an offline file. Beyond closing, no other action is taken. It is up to the user to do any flushing or memory releases of buffers that may have been used to store information from the file. Its parameter is:

This method has no return value.

The method Offline_CloseMemory

Prototype

The Offline_CloseMemory method closes the file backing up the memory area and returns any resources used by it to the operating system. If the file was not opened for read only mode, then the content of the memory area is written back to the offline file. Its parameter is:

The method Offline_CreateFile

Prototype

The Offline_CreateFile method creates a new offline file. This method creates a new file in the file system. If a file with the specified name already exists, then it is destroyed and recreated. Its parameter is:

If all goes well, this method returns a handle to the file for use by the other methods of this class. Note that this handle is completely opaque to users of this class, since its content varies widely by platform. If the file cannot be created, then a NULL handle is returned.

The method Offline_OpenFile

Prototype

The Offline_OpenFile method opens an existing offline file. Its parameters are:

This method attempts to open an existing file in the file system at the location specified within FileName. If the parameter ReadOnly is nonzero, then the process using the returned handle will not be able to make any changes to the file. It is highly recommended that ReadOnly be set to nonzero whenever a file is only going to be read. Note that files opened in this way may be used simultaneously by other processes.

If all goes well, this method returns a handle to the file for use by the other methods of this class. Note that this handle is completely opaque to users of this class, since its content varies widely by platform. If the file cannot be opened, then a NULL handle is returned.

The method Offline_OpenMemory

Prototype

The Offline_OpenMemory method opens a file as a memory mapped file. In other words it reads the entire file into memory. Files opened in this way can be changed; however, they cannot be extended. Note that files opened in this manner cannot be read or written. Any changes or accesses are made directly though the returned memory area. Its parameters are:

If all goes well, this service returns a handle to the file for use by the other services of this provider. If the file cannot be opened, then a NULL handle is returned.

The method Offline_ReadBlock

Prototype

The Offline_ReadBlock method reads a block of information from an existing location within the file. This location is computed by multiplying the block number minus one times the block size. All blocks written to the file are the same size. The actual block size is determined when the user decides how he is going to access the file at the time that the file is initially created. Its parameters are:

This method has no return value.

The method Offline_RewriteBlock

Prototype

The Offline_RewriteBlock method rewrites a revised block of information to an existing location within the file. This location is computed by multiplying the block number minus one times the blocksize. All blocks written to the file must be the same size. The actual block size is determined when the user decides how he is going to access the file at the time that the file is initially created. Its parameters are:

This method has no return value.

The method Offline_SizeInBlocks

Prototype

The Offline_SizeInBlocks method gets the current size of the file in blocks. Its parameters are:

This method determines the total current size of the file, which may exceed the integer size threshold, and divides it by the block size, to determine the integer block count, which is then returned.

The method Offline_SizeMemory

Prototype

The Offline_SizeMemory method returns the amount of memory being used to store the entire file in memory. Its parameter is:

This method returns the size in bytes.

The method Offline_WriteNewBlock

Prototype

The Offline_WriteNewBlock method writes a new block to the back of an offline file. All blocks written to the file are the same size. The actual block size is determined when the user decides how he is going to access the file at the time that the file is initially created. Its parameters are:

This method has no return value.