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.
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.