The VarValues Service Class
The service class
VarValues contains those methods used by the engine to allocate,
store, and retrieve variable values.
The members of the
tVariable structure used by this class are as follows:
| Member | Description of content
|
| migComment | Contains the sequence number of the variable, starting at one, within the list
of parameters and then local variables declared within the subprogram.
|
| specInfo | If the variable is a scalar then this is set to zero else it is set to the
the number of elements in the array.
|
The method VarValues_Construct
Prototype
void* VarValues_Construct(int subRoot)
The
VarValues_Constuct method initializes the values of the local variables
associated with a subprogram. Each call to a subprogram constructs a variable values vector.
In the case of recursion there is one varvalues vector for each active call to the
subprogram. Its parameter is:
| Parameter | Description
|
| subRoot | specifies the root offset of the subprogram being called.
|
Each parameter and local variable defined for the subprogram is assigned a sequence number
starting at one by the method
VarValues_SetLocalVariables. The corresponding entry
in the values vector controls the values for that component during the current call to the
subprogram. The zero member of the values vector contains the control information for
the values vector itself.
The method returns an opaque handle to the variable values vector. It is this handle that is
referred to as
This in methods using this vector.
The method VarValues_Destroy
Prototype
void VarValues_Destroy(void* This)
The
VarValues_Destroy method destroys a variable values vector for a subprogram call
when that call exits the subprogram. All scratch information storage associated with the
parameters and local variables associated with the subprgram call is released to the scratch
information manager. This includes the variable values vector itself. Its parameter is:
| Parameter | Description
|
| This | specifies the handle of the variable values vector. After this call the content
of this handle is no longer valid.
|
The method VarValues_GetHandle
Prototype
void* VarValues_GetHandle(void* This,int seq)
The
VarValues_GetHandle method is called when a member of a variable with a structure
type is being accessed. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose member is being accessed.
|
The method returns a pointer to the start of the value vector for this instance of the
structure.
The method VarValues_GetType
Prototype
int VarValues_GetType(void* This,int seq)
The
VarValues_GetType method simply gets the type of a variable instance from the
variable values vector. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose type is being gotten.
|
The engines using this class support variant types that are not imposed on
a variable until runtime. The consequence of this is that variables do not necessarily
have the same type in different executions of their subprogram. The type is recorded in
the variable value vector and not in the information vector of the variable itself.
The method VarValues_GetValue
Prototype
int VarValues_GetValue(void* This,int seq)
The
VarValues_GetValue method simply gets the value entry of a variable instance from
the variable values vector. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose value is being gotten.
|
The method VarValues_PopHandle
Prototype
void* VarValues_PopHandle(void* This)
The
VarValues_PopHandle method pops a handle to a value that is to be passed to a
method expecting a pointer to a structure, array, or ByRef parameter. Its parameter is:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
The method pops a value or vector from the runtime data queue and returns a pointer obtained
from the information popped to an actual value or value vector that is being passed to
a method.
The method VarValues_PopObject
Prototype
void* VarValues_PopObject(void* This)
The
VarValues_PopObject method pops an object handle of a value instance. Its
parameter is:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
First, the sequence number of a variable is popped fron the stack. If that variable has an
object type with values associated with it then the handle to those values is returned. If no
values are associated with the object type, they are initialized in scratch information
storage and the handle is returned. If not an object type, then a simple pointer to the
values is returned.
The method VarValues_PushObject
Prototype
void VarValues_PushObject(int symRoot,int symType,void* handle)
The
VarValues_PushObject method creates an object and pushes its attribute vector onto
the runtime data queue. Its parameters are as follows:
| Parameter | Description
|
| symRoot | specifies the root of the object.
|
| symType | specifies the object type of the object.
|
| handle | specifies the handle for the information associated with the object.
|
The method VarValues_PushValue
Prototype
void VarValues_PushValue(void* This,int seq,int subscript)
The method pushes the possibly subscripted value of a variable onto
the runtime data queue. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose value is being pushed.
|
| subscript | specifies the subscript relative to 0 of the value if the variable is an array.
If the variable is not an array this parameter is ignored.
|
The method VarValues_SetExternalCall
Prototype
void VarValues_SetExternalCall(void* This,int subRoot, char* prams)
The
VarValues_SetExternalCall method sets the parameter values of a subprogram when
that subprogram is being called via from an external source. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| subRoot | specifies the root offset of the subprogram being called.
|
| prams | contains the values to be assigned to the parameters of the subprogram. For
integer parameters it should contain a valid integer representation and for
booolean parameters it should contain ".T." or ".F.".
|
The method VarValues_SetInternalCall
Prototype
void VarValues_SetInternalCall(void* This, int subRoot)
The
VarValues_SetInternalCall method sets the parameter values of a subprogram when
that subprogram is being called via from an internal source. Its parameters ar as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| subRoot | specifies the root offset of the subprogram being called.
|
The actual initial parameter values for the subprogram are popped from the runtime data
queue.
The method VarValues_SetLocalVariables
Prototype
void VarValues_SetLocalVariables(int subRoot)
The
VarValues_SetLocalVariables method is called by the
gmSL compiler after the
code for a subprogram has been compiled. It scans the symbols associated with the subprogram
for local variables and their control structures as required by the runtime engine. The
control structure for the subprogram is modified as well to specify the number of local
variables. Its parameter is as follows:
| Parameter | Description
|
| subRoot | specifies the rool offset of the complied gmSL method.
|
The method VarValues_SetValue
Prototype
void VarValues_SetValue(void* This,int seq,int value)
The
VarValues_SetValue method sets the simple value of a variable instance. Its
parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose value is being set being set.
|
| value | specifies the new value.
|
The method VarValues_StoreValue
Prototype
void VarValues_StoreValue(void* This,int seq,int subscript)
The method pops a value from the runtime data queue and stores it
in the possibly subscripted value of a variable. Its parameters are as follows:
| Parameter | Description
|
| This | specifies the handle of the variable values vector.
|
| seq | specifies the sequence number of the variable whose value is being stored.
|
| subscript | specifies the subscript relative to 0 of the value if the variable is an array.
If the variable is not an array this parameter is ignored.
|