SQABasic "SuiteDriverStack" Library

 MODULE DESCRIPTION:

 Routines for implementing the SuiteDriver 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 SuiteDriverStates 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 IsSuiteDriverStackInit  BasicLib SuiteDriverStack 
Function InitSuiteDriverStack    BasicLib SuiteDriverStack 
Function GetSuiteDriverStackSize  BasicLib SuiteDriverStack 
Function SuiteDriverStackIsEmpty  BasicLib SuiteDriverStack 
Function SuiteDriverStackIsFull  BasicLib SuiteDriverStack 
Function ExpandSuiteDriverStack  BasicLib SuiteDriverStack 
   Sub   CaptureSuiteDriverState  BasicLib SuiteDriverStack 
Function PushSuiteDriverStack    BasicLib SuiteDriverStack 
Function PopSuiteDriverStack     BasicLib SuiteDriverStack 
Function PeekSuiteDriverStack    BasicLib SuiteDriverStack 
   Sub   GetLastSuiteDriverState  BasicLib SuiteDriverStack

Constants

    (none)

Globals

    (none)

User-Defined Types

Type SuiteDriverState
    status      AS AUStatusInfo  'SuiteDriverInfo
    fullStatus  AS AUStatusInfo  'SuiteDriverTestInfo
    guiInfo     AS AUGUIInfo     'SuiteDriverGUIInfo
    map         As String        'AUCurrentAppMap 
End Type

Routine Details


 Function IsSuiteDriverSTACKInit() As Integer

 DESCRIPTION:

  Verifies that the SuiteDriver 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Function InitSuiteDriverSTACK (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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Function GetSuiteDriverSTACKSize () 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Function SuiteDriverSTACKIsEmpty () 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Function SuiteDriverSTACKIsFull () 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Function ExpandSuiteDriverSTACK () 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Sub  CaptureSuiteDriverState (state As SuiteDriverState)

 DESCRIPTION:

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

 PARAMETERS:

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

 ERRORS:

       none

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

      JUL 21, 2000    Original Release







  Function PushSuiteDriverSTACK () As Integer

 DESCRIPTION:

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

          SuiteDriverInfo
          SuiteDriverTestInfo
          SuiteDriverGUIInfo
          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 21, 2000
 History:

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







  Function  PopSuiteDriverSTACK () As Integer

 DESCRIPTION:

      Pops a SuiteDriverState off the STACK.
      See PushSuiteDriverSTACK 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 21, 2000
 History:

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







  Function  PeekSuiteDriverSTACK (state As SuiteDriverState) As Integer

 DESCRIPTION:

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

 PARAMETERS:

      state       a SuiteDriverState 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 21, 2000
 History:

      JUL 21, 2000    Original Release







  Sub  GetLastSuiteDriverState (state As SuiteDriverState)

 DESCRIPTION:

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

      However, some routines that re-enter SuiteDriver 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 SuiteDriverState 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 21, 2000
 History:

      JUL 21, 2000    Original Release






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