Page tree
Skip to end of metadata
Go to start of metadata

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


void Offline_CloseFile(void* This);
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:

Parameter Description
This Specifies the handle of the file to be closed as was obtained from either Offline_CreateFile or Offline_OpenFile.

This method has no return value.

The method Offline_CloseMemory

Prototype


void Offline_CloseMemory(void* This);
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:

Parameter Description
This Specifies the handle of the file to be closed.


The method Offline_CreateFile

Prototype


void* Offline_CreateFile(char* FileName);
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:

Parameter Description
FileName Contains the full pathname of the file to be created. At this level, this pathname must be completely compatible with the platform hosting this code.

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


void* Offline_OpenFile(char* FileName,int ReadOnly);
The Offline_OpenFile method opens an existing offline file. Its parameters are:

Parameter Description
FileName Contains the full pathname of the file to be opened. At this level, this pathname must be completely compatible with the platform hosting this code.
ReadOnly Specifies that records will only be read form the file, no writes will be performed.

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


void* Offline_OpenMemory(char* FileName,int ReadOnly,UBYTE** MemoryArea);
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:

Parameter Description
FileName Contains the full pathname of the file to be opened. At this level this pathname must be completely compatible with the platform hosting this code.
ReadOnly if nonzero, then the process using the returned handle will not be able to make any changes to the file. It is highly recommended that this be set to nonzero whenever a file is only going to be read.
MemoryArea returns a byte pointer to the area in memory into which the content of the file has been mapped.

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


void Offline_ReadBlock(void* This,UBYTE* Block,ULONG BlockNumber,int BlockSize);
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:

Parameter Description
This Specifies the handle for the file containing the information blocks, as returned by Offline_CreateFile or Offline_OpenFile.
Block Receives the actual block of information read from the file.
BlockNumber specifies the number of the block relative to 1 to be read.
BlockSize Specifies the size of the block to be read in bytes.

This method has no return value.

The method Offline_RewriteBlock

Prototype


void Offline_RewriteBlock(void* This,UBYTE* Block,ULONG BlockNumber,int BlockSize);
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:

Parameter Description
This Specifies the handle for the file receiving the information blocks, as returned by Offline_CreateFile or Offline_OpenFile.
Block Contains the actual block information to be rewritten to the file.
BlockNumber specifies the number of the block relative to 1 to be rewritten.
BlockSize Specifies the size of the blocks being rewritten in bytes.

This method has no return value.

The method Offline_SizeInBlocks

Prototype


ULONG Offline_SizeInBlocks(void* This,int BlockSize);
The Offline_SizeInBlocks method gets the current size of the file in blocks. Its parameters are:

Parameter Description
This Specifies the handle for the file receiving the raw records, as returned by Offline_CreateFile or Offline_OpenFile.
BlockSize Specifies the block size value being used for calls to Offline_WriteNewBlock.

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


ULONG Offline_SizeMemory(void* This);
The Offline_SizeMemory method returns the amount of memory being used to store the entire file in memory. Its parameter is:

Parameter Description
This Specifies the handle for the file.

This method returns the size in bytes.

The method Offline_WriteNewBlock

Prototype


void Offline_WriteNewBlock(void* This,UBYTE* Block,int BlockSize);
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:

Parameter Description
This Specifies the handle for the file receiving the raw records, as returned by Offline_CreateFile or Offline_OpenFile. Obviously, if the open was read only then this method cannot be used.
Block Contains the actual block of information to be written to the back of the file.
BlockSize Specifies the size of the block to be written in bytes. This method uses but does not retain this size value. It is up to the caller to ensure that all blocks in any given file are always the same size.

This method has no return value.
Table of Contents

  • No labels