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

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:

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

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

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

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

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:

This method itself has no return value.

The method DataQueue_GetBoolean

Prototype

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

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

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:

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

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:

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

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:

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

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

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:

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

The method DataQueue_PushEngine

Prototype

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:

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

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

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:

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

This method itself has no return value.

The method DataQueue_PushString

Prototype

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:

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

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

The method DataQueue_SetBottom

Prototype

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

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:

This method has no return value.

The method DataQueue_TestTop

Prototype

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.