The Store Service Class

The service class Store contains the methods needed to manage data organized into hierarchical fields and records. When dealing with language processing, program storage must be viewed as containing a wide variety of different structures: indexes, lists, fixed records, long unformatted records, variable length strings, and so on. In addition, it may be purely memory bound or it may be stored in a persistent file system. The role of this service class is to provide a single interface for storing and retrieving information. It uses the LongMemory service class to manage its storage; therefore, it is sufficiently robust to allow for the management of large files in the multiple gigabyte size range, while it is still efficient for use by purely memory bound applications.

Physically, a storage area consists of a series of relatively large fixed sized blocks whose boundaries cannot be crossed without software support. It is this unalterable property of persistent storage that must be dealt with explicitly if an efficient information management system is desired. The manner in which these blocks are created, maintained, and accessed is determined when the storage area is created or opened. At a logical level the storage area is viewed as consisting of a simple sequence of binary words -- long memory. All information is stored on a word boundary and all offsets are expressed in terms of words.

The primary aspect of the approach used to achieve very rapid access times is semi-permanent pointers. These are implemented via the PagingSystem service class. The basic idea is that a page pointer is a valid memory pointer until the block which it contains is swapped out of memory. Thus, these pointers can be used safely within local blocks of code where efficiency is needed, even though they cannot be saved and reused over longer stretches of code.

The field langRoot

Prototype


extern int langRoot;

The langRoot field specifies the root of the language components in language file

The field langStore

Prototype


extern int langStore;

The langStore field specifies the language storage area provider number.

The field userStore

Prototype


extern int userStore;

The userStore field specifies the user storage area provider number.

The method Store_AddGlobal

Prototype


int Store_AddGlobal(int root,int global);

The Store_AddGlobal method adds the root offset of a component, indexed by its parent to a global index maintained within the storage area. This entry declares that the child component has global scope if and only if the parent component is an active reference. Its parameters are:

Parameter	Description
root	Specifies the root offset of a component that may have global scope.
global	Specifies the offset of the parent external library or class whose active reference status triggers the global scope of its component.

If all goes well, the method returns a one. If the global, root pair already exists, the method returns a zero.

The method Store_ChangeParent

Prototype


void Store_ChangeParent(int iRoot,int parent)

The Store_ChangeParent method changes the parent of a component. Given the referential complexity of the languages being processed, the compilers sometimes have to guess which branch of the symbol table a given component belongs to. This method allows the caller to change the parent and thus the branch of a previously entered component. This can only be applied to components that are not on the root branch. Its parameters are:

Parameter	Description
iRoot	Specifies the root offset of the component in storage as originally returned by the Store_Vector method.
parent	Specifies the root offset of the new parent component.

The method Store_Close

Prototype


void Store_Close(void);

The Store_Close method closes the current storage area if that area is currently open. It does not change the currently selected storage area.

The method Store_Create

Prototype


int Store_Create(char* filename,int iUnit);

The Store_Create method creates a storage area. It selects the indicated storage unit and initializes it as a new empty area whose content will be optionally paged into a specified file. Any information currently in the storage area will be lost. Until another storage area is selected all storage requests will be directed to this currently selected storage area. Its parameters are:

Parameter	Description
filename	Contains the name of that file (optionally without an extension), if the storage is to be paged into a file. If the storage is to be purely memory-based, then this parameter should be NULL.
iUnit	Specifies the unit number of the desired storage area. The current implementation supports upto Store_MaxUnit areas, so this must contain a value between 1 and Store_MaxUnit.

If all goes well a one (true) is returned. If there is a problem creating the storage area a zero (false) is returned.

The method Store_DeltaVector

Prototype


void* Store_DeltaVector(int root);

The Store_DeltaVector method gives write access to the information vector associated with the component whose root offset is specified. If there is any question about the type of component being accessed or about the validity of the root offset value, use the Store_GetObjectType method first (see the discussion there). Any changes made to the information vector will be saved. Use the Store_GetVector method if the vector is to be examined only. The parameter of this method is:

Parameter	Description
root	Specifies the root offset of component in storage.

This method returns a semi-permanent void pointer to the information vector. The storage algorithm guarantees that there are no block boundaries with the vector, so the return value is normally cast to a structure type.

The method Store_FindFirstChild

Prototype


int Store_FindFirstChild(int* levels,int iRoot);

