The DataQueue Service Class

The service class DataQueue contains the core methods needed to provide a runtime data queue. The runtime data queue is a LIFO (Last In First Out) list of temporary arbitrary data items used by the runtime engine and string machine. All data stored in the queue is in raw form followed by a 2 word record which contains the length of the information in words and type code which describes the type of information stored. The base of the queue contains three values: the total size, the current top, and the current local base.

The method DataQueue_ClearBotton

Prototype


void DataQueue_ClearBottom(int isEmpty)'

The DataQueue_ClearBotton method clears the current bottom of the data queue. It checks to see if there is a bottom mark at the current top of the queue. If there is, then it removes that mark. If there is not a bottom mark at the top of the queue, then it either clears the queue or issues a fatal system error. Its parameter is:

Parameter	Description
isEmpty	Specifies the desired state of the queue. If non-zero, then the queue must be positioned at the bottom; else this method empties the queue.

This method has no return value. If the queue is supposed to be positioned at the bottom, but is not, then the message "SYSTEM ERROR#10009: Queue not at bottom mark, top=%d" is logged and control is returned to the operation system.

The method DataQueue_Close

Prototype


void DataQueue_Close(void);

The DataQueue_Close method closes the current data queue, if there is currently one active. All of its resources and any data in it is lost. This method has no parameters. If there currently is a backup queue, then that queue becomes the active one.

This method has no return value.

The method DataQueue_Compare

Prototype


void DataQueue_Compare(void);

The DataQueue_Compare method compares the top two entries on the stack and stores an integer value describing the result in their place. If the first entry is less than the second then a negative integer is stored. If the first entry equals the second then a zero is stored. If the first entry is greater than the second then a positive integer is stored. If the second entry in the comparison is a string, then a string comparison is done; else an integer comparison is done. This method has no parameters.

This method itself has no return value.

The method DataQueue_Concatenate

Prototype


void DataQueue_Concatenate(void);

The DataQueue_Concatenate method forms a string by concatenating the top two entries in the data queue and stores the result string in their place. If either of the entries are not strings as stored, then that entry is converted to a string prior to the concatenation. The resulting entry on the queue is always a string. This method has no parameters.

This method itself has no return value.

The method DataQueue_Create

Prototype


void DataQueue_Create(int queueSize);

The DataQueue_Create method creates and initializes a new data queue storage area. If there is a data queue currently defined, then it becomes the backup queue. Its resources and data are not lost. Its parameter is:

Parameter	Description
queueSize	specifies the number of bytes of storage to be allocated to the new data queue storage area.

This method itself has no return value.

The method DataQueue_GetBoolean

Prototype


int DataQueue_GetBoolean(void);

The DataQueue_GetBoolean method gets a zero/non-zero boolean value from the data queue. It examines the current top of the queue. This method has no parameters.

If anything other than a string is stored at the current top of the queue, there then it is removed from the queue and its value is returned by this method. If there is a string value at the top of the queue, then if it is empty a zero is returned; else a one is returned.

The method DataQueue_GetInteger

Prototype


int DataQueue_GetInteger(void);

The DataQueue_GetInteger method gets an integer value from the top of the queue, doing conversions to integer if necessary. It examines the current top of the queue. If an integer value is stored there then it is removed from the queue and returned. If there is a string value at the top of the queue, then it is converted into integer form and returned; else zero is returned. This method has no parameters.

This method returns the value from the top of the queue in integer form.

The method DataQueue_GetString

Prototype


int DataQueue_GetString(char* buffer,int nBuffer);

The DataQueue_GetString method gets a gets string value from the data queue, performing a conversion to string if necessary. It examines the current top of the queue. If a string value is stored there then it is removed from the queue and copied into the return buffer. If there is an integer value at the top of the queue, then it is converted into string form into the return buffer. Its parameters are:

Parameter	Description
buffer	Receives the string value that was at the top of the queue in null-terminated form.
nBuffer	Specifies the size of the buffer return area. It is used to prevent overflows.

This method returns the number of characters returned in the buffer. This will never be greater than the size of the buffer minus 1. If loss of long string information is a potential problem then use a combination of DataQueue_TestTop and DataQueue_PopString to receive long strings.

The method DataQueue_PopEngine

Prototype


int* DataQueue_PopEngine(int* length,int* top);

The DataQueue_PopEngine method pops an information vector from the data queue. It examines the current top of the queue. If a user information vector is stored there then it is conditionally removed from the queue and a pointer to its value is returned. Note that this pointer is valid until additional values are pushed onto the stack. If the value stored at the top of the queue is not of the specified type, then a system error occurs. Its parameters are:

Parameter	Description
length	optionally returns the length of the vector, if it is not NULL. Users of this method will usually already know the length.
top	optionally returns a pointer to the new top of the queue, if this parameter is not NULL. In some situations the user needs to examine the information at the top of the queue before deciding to remove it. In this case, this parameter is set to a non-NULL pointer. The new top returned can later be passed to the DataQueue_SetTop service when and if the actual removal is desired.

The method returns a void* pointer to the start of the information in the queue. This pointer is valid until additional information is pushed. In particular it remains valid during subsequent pops of information.

The method DataQueue_PopInformation

Prototype


int* DataQueue_PopInformation(int* iType,int* length);

