SQABasic CycleDriverStack Library

SQABasic "CycleDriverStack" Library

 MODULE DESCRIPTION:

 Routines for implementing the CycleDriver 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 CycleDriverStates 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.)

'$INCLUDE: "LogUtilities_X.SBH"
'$INCLUDE: "ApplicationUtilities_X.SBH"
'$INCLUDE: "CycleDriverSTACK_X.sbh" 'for CycleDriverState
'$INCLUDE: "CycleDriverStack.SBH"

Internal Dependencies:

(stuff this library needs at compile time.)

'$INCLUDE: "ApplicationUtilities.SBH"
'$INCLUDE: "DDUtilities_X.SBH"
'$INCLUDE: "CycleDriver_X.SBH"
'$INCLUDE: "BufferUtilities_X.SBH"
'$INCLUDE: "BufferUtilities.SBH"

Exported Declarations

Function IsCycleDriverStackInit  BasicLib CycleDriverStack 
Function InitCycleDriverStack    BasicLib CycleDriverStack 
Function GetCycleDriverStackSize  BasicLib CycleDriverStack 
Function CycleDriverStackIsEmpty  BasicLib CycleDriverStack 
Function CycleDriverStackIsFull  BasicLib CycleDriverStack 
Function ExpandCycleDriverStack  BasicLib CycleDriverStack 
   Sub   CaptureCycleDriverState  BasicLib CycleDriverStack 
Function PushCycleDriverStack    BasicLib CycleDriverStack 
Function PopCycleDriverStack     BasicLib CycleDriverStack 
Function PeekCycleDriverStack    BasicLib CycleDriverStack 
   Sub   GetLastCycleDriverState  BasicLib CycleDriverStack

Constants

    (none)

Globals

    (none)

User-Defined Types

Type CycleDriverState
    status      AS AUStatusInfo  'CycleDriverInfo
    fullStatus  AS AUStatusInfo  'CycleDriverTestInfo
    guiInfo     AS AUGUIInfo     'CycleDriverGUIInfo
    map         As String        'AUCurrentAppMap 
End Type

Routine Details

Function IsCycleDriverSTACKInit() As Integer

DESCRIPTION:

Verifies that the CycleDriver 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 InitCycleDriverSTACK (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 GetCycleDriverSTACKSize () 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 CycleDriverSTACKIsEmpty () 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 CycleDriverSTACKIsFull () 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 ExpandCycleDriverSTACK () 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 CaptureCycleDriverState (state As CycleDriverState)

DESCRIPTION:

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

PARAMETERS:

state a CycleDriverState reference to receive the captured state.
If there has been no CycleDriver 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 PushCycleDriverSTACK () As Integer

DESCRIPTION:

Pushes the current state of CycleDriver onto the STACK. If the STACK
has not been initialized then we initialize it first.
We push onto the stack by first copying the contents of critical Globals:

CycleDriverInfo
CycleDriverTestInfo
CycleDriverGUIInfo
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 PopCycleDriverSTACK () As Integer

DESCRIPTION:

Pops a CycleDriverState off the STACK.
See PushCycleDriverSTACK 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 PeekCycleDriverSTACK (state As CycleDriverState) As Integer

DESCRIPTION:

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

PARAMETERS:

state a CycleDriverState 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 GetLastCycleDriverState (state As CycleDriverState)

DESCRIPTION:

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

However, some routines that re-enter CycleDriver 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 CycleDriverState 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 
==============================================================================