The Store_FindFirstChild method initiates a depth first, or preorder, search of the symbol tree. Its parameters are:

Parameter	Description
levels	Receives information used internally by the search algorithm. It must have at least two plus the maximum levels in the tree entries. Normal code structures have no more than four levels -- project, class, subprogram, and local variable. Controls defined via forms can often be nested more deeply. A size of 20 is always safe. Note that levels[0] always receives the current nesting level.
iRoot	Specifies the first node to be visited. If it> is non-zero, then the node with this offset is visited first. If it is zero, then the first node in the tree is visited first.

See the description of the method Store_FindNextChild for information on how the next node visited is determined. This method returns the offset of the first node visited or zero, if the symbol tree is empty.

The method Store_FindGlobal

Prototype


int Store_FindGlobal(int symbolRoot,int libRoot)

The Store_FindGlobal method determines if there is a global component in an external that has a specified component name, indicated via its unique symbol root offset. Its parameters are:

Parameter	Description
symbolRoot	Specifies the symbol root offset. It is normally obtained via a call to the Store_FindRoot method.
libRoot	Specifies the offset of the external.

If the return value is negative then there are no globals with the specified name. If the return value is zero, then the indicated external has no global component with the specified name. A positive value is the root of a public component in the current external with the specified name.

The method Store_FindNextChild

Prototype


int Store_FindNextChild(int* levels);

The Store_FindNextChild method continues a depth first, or preorder search, of the symbol tree. Its parameter is:

Parameter	Description
levels	Receives information used internally by the search algorithm. It must have been initialized by the Store_FindFirstChild method.

In a depth first search, a visit to a node is followed immediately by visits to all descendants of the node. There is a simple recursive algorithm for describing a depth first search.


  void depth_first_tree_search(node v, int level, void* info)
  {
     node u;

     visit(v,level,info);
     level++;
     for(each child u of v) depth_first_tree_search(u,level,info);
 }

This method returns the offset of the next node visited or zero, if there are no more nodes to visit. Note that levels[0] is always the value of level in the above algorithm

The method Store_FindRoot

Prototype


int Store_FindRoot(CONST char* identifier);

The Store_FindRoot method searches the base symbol table for a specified identifier and returns its root. This root unique for each identifier. Its parameters is:

Parameter	Description
identifier	Contains the identifier to be searched for in the symbol table in null-terminated form.

If a component with the specified identifier is found within the symbol table then the root offset of that component is returned. If no component can be found in the table, then a zero is returned. Note this is the root of the symbol, not the root of any component that is identified by it.

The method Store_FindVector

Prototype


int Store_FindVector(CONST char* identifier,int parent);

The Store_FindVector method finds an identified information vector within a specified single branch in the hierarchical symbol table. Its parameters are:

Parameter	Description
identifier	Contains a null-terminated string with the identifier to be searched for in the specified branch of the symbol table.
parent	Specifies which branch of the symbol table is to be searched. If it is the root branch of the symbol table is to be searched, then it should be set to zero. If a child branch of a parent component, then it should be set equal to the root offset of that parent component.

If a component with the specified identifier is found within the specified branch, then the root offset of that component is returned. If no component can be found in the branch, then a zero is returned.

The method Store_FirstReference

Prototype


int* Store_FirstReference(int symbolRoot,void* PostSet);

The Store_FirstReference method returns the first reference record for a given symbol or for any symbol as stored earlier by the Store_Reference method. This reference is assumed to have the following content:

Seq	Description 0f content
0	The offset of the component containing the reference
1	The offset of the component being referenced
2	The text record number in the host file of the reference
3	The offset in the compiled code of the reference code
4	The offset of the information file containing the subprogram
5	If the reference treated the component as terminal then one, else zero

Its parameters are:

Parameter	Description
symbolRoot	Specifies the offset of the symbol for which references are desired. If it is zero, then all references are returned sorted by symbol referenced.
PostSet	Receives the information needed to control the search. It is a small scratch storage area which must be allocated by the caller. Its content should not be used by the caller. This area must be passed to the Store_NextReference method to obtain additional reference records.

Note that as many simultaneous searches as desired may be conducted so long as each search has its own unique PostSet allocated. If there is at least one reference record available, then a semi-permanent pointer to that record is returned. If there is no reference to the specified symbol, or at all, then a NULL is returned.

