C-API: TM1ValArraySize is not present in the TM1 API

[MartinBrandl]

Hi all,

I missing the function "TM1ValArraySize"in the TM1 C-API (Tm1api.h). I need this to determine the actual number of array elements returned from "TM1CubeCellsValueSet".
I already tryed to use "TM1ValArrayMaxSize" but then, the next call "TM1ValArrayGet" causes a crash in the tm1api.dll.

The manual of the TM1 API tells me to use TM1VallArrraySize instead of TM1ValArrayMaxSize:

TM1ValArrayMaxSize returns the maximum number of components of an array value capsule.
The actual number of array elements in the value capsule is returned by the function
TM1ValArraySize

The tm1api.dll does export this function, but it's not included in the API header.
Is there any reason? What can I use instead?

Cheers,
Martin

[Wim Gielis]

Hello

At least in the TM1 API for VB, that one is missing.

It was noted by Alan Kirk in the TM1 tools code:
http://www.tm1forum.com/viewtopic.php?f=21&t=2515

Please download the code, install the addin and look at the list of API functions in one of the modules

At the bottom, you will find the call to that function, including Alan's remarks.

[MartinBrandl]

Hello Wim,

I found the remarks from Alan:

'Despite the API manual making much mention of this function,
'it hasn't been declared in the standard module, nor has it been documented. I assumed
'(apparently correctly) that it uses the same arguments as TM1ValArrayMaxSize.
'CAUTION! It returns thr ACTUAL VALUE, NOT a handle to a value capsule containing
'the value. I discovered this during standard API error handling (i.e., an Excel crash).
'Alan Kirk, 14-Feb-11
Declare Function TM1ValArraySize Lib "tm1api.dll" (ByVal hUser As Long, ByVal vArray As Long) As Long

Do I realy need to declare this function? Can't I use "TM1ValArrayMaxSize" in context with "TM1CubeCellsValueSet"?

Cheers,
Martin

[Alan Kirk]

Hello Wim,

I found the remarks from Alan:

'Despite the API manual making much mention of this function,
'it hasn't been declared in the standard module, nor has it been documented. I assumed
'(apparently correctly) that it uses the same arguments as TM1ValArrayMaxSize.
'CAUTION! It returns thr ACTUAL VALUE, NOT a handle to a value capsule containing
'the value. I discovered this during standard API error handling (i.e., an Excel crash).
'Alan Kirk, 14-Feb-11
Declare Function TM1ValArraySize Lib "tm1api.dll" (ByVal hUser As Long, ByVal vArray As Long) As Long

Do I realy need to declare this function? Can't I use "TM1ValArrayMaxSize" in context with "TM1CubeCellsValueSet"?

Cheers,
Martin

Not the same thing. As per page 22 of the API manual:

TM1ValArrayMaxSize returns the maximum number of components of an array value capsule.
The actual number of array elements in the value capsule is returned by the function TM1ValArraySize.

(My emphasis.)

It means that the array may be able to store more elements than there actually are, but if you were iterating through the array members you'd need to check one by one to make sure that they're valid rather than empty. (Ideally without running into an error that will crash the client, as the API is wont to do.) I would expect that it would also have a negative performance impact on your code if you have an extremely large array.

TM1CubeCellsValueSet itself doesn't directly need or use that function; I'd assume that you're using it to construct the arrays to be passed to it. You'd need to look at your code in the context of the difference described above and determine whether you could get away with making the substitution.

[MartinBrandl]

Hi Alan,

I'm writing a set of values to TM1 using the code below:

Code: Select all

...
TM1V  hArrayOfCells		= TM1ValArray( cPool, cCellList.Array(),  cCellList.Count()  );
TM1V  hArrayOfValues	= TM1ValArray( cPool, cValueList.Array(), cValueList.Count() );
ASSERT( cValueList.Count() == cCellList.Count() );

// Update the value of an array of cells in a cube
TM1V			hResultArray	= TM1CubeCellsValueSet( cPool, hCube, hArrayOfCells, hArrayOfValues );
ASSERT( NULL != hResultArray );

TM1_INDEX	iResultCount		= TM1ValArrayMaxSize( mpcConnection->GetSystemHandle(), hResultArray );

// Error handling. 
for ( TM1_INDEX i = 1; i <= iResultCount; i++ )
{
	TM1V hResult	= TM1ValArrayGet(mpcConnection->GetSystemHandle(), hResultArray, i);
...

The crash occurs only in a special, complex case - somewhere below TM1CubeCellsValueSet. In most cases, the function works fine.
It must have something to do with the handle return from TM1CubeCellsValueSet. I expected that I have to use TM1ValArraySize instead of TM1ValArrayMaxSize. Is that generally right?

Cheers,
Martin