gmSCScratchInfoClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

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


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:

Parameter Description
offset Specifies the offset in the information storage area of the information vector as previously returned by the Write method.
nByte returns the length in bytes of the information vector as it was specified when the vector was originally written.

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


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


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:

Parameter Description
iUnit Specifies which unit is to be created. It must contain a value between 0 and 2, or one of the constants -- ScratchInfo_Global, ScratchInfo_Local, or ScratchInfo_User

The created unit becomes the currently active one.

The method ScratchInfo_Delete

Prototype


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:

Parameter Description
offset Specifies the offset in the information storage area of the information vector being deleted as previously returned by the Write method.


The method ScratchInfo_PostCreate

Prototype


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


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:

Parameter Description
basePoint specifies the root offset of the posting set to be searched as returned by the method ScratchInfo_PostCreate.
pairIndex specifies the value whose associated entry value is desired.

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

The method ScratchInfo_PostWrite

Prototype


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:

Parameter Description
basePoint specifies the root offset of the posting set to be written to as returned by the method ScratchInfo_PostCreate.
index Specifies the index value to be used are the pairIndex value when the posting set is searched by ScratchInfo_PostFind.
value Specifies the value that is to be associate with the index.

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


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:

Parameter Description
offset Specifies the offset in the information storage area of the information vector being replaced as previously returned by the ScratchInfo_Write or ScratchInfo_Replace methods. If this offset is zero, then this method assumes that no previous vector exists and it simply writes a new one.
info Specifies the handle for the replacing information vector. Its content is arbitrary.
nByte Specifies the length of the information vector in bytes. It must be greater than zero and less than the pagesize of the storage area.

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


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:

Parameter Description
iUnit Specifies which unit is to be selected. It must contain a value between 0 and 2, or one of the constants -- ScratchInfo_Global, ScratchInfo_Local, or ScratchInfo_User

The created unit becomes the currently active one.

The method ScratchInfo_Write

Prototype


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:

Parameter Description
info Contains the vector to be written. It is copied into the scratch storage area. No assumptions about its internal content are made as its length is supplied explicitly. The value of info may be NULL. In this case an area nByte long is allocated and initialized at zero.
nByte Specifies the length of the information vector in bytes. It must be greater than zero and less than the pagesize of the storage area.

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.
Table of Contents