The method Store_GetDataName

Prototype


char* Store_GetDataName(void);

The Store_GetDataName method gets the name of the storage area. When a file-based storage area is created or opened its name is stored in the storage control structure. Additionally, the Store_SetName method can be used to supply an alternative name or to supply an actual name to areas that have no supporting file. This method returns that name as a null-terminated string. This string may be empty, but never NULL.

The method Store_GetFirst

Prototype


int Store_GetFirst(int parent);

The Store_GetFirst method returns the first child of a parent component or of the root branch. This is the first component entered for the parent. In general, using this method in conjunction with the Store_GetNext method, will generate the sequence of components stored within some branch of the symbol table in their defined order. Its parameters is:

Parameter	Description
parent	Specifies the root offset of the parent component or zero if the first member of the root branch in the symbol table is desired.

If there is a first child of the specified component then this method returns its root offset. If there is no first child, then this method returns a zero.

The method Store_GetGlobals

Prototype


int Store_GetGlobals(int symbolRoot,int* globals,int nGlobal);

The Store_GetGlobals method returns the global root pairs added to a symbol identifier via the Store_AddGlobal method. The description of that method contains a detailed description of these pairs. Its parameters are:

Parameter	Description
symbolRoot	Specifies a root offset in the base symbol index as returned by the Store_FindRoot method.
globals	Receives the pairs added to the specified symbol.
nGlobal	Specifies the length of the globals vector. No more than nGlobal entries will be stored int globals.

The method returns the number of entries returned in the vector. This is two times the number of pairs.

The method Store_GetHandle

Prototype


void* Store_GetHandle(void);

The Store_GetHandle method gets the LongMemory handle of the current storage area. All storage areas are maintained within a LongMemory area. Though most access needs for that memory area are provided here, it is occasionally necessary to use the LongMemory methods, or one of the specialized stream access methods directly.

This method returns the handle to the underlying LongMemory instance, if the storage area is open; else a NULL is returned.

The method Store_GetIdent

Prototype


char* Store_GetIdent(int root,int* nIdent)

The Store_GetIdent method returns the identifier of a component that was placed in storage using the Store_Vector method. By definition, the "identifier" is the original identifier that was associated with the component when it was first placed in the symbol table. Its parameters are:

Parameter	Description
root	Specifies the root offset of component in storage as originally returned by the Store_Vector method.
nIdent	returns the length of the identifier.

The method returns a semi-permanent character pointer to the identifier of the component.

The method Store_GetInfo

Prototype


int Store_GetInfo(int addr,int* info);

The Store_GetInfo method reads the information vector stored at the address specified. Its parameters are:

Parameter	Description
addr	Specifies the address of the information vector. That vector is stored along with its length.
info	Receives the content of the information vector. It is up to the user to ensure that it has sufficient room. See the method Store_GetLength to obtain its length in advance.

The method returns the length of the information vector as stored in info in bytes.

The method Store_GetLength

Prototype


int Store_GetLength(int offset);

The Store_GetLength method returns length information about the storage areas of about vectors store in that area. Its parameters is:

Parameter

Description

offset

Specifies what length information is wanted. If it is zero, then the length in words of the currently selected storage area is returned. If it is not zero but less than the number of possible storage units Store_MaxUnit, then the length in words of that unit is returned. If it is greater than the possible number of storage units, then the length in bytes of the information stored at the specified offset is returned.

Regardless of the value of the parameter offset, if the current storage area is empty, then this method returns zero.

The method Store_GetMessage

Prototype


char* Store_GetMessage(int number,int* nString)

The Store_GetMessage method gets a message stored in the global message cache. Its parameters are:

Parameter	Description
number	Specifies number of the message.
nString	returns the length of the message.

If the message exists, the method returns a pointer to the message string. If the message does not exist, then a NULL is returned.

The method Store_HasName

Prototype


int Store_HasName(int root);

The Store_HasName method returns a one if a symbol has a separate name defined and returns zero if it does not. Its parameter is:

Parameter	Description
root	Specifies the root offset of the symbol whose name status is needed.

The method Store_GetName

Prototype


char* Store_GetName(int root,int* nIdent);

The Store_GetName method returns the name of a component that was placed in storage using the Store_Vector method or was set using the method Store_SetName. Its parameters are:

Parameter	Description
root	Specifies the root offset of component in storage.
nIdent	returns the length of the name.

