Class VarTrace

VarSpace
ClassModule VarTrace

An event source designed to allow users to trace reads and writes on variables.
Developer Documentation
C:\AAA-Exchage\DocuPro6\VarSpace\VarTrace.cls

Description:
This object is designed to allow external programs to receive events whenever a variable is read from, written to, or destroyed. The following code properly dimensions a VarTrace object to receive events:

Dim WithEvents vt As VarTrace
After reserving space for the VarTrace object itself, events may be captured using the standard event capture mechanism of other Visual Basic events sources such as Textboxes, Buttons and other Controls. Note: The "WithEvents" keyword may only be used in class type VB modules including Forms, Classes and Controls.

Author:
Andrew Friedl

Copyright:
1997.03.10, BlackBox Software & Consulting


Variables
Private
m_Var As Variable
m_ID As String

General Methods
object members
Variable Friend Property Get Variable() As Variable
        Returns a reference to the variable being traced
Variable Friend Property Set Variable(V As Variable)
        Sets a reference to the variable being traced
ID Friend Property Get ID() As String
        Retrieves the globally unique identifier for the VarTrace object.
ID Friend Property Let ID(S As String)
        Sets the globally unique identifier for the VarTrace object.
Quit Public Sub Quit()
        Causes the VarTrace object to disconnect itself from the variable being traced.
TraceRead Friend Sub TraceRead(Value)
        Subroutine to be called when the Variable being traced is Read.
TraceWrite Friend Sub TraceWrite(OldValue As Variant, NewValue As Variant)
        Subroutine to be called when the Variable being traced is Written.
TraceDestroy Friend Sub TraceDestroy(Value As Variant)
        Subroutine to be called when the Variable being traced is about ti be destroyed.

General Methods - Detail
object members

Variable

Returns a reference to the variable being traced

Description:
When a VarTrace is monitoring a Variable for reads, writes and destruction, it maintains a reference to the Variable object being traced. This reference is needed by the tracer object so that tracing may be terminated when it is desirable to do so.

Definition:
Friend Property Get Variable() As Variable

Returns:
a reference to the Variable object being traced.


Variable

Sets a reference to the variable being traced

Description:
When a VarTrace is monitoring a Variable for reads, writes and destruction, it maintains a reference to the Variable object being traced. This reference is needed by the tracer object so that tracing may be terminated when it is desirable to do so. param V a reference to the Variable object to be traced.

Definition:
Friend Property Set Variable(V As Variable)


ID

Retrieves the globally unique identifier for the VarTrace object.

Description:
When a VarTrace is created, it is assigned a globally unique ID that allows differentiation between VarTrace objects.A hold over from previous version, this property may be depracated in future releases.

Definition:
Friend Property Get ID() As String

Returns:
A string identifier.


ID

Sets the globally unique identifier for the VarTrace object.

Description:
When a VarTrace is created, it is assigned a globally unique ID that allows differentiation between VarTrace objects.A hold over from previous version, this property may be depracated in future releases.

Definition:
Friend Property Let ID(S As String)

Parameters:
S A string identifier.


Quit

Causes the VarTrace object to disconnect itself from the variable being traced.

Description:
After a call to the Quite subroutine, no more events will be triggered for reads, writes, or deletes upon the variable being traced. An instance of VarTrace is rendered useless after to this subroutine. Note: Quite is always called prior to the destruction of a VarTrace object, and it is generally a good ides to set them to Nothing when you're done with them.

Definition:
Public Sub Quit()


TraceRead

Subroutine to be called when the Variable being traced is Read.

Description:
When a traced Variable is read, the Variable object indicates this to all appropriate VarTraces assigned to it by calling this member subroutine on each one of them. This subroutine Raises the TraceRead event. User code then has direct control over the read process if code has been setup to capture the event. Note: Because the TraceRead event occurs prior to the users retrieval of data, the value can be altered within the event, allowing users to create dynamic variables such as auto-incrementing values.

Definition:
Friend Sub TraceRead(Value)

Parameters:
Value The current (Variant) value of the Variable. This value is read/write and may be altered within the event procedure.


TraceWrite

Subroutine to be called when the Variable being traced is Written.

Description:
When a traced Variable is written, the Variable object indicates this to all appropriate VarTraces assigned to it by calling this member subroutine on each one of them. This subroutine Raises the TraceWrite event. User code then has direct control over the write process if code has been setup to capture the event. Note: Because the Tracewrite event occurs prior to the storage of the users data, the new value can be altered within the event, allowing users to create dynamic or read only. This also allows dynamic updates of external conditions based upon changes of variables stored within the VarStack.

Definition:
Friend Sub TraceWrite(OldValue As Variant, NewValue As Variant)

Parameters:
OldValue The current value assigned to the Variable.
NewValue The value that is about to be assigned to the Variable. Altering this value alters the values that will be stored in the Variable. Note: If this value is altered within the TraceWrite event, subsequent VarTraces receive the altered value instead of the original value.


TraceDestroy

Subroutine to be called when the Variable being traced is about ti be destroyed.

Description:
When a Variable is about to be deleted, it informs all VarTraces currently assigned to it by calling this subroutine on each of them. User code (if assigned) is informed via the TraceDestroy event.

Definition:
Friend Sub TraceDestroy(Value As Variant)

Parameters:
Value a variant type that is the current value of the variable. Altering the Value has no effect as the variable will be destroyed immediately after all traces have been notified.


Generated by BlackBox Software's DocuPro for VB6
Software and Documentation Copyright 1999,2000 BlackBox Software, All Rights Reserved