The DataQueue_PopInformation method pops an information value from the data queue. It returns a pointer to the top information vector on the queue and removes it from the queue. Its parameters are:

Parameter	Description
iType	returns the type code of the information, if non-NULL.
length	returns the length of the information, if non-NULL.

This method returns an integer pointer to the actual start of the information vector for the requested value or a NULL if there is no information currently in the queue.

The method DataQueue_PopInteger

Prototype


int DataQueue_PopInteger(void);

The DataQueue_PopInteger method pops an integer value from the data queue. This method has no parameters.

It examines the current top of the queue. If an integer value is stored there then it is removed from the queue and its value is returned. If there is not an integer value at the top of the queue, then a fatal "SYSTEM ERROR#10005: Integer not at stack top, top = %d" error occurs.

The method DataQueue_PopString

Prototype


char* DataQueue_PopString(int* nString);

The DataQueue_PopString method pops a string value from the data queue. It examines the current top of the queue. If a string value is stored there then it is removed from the queue and a pointer to its value is returned. Note that this pointer is valid until additional values are pushed into the queue. If there is not a string value at the top of the queue, then a fatal "SYSTEM ERROR#10006: String not at stack top, top type=%d" error occurs. The string itself is returned in null-terminated form -- i.e., as a valid C-string. Its parameters is:

Parameter	Description
nString	returns the length of the string. If nString is NULL, then no length is returned and if the string is a empty it is returned as a NULL

The method returns a pointer to the start of the string. This may be a simple null-string,

The method DataQueue_PushEngine

Prototype


int* DataQueue_PushEngine(int* information,int length);

The DataQueue_PushEngine method pushes an arbitrary engine information vector into the data queue along with its length and type marker. Note that any variable length information may be stored using this method. It merely does a binary copy of the data. Note that the data queue is word aligned so no packing or unpacking is necessary to access its value directly from queue storage. Its parameters are:

Parameter	Description
information	contains the vector to be stored in the queue. There are cases where it is convenient to allocate the space for the vector and then to copy values into that space. In this case, this parameter may be NULL.
length	Specifies the length of the information vector expressed in words.

After this method executes the top of the queue looks as follows:

Word	Description of content
top	REP_ENGINE
top-1	length
top--	information

This method returns a pointer to the start of the information. This pointer is valid until this unit of information is removed from the queue. If there is not enough room to store the vector then a fatal "SYSTEM ERROR#10004: Data queue stack overflow" error occurs.

The method DataQueue_PushInteger

Prototype


void DataQueue_PushInteger(int iValue);

The DataQueue_PushInteger method pushes an integer value into the data queue along with its length (1) and its type marker (REP_SHORT). The only error checked by this method is whether there is sufficient room in the queue for the new entry. If there is not, this method does a fatal SYSTEM ERROR#10001: Integer stack overflow" error exit. Its parameter is:

Parameter	Description
iValue	Specifies the actual integer value.

After this method executes the top of the queue looks as follows:

Word	Description of content
top	REP_SHORT
top-1	1
top-2	iValue

This method itself has no return value.

The method DataQueue_PushString

Prototype


char* DataQueue_PushString(char* string,int nString);

The DataQueue_PushString method pushes a string value into the data queue, preceded by its length in characters and followed by a null-byte. That record is then followed by its record length (nString/sizeof(int)+2) and its type marker (REP_FSTRING). The only error checked by this method is whether there is sufficient room in the queue for the new entry. If there is not, this method does a fatal "SYSTEM ERROR#10003: String stack overflow--size=%d top=%d nString=%d" exit. Its parameters are:

Parameter	Description
string	Contains the actual string to the stored. There are cases where it is convenient to allocate the space for the string and then to copy values into that space. In this case this parameter may be NULL.
nString	Specifies the length of the string in characters. Great care must be taken not to change any content in the queue storage area not allocated to this string via this parameter.

After this method executes the top of the queue looks as follows:

Word	Description of content
top	REP_FSTRING
top-1	(nString / sizeof(int)) + 2
top--	nstring,string,'\0'

The method returns a pointer to the string itself within the queue.

The method DataQueue_SetBottom

Prototype


int DataQueue_SetBottom(void);

The DataQueue_SetBotton method sets the current queue bottom. It marks the current spot in the queue as the current bottom. Any attempt to pop a value from the queue will fail until this mark is cleared. This method is needed to block any interference between the recursive engines using it, while allowing the processing of calls with a variable number of arguments. This method has no parameters. If there is no room for the bottom mark this method does a fatal "SYSTEM ERROR#10008: Bottom mark stack overflow" exit.

This method returns the integer offset of the mark in the queue.

The method DataQueue_SetTop

Prototype


void DataQueue_SetTop(int top)

The DataQueue_SetTop method sets the current queue top. This method should only be used after a recent use of a conditional Pop method which supplied the parameter value. Its parameter is:

Parameter	Description
top	Specifies the new value of the top of the queue. It must be a value received from a conditional Pop method.

This method has no return value.

The method DataQueue_TestTop

Prototype


int DataQueue_TestTop(void)

The DataQueue_TestTop method tests the status of the top of the data queue. It examines the current top of the queue. This method has no parameters.

This method returns the binary representation code of the data item stored there. If there is a bottom mark at the top, then a zero is returned. If the queue is empty then a -1 is returned.

Table of Contents

Browser not supported