The method returns a semi-permanent character pointer to the name of the component as it was originally specified when the component was first entered into the symbol table or that was entered later using Store_SetName.

The method Store_GetNext

Prototype


int Store_GetNext(int child);

The Store_GetNext method returns the next child of a parent component or of the root branch. This is the next component entered for the parent. In general, using this method in conjunction with the Store_GetFirst method, will generate the sequence of components stored within some branch of the symbol table in their defined order. Its parameter is:

Parameter	Description
child	Specifies the root offset of the current child component as returned by Store_GetFirst or a previous call this method.

If there is a next child of the parent of the specified component, then this method returns its root offset. If there is no next child, then this method returns a zero.

The method Store_GetObjectType

Prototype


int Store_GetObjectType(int root);

The Store_GetObjectType method gets the object type of a component. Whenever a component is entered into the symbol table via the Store_Vector method it is assigned an integer object type code. Each object type code has associated with it a fixed-length information vector used to describe components of the specified type. Before accessing the information vector for a component using either of the methods Store_GetVector or Store_DeltaVector, if there is any possible doubt about a root offset, it is good practice to call this method first to make certain that the root offset is in fact well formed and does in fact belong to a component of the expected type. Its parameter is:

Parameter	Description
root	Specifies the root offset of a component in storage.

If the root offset passed to this method has a value less than or equal to zero, then this method displays the following message and returns a zero.


SYSERR#5001: Object Type requested for invalid root %root%

If the root offset passed to this method has a value that exceeds the maximum possible offset, this method displays the following message and returns a zero.


SYSERR#5002: Object Type requested for invalid root %root%

If the root offset is not obviously malformed, then this method returns the object type code as stored the symbol table entry at the specified root offset.

The method Store_GetParent

Prototype


int Store_GetParent(int root);

The Store_GetParent method returns the root offset of the parent of a specified component or a zero if the component is in the root branch of the symbol table. Its parameter is:

Parameter	Description
root	Specifies the root offset of the component in storage as originally returned by the Store_Vector method.

The method Store_GetString

Prototype


char* Store_GetString(int addr,int* nString);

The Store_GetString method returns a semi-permanent pointer to a string in storage that was previously saved using the Store_String method. Note that the string is not necessarily bounded by a null-byte. Its length is also returned by this method. Its parameters are:

Parameter	Description
addr	Specifies the offset of the string in storage as returned by the Store_String method.
nString	returns the length of the string.

The method returns a semi-permanent character pointer to the start of the string. The caller can assume that there are no block-boundaries within the string.

The method Store_GetSymbols

Prototype


int Store_GetSymbols(char* identifier);

The Store_GetSymbols method returns the root offset of a sequence that contains the root offsets of all symbols whose identifier matches a specified one. The symbol table has a tree structure. The symbols within the tree need be unique along one branch only. As a result of this, there can be many duplicates in the symbol table. The roles of the symbol retrieval methods are to search the symbol tree for the correct occurrence of an identifier given a current parent context -- i.e., the typical question asked is "Does a given parent node have a child with the specified identifier". This question must be asked for every parent in the current scope in scope order. This turns out to be a very difficult problem. The simplest approach is to go through each branch on the symbol table in current scope order and see if the identifier can be found on that branch. But there are many branches, especially if a global symbol is being sought, so this process can require many individual searches. To make matters even worse, the required searches are string searches which require time consuming string comparisons as opposed to simple integer comparisons. The approach used separates the search into two parts. First there is a base index in the symbol table that contains one entry for each unique symbol defined anywhere in the current code set. This is the only index that uses string keys. Associated with this entry for each symbol there is a secondary index that uses integer parent node roots as the key and the root of the actual information vector for the identifier in its form within that parent. The parameter of this message is:

Parameter	Description
identifier	Contains the identifier whose entries are desired.

This method searches the base index for the specified identifier using the method Store_FindRoot. If found, it returns the root offset of a sequence maintained there that contains the root offsets of the symbols with that name stored in the order that they were defined. If no symbol with the specified name is present, a zero is returned.

The method Store_GetVector

Prototype


void* Store_GetVector(int root);

The Store_GetVector method gives readonly access to the information vector associated with the component whose root offset is specified. If there is any question about the type of component being accessed or about the validity of the root offset value, use the Store_GetObjectType method first (see the discussion there). Any changes made to the information will generally not be saved. Use the Store_DeltaVector method if the vector is to be changed. The parameter of this method is:

