UNDEFVALS

This function is valid only in rules. Use of this function in a TurboIntegrator process will result in an error.

Use of UNDEFVALS has ramifications regarding how data is stored in the cube and retrieved.

• Data Storage

  For a cube without UNDEFVALS in the rules, the default value is zero. If an attempt is made to store a zero in a cell of the cube, that storage request is ignored, as this is a redundant attempt to store the default value, and it would needlessly consume memory space. Similarly, if a cell already contains a value and the value is deleted, nothing is stored in the cell.

  If however the cube has UNDEFVALS defined in the rules, this makes the default value a special undefined value. Now when a zero is stored in a cell of a cube, it is actually stored, just like any other non-zero value.

  The special undefined value is only a run-time value, returned from requests for cell values. It is never stored in an actual cell in memory, and is never written to disk. Including UNDEFVALS in the rule for a cube has no effect on memory usage or disk storage, except for cells that actually contain zero as a value. When UNDEFVALS is included in the rule for a cube, zero values in that cube will consume memory space and will be written to disk, just like any other data value. If UNDEFVALS is not specified, zero value cells are not stored in memory nor are they written to disk.

• Data Retrieval

  For a cube without UNDEFVALS in the rules, the default value is zero. When a cell is retrieved, and there is no value currently stored for that value in the cube, a value of zero (as the default value) is returned. This means that an application cannot tell whether a cell actually exists and contains zero as the cell value, or whether the cell does not exist (as can be the case with sparse data).

  If however the cube has UNDEFVALS defined in the rules, this make the default value a special undefined value. In this case, when a non-existent cell is retrieved, the value retrieved will be this special undefined value. This can be used to distinguish a cell that does not exist (special undefined returned) from a cell that exists, but whose value is zero (zero returned). Any client written to run against Planning Analytics, which can encounter a cube with UNDEFVALS set, must be prepared to handle a cell value of this special undefined rather than a zero. A client can detect whether a value returned from Planning Analytics is this special undefined value with the TM1ValIsUndefined API function. For details on the TM1ValIsUndefined API function, see the TM1 API documentation.

  Note: This special undefined value is not the value returned by the UNDEF() TurboIntegrator function. The value returned by UNDEF() is an undefined value used for such things as an attempt to divide by zero, or take the logarithm of an illegal number, etc.

In TurboIntegrator, for normal arithmetic operations (+, -, *, /, \, ^) and normal arithmetic comparisons (<, >, >=, <=, =, <>), the special undefined value is treated as a zero. Because of this, the following code does not work:

NoCellVal = UndefinedCellValue( 'cube-name' );
If ( vv = NoCellVal );

In this comparison, NoCellVal, which is the special undefined value for an UNDEFVALS cube, is treated as a zero. This means the comparison is really If ( vv = 0 ).

 vv = CellGetN( 'cube-name', elements-list);
if ( IsUndefinedCellValue( vv, 'cube-name' ) = 1 ); 
#the cells does not exist 
cell_does_not_exist = 1;
else; 
#cell exists 
cell_does_not_exist = 0;
Endif;