README for the func_queue_stack library
=======================================

There are situations when WinRunner's lack of more complex data 
structure support can be an annoyance. Queues (FIFO) and 
Stacks (LIFO) are 2 of the more common data structures that 
are used regularly in any programming languages. This
implementation is written completely in TSL, and basically 
provides wrapper functions to access a sequential array in 
a FIFO (first in first out) or LIFO (last in first out) manner.

A test script (test_queue_stack) has been provided together with 
the module to verify that the module is working correctly.
The test script should also provide a very good example of how 
to use the queue and stack.

In addition, loading the module will automatically add the 
functions to the WinRunner function generator.

Implementation Overview
=======================

Queue:
------
The queue implementation will create 2 entries in the associative
array to maintain pointers to the start and end of the queue 
( 'curr' and 'next').  The 'curr' pointer points to the current
element in the queue (the one that will be returned when the
'dequeue' function is called); while the 'next' pointer points
to the position where the next 'enqueue' should insert the item
to.  The following diagrams illustrates the operation performed
on the array as 2 elements are added to the queue, and then
a function call to 'dequeue' is made at the end.  The numbers
to the left of the queue is the associative index of the array
(by defining 'curr' and 'next', the array becomes an associative
array).

Queue empty and initialized:
Statement: queue_init (my_queue);

 3  |   |
 2  |   |
 1  |   |
 0  |   | <- curr, next

Queue with 1 element enqueued:
Statement: enqueue (my_queue, "a");

 3  |   |
 2  |   |
 1  |   | <- next
 0  | a | <- curr

Queue with 1 more element enqueued:
Statement: enqueue (my_queue, "b");

 3  |   |
 2  |   | <- next
 1  | b |
 0  | a | <- curr

Queue after a 'dequeue' function call (the function returns "a"):
Statement: dequeue (my_queue, myval); # myval will contain "a"

 3  |   |
 2  |   | <- next
 1  | b | <- curr
 0  |   |


Stack
-----
The stack implementation is a lot simpler than the queue, as
only the pointer to the last element is needed.  In this case,
we use the entry: 'next', which points to the location where
the next 'push' to the stack should place the element to.
The following diagrams illustrate the operations performed on
a stack.  The example shows two 'push' operations to the stack,
and followed by a 'pop' at the end.

Stack empty and initialized:
Statement: stack_init (my_stack);

 3  |   |
 2  |   |
 1  |   |
 0  |   | <- next
    +---+

Stack with 1 element 'push'ed
Statement: stack_push (my_stack, "a");

 3  |   |
 2  |   |
 1  |   | <- next
 0  | a |
    +---+

Stack with 1 more element 'push'ed
Statement: stack_push (my_stack, "b");

 3  |   |
 2  |   | <- next
 1  | b |
 0  | a |
    +---+

Stack after a 'pop' function call:
Statement: stack_pop (my_stack, myval); # myval will contain "b"

 3  |   |
 2  |   |
 1  |   | <- next
 0  | a |
    +---+


References:

- Information on stack: http://hissa.nist.gov/dads/HTML/stack.html
- Information on queue: http://hissa.nist.gov/dads/HTML/queue.html
- Information on linklist: http://hissa.nist.gov/dads/HTML/linklist.html

  WinRunner related links:
  ------------------------

- Official Mercury Interactive web site: 
    http://www.merc-int.com
- Official Mercury Interactive support site (this site is really
  slow, but you can access all the documentations, discussion 
  groups, knowledge base and updates on all of Mercury 
  Interactive's products):
    http://support.merc-int.com

- More customer functions for WinRunner: 
    http://www.itechnologist.com/tech/
- Unofficial WinRunner list: 
    http://www.egroups.com/group/winrunner
- QAForums discussion group (has WinRunner related group): 
    http://www.qaforums.com/
- Automated Testing Resources (has links to more WinRunner related
  web sites):
    http://www.sqa-test.com/ATS_Tips.html