Parameter	Description
root	Specifies the root offset of the component in storage.

The method returns a semi-permanent void pointer to the information vector. The storage algorithm guarantees that there are no block boundaries with the vector, so the return value is normally cast to a structure type.

The method Store_IssueMessage

Prototype


int Store_IssueMessage(CONST char* format,int number,char* Strings[],int nString,int Values[],int nValue);

The Store_IssueMessage method issues a stored message. It retrieves a patterned message from a specified storage unit, combines it with the supplied string and integer parameters, and then writes the completed message to the log file using a specified format. Its parameters are:

Parameter	Description
format	Contains a printf-style format to be used.
number	Specifies the number of message to be used.
Strings	Contains the string values to be supplied.
nString	Specifies the number of string values.
values	Contains the integer values to be supplied.
nValue	Specifies the number of integer values.

If a message was actually written to the log file, then this method returns the length of that message else it return 0.

The method Store_LinkedString

Prototype


int Store_LinkedString(char* String,int nString,int link);

The Store_LinkedString method stores a character string preceded by its length and by an integer link in such a way that no block boundaries are crossed. It is this convention that makes it possible to use a semipermanent pointer to access the character string and its associated link later. It has the following parameters:

Parameter	Description
String	Contains the character string to be stored. It need not be null-terminated as its length is supplied explicitly.
nString	Specifies the length of character string being stored.
link	Specifies a simple value that is stored along with the string. Usually this will be an offset of some other information previously stored in the area but may be any integer value.

The methods within this Store class do not make any assumptions about the content of the String or link parameter therefore, they can be used to store any fixed length byte sequence with an information associated integer value.

The method returns offset in the storage area of the string. This offset can be used later to retrieve the string using the standard Store_GetString method. This offset can also be used later to obtain or change the link value using the methods Store_LinkGet or Store_LinkSet.

The method Store_LinkGet

Prototype


int Store_LinkGet(int addr);

The Store_LinkGet method gets the string associated link for a string that was originally stored by the Store_LinkedString method using the offset returned by that method. Its parameter is:

Parameter	Description
addr	Specifies the location of the string whose link is wanted. It must be the offset returned by the Store_LinkedString method when the string and its link were originally stored.

The method returns the value of the link as retrieved from the storage area. This may be the original value or a value as changed by the Store_LinkSet method.

The method Store_LinkSet

Prototype


void Store_LinkSet(int addr,int link);

The Store_LinkSet method sets the string associated link for a string that was originally stored by the Store_LinkedString method using the offset returned by that method. Its parameters are:

Parameter	Description
addr	Specifies the location of the string whose link is to be changed. It must be the offset returned by the Store_LinkedString method when the string and its link were originally stored.
link	Specifies the new link value to be associated with the string as returned by the method Store_LinkGet.

The typical use of this method is to create linked lists. The user retains the locations of the current first and last members of the list as it is being created. The link value of the last member added is always originally set to zero. As new members are added the previous member's link value is set to the location of the new member.

The method Store_Message

Prototype


void Store_Message(int number,char* String,int nString);

The Store_Message method stores a message in the global message cache. Its parameters are:

Parameter	Description
number	Specifies the number of the message.
String	Contains the actual message.
nString	Specifies the length of the message.

The method Store_NextReference

Prototype


int* Store_NextReference(void* PostSet);

The Store_NextReference method finds the next reference to a symbol. Once a reference search is started via Store_FirstReference, this method is used to find successive references. Note that when a symbol specific search is being performed, the references to that symbol are followed by references to a later symbol. The caller must check the symbol referenced entry if only one symbol's references are desired. Each reference record is assumed to have the following content:

Seq	Description 0f content
0	The offset of the component containing the reference
1	The offset of the component being referenced
2	The text record number in the host file of the reference
3	The offset in the compiled code of the reference code
4	The offset of the information file containing the subprogram
5	If the reference treated the component as terminal then one, else zero

Its parameter is:

Parameter	Description
PostSet	Receives the information needed to control the search. It is a small scratch storage area which must be allocated by the caller. Its content should not be used by the caller. This area must be initialized with the Store_FirstReference method.

