SQABasic "StepDriverStack" Library

 MODULE DESCRIPTION:

 Routines for implementing the StepDriver STACK.

 NOTE:
 SQABasic does not allow an array to be part of a user-defined data type.
 Because of this, a STACK buffer is actually comprised of two things referred
 to as a buffer pairing:

      BufferInfo -- tracks pointers for read and
                write and size information.

      Buffer -- array of StepDriverStates used as
                the buffer

 These buffer pairings actually get modified separately and care must be taken to
 insure that they remain in sync with each other.  If they do not remain in
 sync then data corruption and unexpected program behavior (or maybe even
 access violations) could result.

 The routines in this library are intended to maintain both parts of the pair.
 See BufferUtilities for more information and routines used here to maintain this STACK.
Declarations Constants Global Variables User-Defined Types Routine Details

User Dependencies:

(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)

Internal Dependencies:

(stuff this library needs at compile time.)

Exported Declarations

Function IsStepDriverStackInit   BasicLib StepDriverStack 
Function InitStepDriverStack     BasicLib StepDriverStack 
Function GetStepDriverStackSize  BasicLib StepDriverStack 
Function StepDriverStackIsEmpty  BasicLib StepDriverStack 
Function StepDriverStackIsFull   BasicLib StepDriverStack 
Function ExpandStepDriverStack   BasicLib StepDriverStack 
   Sub   CaptureStepDriverState  BasicLib StepDriverStack 
Function PushStepDriverStack     BasicLib StepDriverStack 
Function PopStepDriverStack      BasicLib StepDriverStack 
Function PeekStepDriverStack     BasicLib StepDriverStack 
   Sub   GetLastStepDriverState  BasicLib StepDriverStack

Constants


    (none)

Globals


    (none)

User-Defined Types


Type StepDriverState
    status    AS AUStatusInfo  'StepDriverInfo
    info      AS AUGUIInfo     'StepDriverTestInfo
    map       As String        'AUCurrentAppMap 
End Type

