The ScratchInfo Service Class

The service class ScratchInfo manages a scratch information storage area primarily for use by the engine for the rapid storage, retrieval, and removal of volatile values. All of its content is maintained in a single memory-based long storage area; consequently, this class has no external handles that must be managed by the users of this class.

Note that this class uses the value of the global define SCRATCHINFO_PAGESIZE to define its page size. This constant is typically equal to 16384. No records longer than this size can be managed via this class. If very long records are needed by some process this value can be changed by changing the implementation of the method ScratchInfo_Create.

The method ScratchInfo_Access

Prototype

Code Block
language cpp theme Eclipse linenumbers true
void* ScratchInfo_Access(int offset,int* nByte);

The ScratchInfo_Access method accesses a previously stored scratch information vector from the currently active area. Its parameters are:

The method returns a handle to the start of the information vector. The caller can assume that there are no block-boundaries within the vector. This pointer can be used in the normal way, but it may be semipermanent in some implementations, which means that it should be used only locally for immediate access.

The method ScratchInfo_Close

Prototype

Code Block
language cpp theme Eclipse linenumbers true
void ScratchInfo_Close(void);

The ScratchInfo_Close method closes the current scratch information storage area if that area is currently open. Any use of this class before a new call to the method ScratchInfo_Create will fail. This method has no parameters or return value.

The method ScratchInfo_Create

Prototype

Code Block
language cpp theme Eclipse linenumbers true
void ScratchInfo_Create(int iUnit);

The ScratchInfo_Create method creates the current scratch information storage area. If that area is currently open, then it is closed before a new area is created. Any use of this class before this method has been called will fail. Any process using this method should also use the method ScratchInfo_Close before it exits. There may be up to three independent storage areas active. Its parameter is:

The created unit becomes the currently active one.

The method ScratchInfo_Delete

Prototype

Code Block
language cpp theme Eclipse linenumbers true
void ScratchInfo_Delete(int offset);

The ScratchInfo_Delete method logically deletes a scratch information vector from information storage associated with the currently active area. Its primary use is by an execution engine when it ends the execution of a subprogram and must restore any resources being used by its variables. The vector is not physically deleted, rather it is posted into a deleted record chain. From there it can be reused via other methods. Its parameter is:

The method ScratchInfo_PostCreate

Prototype

Code Block
language cpp theme Eclipse linenumbers true
int ScratchInfo_PostCreate(void);

The ScratchInfo_PostCreate method creates a runtime posting set in the currently active area for use in storing binary relationships between components. A posting set is a high-speed sorted list of integer keys each of which has an integer value associated with it. This method simply creates the structure needed to support the posting set. It has no parameters.

The method returns the root offset in the storage area of the posting set.

The method ScratchInfo_PostFind

Prototype

Code Block
language cpp theme Eclipse linenumbers true
int ScratchInfo_PostFind(int basePoint,int pairIndex);

The ScratchInfo_PostFind method searches the posting set in the currently active area for an entry associated with a particular value. Its parameters are:

If the entry is found, the value associated with the index is returned; else zero is returned.

The method ScratchInfo_PostWrite

Prototype

Code Block
language cpp theme Eclipse linenumbers true
int ScratchInfo_PostWrite(int basePoint,int index,int value);

The ScratchInfo_PostWrite method writes a new index value to a sorted posting set in the currently active area and associates a specified value with it. Its parameters are:

If all goes well, the method returns a one. If the pair already exists and has a nonzero value associated with it, the method returns a zero.

The method ScratchInfo_Replace

Prototype

Code Block
language cpp theme Eclipse linenumbers true
int ScratchInfo_Replace(int offset,void* info,int nByte);

The ScratchInfo_Replace method replaces a scratch information vector in the currently active area with a different information vector. Its primary use is by an execution engine when the value of a variable is being changed. The actual process proceeds as follows. If the new vector has the same length as the one being replaced then the new vector is simply copied into the existing storage location and the offset of the vector remains the same. If the lengths are different, then the existing vector is logically deleted from the storage area and the new one is written. Its parameters are as follows:

This method returns the integer offset in the storage area of the start of the information vector. This offset must be used later to retrieve the information. Depending upon its length this may be the same as the previous offset or it may be different.

The method ScratchInfo_Select

Prototype

Code Block
language cpp theme Eclipse linenumbers true
void ScratchInfo_Select(int iUnit);

The ScratchInfo_Select method selects one of the currently open scratch storage areas to be the currently active one. Its parameter is:

The created unit becomes the currently active one.

The method ScratchInfo_Write

Prototype

Code Block
language cpp theme Eclipse linenumbers true
int ScratchInfo_Write(void* info,int nByte);

The ScratchInfo_Write method writes to the currently active area a scratch information vector preceded by its length in such a way that no block boundaries are crossed. It is this convention that makes it possible to access the information later without having to worry about the underlying block structure. The length of information vector must be less than the pagesize being used in the underlying physical storage of the blocks. Its parameters are:

This method returns the integer offset in the storage area of the start of the information vector. This offset must be used later to retrieve the information.