If there is an additional reference record available, then a semi-permanent pointer to that record is returned. If there is no additional reference, then a NULL is returned.

The method Store_Open

Prototype


int Store_Open(char* filename,int iUnit,int append);

The Store_Open method opens an existing storage area. It selects the indicated storage unit and initializes it with the contents of a existing file. Any information currently in the storage area will be lost. Until another storage area is selected, all storage requests will be directed to this currently selected storage area. Its parameters are:

Parameter	Description
filename	Contains the name of the file (without an extension) to be opened for the storage area.
iUnit	Specifies the unit number of the desired storage area. The current implementation supports upto Store_MaxUnit areas, so this integer must contain a value between 1 and Store_MaxUnit.
append	Specifies the access permission for the file. If it is nonzero (true), then the file is opened with read/write access permission. If zero (false), then the file is opened for read only access.

If all goes well a one (true) is returned. If there is a problem opening the storage area because the file does not exist zero (false) is returned.

The method Store_PostVector

Prototype


int Store_PostVector(char* identifier,int parent,int length,int type);

The Store_PostVector method posts a component information vector. It is a secondary method used to enter components into the hierarchical symbol table. To enter a symbol four things must be known. First it must have a unique identifier relative to the parent of the symbol. Second it must have a parent which can either be another symbol already entered into storage or can be the root of the symbol hierarchy. Third it must have a information storage vector length. A zero-filled area of storage is allocated to the component with the specified length. Fourth. it must have an object type code, which specifies the type of component being entered. This method checks first to see if the component is already present. If not, it stores it. The parameters of this method are:

Parameter	Description
identifier	Contains the identifier of component in null-terminated form.
parent	Specifies root offset of the parent of the component, if the component is the child of a previously stored component. If the component has no parent -- i.e., if it belongs in the root of the symbol table then this should be set to zero.
length	Specifies the length of information vector to be allocated for use by this component.
type	Specifies the component object type code to be assigned to the component table.

If there already is a component with the same identifier stored in the specified branch of the symbol table, then its root address is returned; else the component is stored and then the new root offset is returned.

The method Store_ReadFront

Prototype


int Store_ReadFront(void* info,int offset,int nFront);

The Store_ReadFront method reads a front part of a long information vector that was initially written using the method Store_WriteInfo. A physical read is required since these information vectors may cross block boundaries, thus making semi-permanent pointers inappropriate. This method should be used when the information storage area receiving the read in not necessarily large enough to contain the entire vector that is in storage. Its parameters are:

Parameter	Description
info	Receives the information read. It must have sufficient room to contain the nFront bytes.
offset	Specifies the starting offset of the information as originally returned by the Store_WriteInfo method.
nFront	Specifies the maximum number of bytes to be read.

The method returns the number of bytes actually read.

The method Store_ReadInfo

Prototype


int Store_ReadInfo(void* info,int offset);

The Store_ReadInfo method reads long information vectors that were initially written using the method Store_WriteInfo A physical read is required since these information vectors may cross block boundaries, thus making semi-permanent pointers inappropriate. Its parameters are:

Parameter	Description
info	Receives the information read. It must have sufficient room to contain the entire vector (see Store_ReadFront).
offset	Specifies the starting offset of the information as originally returned by the Store_WriteInfo method.

The method returns the length of the information vector read in bytes.

The method Store_Reference

Prototype


void Store_Reference(int* reference);

The Store_Reference method stores a reference record. The storage area maintains a sorted list of reference records sorted by the offset of the symbol being referenced. During the compilation process symbols are encountered by a referencing component. This method is used to order them by the component being referenced so that those references can be used by the analyser and auditor. This method actually stores an individual reference record, which is assumed to have the following content:

Seq	Description 0f content
0	The offset of the component containing the reference
1	The offset of the component being referenced
2	The text record number in the host file of the reference
3	The offset in the compiled code of the reference code
4	The offset of the information file containing the subprogram
5	If the reference treated the component as terminal then one, else zero

Note that the reference information allows the later retrieval not only of the referencing pseudocode but also the actual source statement that generated the reference. Its parameter is as follows:

Parameter	Description
reference	Contains the 6 integer values that describe a single reference stored within the pcode created by a language compiler.

The method Store_RewriteInfo

Prototype


void Store_RewriteInfo(void* info,int nByte,int offset);