Routine Details



 Function IsStepDriverSTACKInit() As Integer

 DESCRIPTION:

  Verifies that the StepDriver STACK appears to have been initialized.

 PARAMETERS:

      (none)

 RETURNS:

      BufferUtilities.BUFFER_INITIALIZED       If buffer appears initialized.
      BufferUtilities.BUFFER_NOT_INITIALIZED  One or more fields has unexpected values (usually 0)

 ERRORS:

   none

 Orig Author: Carl Nagle
 Orig   Date: JUl 11, 2000
 History:

      JUl 11, 2000    Original Release








  Function InitStepDriverSTACK (size As Integer, inc As Integer) As Integer

 DESCRIPTION:

      Initializes our STACK pairing with the initial size and increment
      value as provided.  The increment value is how much the buffer size
      should be increased each time it is resized.

      On exit, the pairing is initialized and ready for use.

 PARAMETERS:

      size    the size to initially allocate for the STACK buffer.
              If <1 then the default size of 5 will be used.

      inc     the increment value used when increasing the buffer size.
              If <1 then the default inc of 1 will be used.

 RETURNS:

      N           The initialized size of the STACK on exit.

      BufferUtilities.BUFFER_NOT_INITIALIZED   If a problem occurred.

 ERRORS:

       none

 Note:
 SQABasic does not allow an array to be part of a user-defined data type.
 Because of this, a STACK is actually comprised of two things referred to as
 a buffer pairing:

      BufferInfo  tracks pointers for read and write and size information
      Buffer      array of the desired type used as the buffer

 These buffer pairings actually get modified separately and care must be taken to
 insure that they remain in sync with each other.  If they do not remain in
 sync then data corruption and unexpected program behavior (or maybe even
 access violations) could result.

 The routines in this library are meant to fully implement the buffer
 pairings for the user.  Calls to the routines in the BufferUtilities
 library are not necessary and should be avoided.

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Function GetStepDriverSTACKSize () As Integer

 DESCRIPTION:

      Retrieves the number of items currently stored in the STACK buffer.
      You CANNOT simply read the value of the info.size field.

 PARAMETERS:

      (none)

 RETURNS:

      N           The current number of items in the STACK buffer.

      BufferUtilities.BUFFER_NOT_INITIALIZED   If a problem occurred.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Function StepDriverSTACKIsEmpty () As Integer

 DESCRIPTION:

      Determines if there are no entries in the STACK.

 PARAMETERS:

      (none)

 RETURNS:

      BufferUtilities.BUFFER_INITIALIZED       If buffer is NOT empty.
      BufferUtilities.BUFFER_IS_EMPTY          If buffer is empty.
      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Function StepDriverSTACKIsFull () As Integer

 DESCRIPTION:

      Determines if the STACK is full.

 PARAMETERS:

      (none)

 RETURNS:

      BufferUtilities.BUFFER_INITIALIZED       If buffer is NOT FULL.
      BufferUtilities.BUFFER_IS_FULL           If buffer is FULL.
      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Function ExpandStepDriverSTACK () As Integer

 DESCRIPTION:

      Expand the STACK by the amount stored as the redimIncrement.
      The STACK is redimmed PRESERVing the existing contents.

 PARAMETERS:

      (none)

 RETURNS:

      N               The number of available (unused) items in the buffer.

      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Sub  CaptureStepDriverState (state As StepDriverState)

 DESCRIPTION:

      Captures the current state of the StepDriver.
      The state information available are the fields defined in the
      StepDriverState user-defined data type.

 PARAMETERS:

      state       a StepDriverState reference to receive the captured state.
                  If there has been no StepDriver activity then the returned
                  state will contain uninitialized or default values for fields.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Function PushStepDriverSTACK () As Integer

 DESCRIPTION:

      Pushes the current state of StepDriver onto the STACK.
      We do this by first copying the contents of critical Globals:

          StepDriverInfo
          StepDriverTestInfo
          AUCurrentAppMap

      Then push the copies to the STACK.

 PARAMETERS:

      (none)

 RETURNS:

      N                          new calculated count of items in the buffer.

      BufferUtilities.BUFFER_IS_FULL     error if buffer is FULL and fails to be
                                  expanded (which is attempted).

      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release
      JAN 21, 2001    (CANAGL) Redesigned reentrancy and the STACK.








  Function  PopStepDriverSTACK () As Integer

 DESCRIPTION:

      Pops a StepDriverState off the STACK.
      See PushStepDriverSTACK for what is stored in the STACK.

 PARAMETERS:

      none

 RETURNS:

      N                          new calculated count of items in the buffer.
                                  (0 if empty AFTER the POP.)

      BufferUtilities.BUFFER_IS_EMPTY          If buffer is empty on entry.
      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release
      JAN 21, 2001    (CANAGL) Redesigned reentrancy and the STACK.








  Function  PeekStepDriverSTACK (state As StepDriverState) As Integer

 DESCRIPTION:

      Retrieves the next value from the STACK without popping it off.

 PARAMETERS:

      state       a StepDriverState reference to receive the object

 RETURNS:

      N           the count of items in the buffer.

      BufferUtilities.BUFFER_IS_EMPTY          If buffer is empty on entry.
      BufferUtilities.BUFFER_NOT_INITIALIZED   If buffer appears uninitialized.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release








  Sub  GetLastStepDriverState (state As StepDriverState)

 DESCRIPTION:

      Retrieves the state of the StepDriver just prior to the last POP.

      However, some routines that re-enter StepDriver will want to get a
      handle on their own separate statistics for reporting or logging
      purposes.  To do this, they must get the statistics before the POP
      or call this routine before the next PUSH.

 PARAMETERS:

      state       a StepDriverState reference to receive the stored state.
                  If there has never been a PUSH or a POP then the returned
                  state will contain uninitialized or default values for fields.

 ERRORS:

       none

 Orig Author: Carl Nagle
 Orig   Date: JUL 11, 2000
 History:

      JUL 11, 2000    Original Release






Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php 
==============================================================================