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.