IPB_Session interface:
AcquireArrayItemValue method
Description
Clones the data in the PBCallInfo structure in an array item
and resets the IPB_Value pointer.
Syntax
AcquireArrayItemValue( pbarray array, pblong dim[ ])
Argument
|
Description
|
|---|
array
|
A valid pbarray structure.
|
dim
|
A pblong array to
hold the indexes of all dimensions of the array. The size of the
array must equal the dimensions of array.
|
Return Values
IPB_Value*.
Examples
This FOR loop acquires the value
of an item in an array and sets the value in another array:
for( i=1; i <= bound; i++)
{
dim[0]= i;
ipv = Session -> AcquireArrayItemValue(refArg, dim);
Session -> SetArrayItemValue(*i_array, dim, ipv);
Session -> ReleaseValue(ipv);
}
Usage
The AcquireArrayItemValue method enables
you to retain the data in the PBCallInfo structure for a single
array item.
The AcquireArrayItemValue method is independent
of the type of the data but is most useful for acquiring the value
of pointer values, such as pbvalue_string, pbvalue_blob,
and so on. When you call FreeInfo, the data is
not freed and the pointer returned by AcquireArrayItemValue is
still valid.
When you no longer need the data, you must call
the ReleaseValue method to free the data. Failing
to do so causes a memory leak.
The PBVM clones a new IPB_Value and resets the existing
one. If you attempt to get or acquire the original value, the value
returned is zero or null until another IPB_Value
is set to the value.
Working with large arrays The processing that the AcquireArrayItemValue and ReleaseValue methods perform
results in poor performance when handling large arrays. It is more efficient
to get the type of the array and handle each type with appropriate type–specific
functions.
See Also
ReleaseValue