The method Store_RewriteInfo rewrites long information vectors that were initially written using the method Store_WriteInfo. The number of bytes in the new vector may not exceed the original length of this information. If they do, then the following system error warning is displayed


 SYSERROR#50003: Rewriting "current" bytes over "previous" bytes.

Its parameters are:

Parameter	Description
info	Contains the information to be written.
nByte	Specifies the length of the information.
offset	Contains the starting offset of the information as originally returned by the Store_WriteInfo method.

The method Store_Select

Prototype


void Store_Select(int Unit);

The Store_Select method selects one of the available storage areas as the current storage area. All successive storage area accesses will be performed to this area until another call to this method is made. Note that this method only selects the area, it does not change it in any way. Its parameter is:

Parameter	Description
Unit	Specifies the unit sequence number of the desired storage area. It must have a value between 1 and Store_MaxUnit.

The method Store_SeqClose

Prototype


void Store_SeqClose(void* sequence);

The Store_SeqClose method closes a sequence in storage. This method is needed to close any sequences accessed via the Store_SeqCreate or Store_SeqOpen methods. In addition to closing these sequences, this method also frees the memory used to contain the control structure. Its parameter is:

Parameter	Description
sequence	Specifies the handle to the sequence control structure.

The method Store_SeqCreate

Prototype


void* Store_SeqCreate(int BlockSize);

The Store_SeqCreate method creates a sequence in the current storage area. A sequence is an open ended list of entries. They are used frequently by the language processing system. See the description of the Sequence service class for more information. This method is provided to simplify creating sequences within the current storage area. Sequences created via this method must be closed with the Store_SeqClose method to ensure that all resources are properly closed. Its parameter is:

Parameter	Description
BlockSize	Specifies the size of each block within the sequence. It is normally a small value like 8 or 16.

The method returns the handle for the created sequence.

The method Store_SeqOpen

Prototype


void* Store_SeqOpen(int seqRoot);

The Store_SeqOpen method opens an existing sequence in the current storage area. A sequence is an open ended list of entries. They are used frequently by the language processing system. See the description of the Sequence class for more information. This method is provided to simplify opening sequences within the current storage area. Sequences opened via this service must be closed with the Store_SeqClose method to ensure that all resources are properly closed. Its parameter is:

Parameter	Description
seqRoot	Specifies the root offset of the sequence in the storage area. It would have been the value of the Sequence_GetRoot method for the sequence when it was created.

The handle for the opened sequence is returned.

The method Store_SetCaseSensitive

Prototype


void Store_SetCaseSensitive(int on);

The Store_SetCaseSensitive method sets the cases sensitivity of string keys. It does not effect how they are stored, only how they are compared. Its parameter is:

Parameter	Description
on	Specifies how string keys are to be compared. If nonzero, there are case sensitive; else they are case insensitive

The method Store_SetName

Prototype


void Store_SetName(int root,CONST char* Name,int nName);

The Store_SetName method sets the name of a component or of the overall storage area. Whenever a component is stored in the symbol table using the Store_Vector method that component is given an identifier by the caller. This identifier can then used to retrieve the component, and by default is used by the author whenever references to the component are being written. If references are to be authored with a alternate identifier (referred to as the "name" of the component) then this method is used to associate that name with the component. Alternatively the storage area itself is given the name of the file that contains it when the area is either created or opened. This method can be used to supply an alternative name or to supply an actual name to areas that have no supporting file. Its parameters are as follows:

Parameter	Description of content
root	Specifies the root offset of component in storage as originally returned by the Store_Vector method if a component name is being supplied. An offset value of zero sets the storage area name.
name	Contains the name to be assigned to the component or area.
nName	Specifies the length of the name to be assigned. If it has a value of zero then name parameter is assumed to be null-terminated and this method computes its length.

The method Store_SetObjectType

Prototype


void Store_SetObjectType(int root,int objType);

The Store_SetObjectType method sets the object type of a component. Whenever a component is entered into the symbol table it is assigned and integer object type code. Each object type code has associated with it a fixed-length information vector used to describe components of the specified type. There are occasionally instances of components that are misclassified when they are initially stored. This method allows the user to change the object type code. Note that this method does not change the size of the information vector associated with the component, so great care must be exercised in the use of this method. See the method Store_SwitchVectors for an alternative way of reclassifying components. The parameters of this method are:

Parameter	Description
root	Specifies the root offset of the component in storage as originally returned by the Store_Vector method.
objType	Specifies the new object type code to be assigned to the component.

The method Store_SetRawCharacters

Prototype


void Store_SetRawCharacters(int status);

The Store_SetRawCharacters method sets the raw character flag which controls the check for the VB6 terminating type characters. Its parameter is:

Parameter	Description
status	Specifies the status of the check. If it is zero, then the check will be made. If not zero, then the check will not be made.

The method Store_SetString

Prototype


void Store_SetString(int addr,char* string,int length);

The Store_SetString method sets the content of an existing string. There are occasionally situations where a string is edited without changing its length. In this case, this method can be used to restore the string content. Do not use this method if the length of the string has increased, simply use Store_String to rewrite it and to obtain a new offset. Its parameters are:

Parameter	Description
addr	Specifies the offset of the string in storage as returned by the Store_String method.
string	Contains the new value of the string.
length	Specifies the length of the string.

It is up to the user to ensure that this length does not exceed the length of the string when it was initially stored.

The method Store_String

Prototype


int Store_String(char* String,int nString);

The Store_String method stores a character string preceded by its length in such a way that no block boundaries are crossed. It is this convention that makes it possible to use a semipermanent pointer to access the character string later. Obviously the length of string must be less than the pagesize being used in the underlying physical storage of the blocks. Its parameters are:

Parameter	Description
String	Contains the character string to be stored. It need not be null-terminated as its length is supplied explicitly.
nString	Specifies the length of character string being stored.

The method returns the offset in the storage area of the string. This offset can be used later to retrieve the string.

The method Store_SwitchVectors

Prototype


void Store_SwitchVectors(int root1,int root2);

The Store_SwitchVectors method switches the information associated with one component with that associated with another. Its parameters are:

Parameter	Description
root1	Specifies the root offset of the first component of the switch.
root2	Specifies the root offset of the second component of the switch.

The method Store_Unit

Prototype


int Store_Unit(void);

The Store_Unit method returns the value of the current storage unit. This is the unit number of the currently selected storage area. It has a value between 1 and Store_MaxUnit.

The method Store_Vector

Prototype


int Store_Vector(CONST char* identifier,int parent,int length,int type);

The Store_Vector method stores a component information vector. It is the primary method used to enter components into the hierarchical symbol table. To enter a symbol four things must be known. First, it must have a unique identifier relative to the parent of the symbol. Second, it must have a parent, which can either be another symbol already entered into storage or can be the root of the symbol hierarchy. Third, it must have a information storage vector length. A zero-filled area of storage is allocated to the component with the specified length. Fourth. it must have an object type code, which specifies the type of component being entered. Its parameters are:

Parameter	Description
identifier	Contains the identifier of the component in null-terminated form. It must be unique relative to its parent.
parent	Specifies root offset of the parent of the component, if the component is the child of a previously stored component. If the component has no parent, if it belongs in the root of the symbol table, then this parameter should be zero.
length	Specifies the length of information vector to be allocated for use by this component.
type	Specifies the component object type code to be assigned to the component.

If there already is a component with the same identifier stored in the specified branch of the symbol table, then a zero is returned by this method; else the nonzero root offset of the component is returned. It is this root offset which must be used to manipulate or retrieve any information for the component.

The method Store_WriteInfo

Prototype


int Store_WriteInfo(void* info,int nByte);

The Store_WriteInfo method writes long information vectors into storage. There is no limit to the length of this information. Since block boundaries may occur within the storage area used, semi-permanent pointers should not be used to access the record, rather the methods Store_ReadInfo and Store_RewriteInfo should be used. Its parameters are:

Parameter	Description
info	Contains the information to be written.
nByte	Specifies the length of the information.

If the number of bytes to be written is not well-formed -- i.e., is less than or equal to zero, this method displays the following message and returns a zero.


    SYSERR#5004: Empty or negative length (%nbyte%) record being written.

Else, the method returns the offset in the start of the storage area for the information. This offset can be used later to retrieve the information.

The method Store_ZeroFirst

Prototype


void Store_ZeroFirst(int parent);

The Store_ZeroFirst method zeros the offset of the first child of a nonterminal component in the symbol table. This causes this component to be terminal. Its parameter is:

Parameter	Description
parent	Specifies the root offset of the component whose status is to be changed.

Table of Contents

Browser not supported