@CREATEBLOCK

Creates a block or blocks for a sparse member name or a sparse member combination, and sets dense values in the newly created block to #MISSING.

Sometimes, new blocks are not desired; for example, when they contain no other values. In large databases, creation and processing of unneeded blocks can increase processing time and storage requirements.

This advanced-level function can help you use bottom-up calculation to achieve faster performance. It is useful for generating empty target blocks that can then be traversed during bottom-up processing, and populated with data at that time. It is most useful in those situations where blocks are not automatically created by the calculator; for example, during processing of a dense formula where the target blocks are from a different, sparse dimension.

Whereas the allocation functions (@ALLOCATE and @MDALLOCATE) also create the necessary target blocks, those functions are intended specifically for allocating values. The purpose of @CREATEBLOCK is only to enable rapid block creation, without reading or writing data.

Note:

  • This function is not supported in outline member formulas.

  • The DATACOPY calculation command also creates blocks on demand.

Syntax

@CREATEBLOCK(mbrName|mbrList)

Parameters

mbrName

Any single, sparse member name or a sparse member combination or a function that returns a single member, member list, or member combination. For example:

  • Single member name: ["200-20"]

  • Combination of sparse members: ["100-10"->"New York"]

  • Member function returning mbrName or mbrList: @ANCESTORS("New York")

Notes

  • This function does nothing if the block for the specified member combination already exists.

  • mbrName|mbrList can be explicitly stated or can be returned by a function.

  • If mbrName is a cross-dimensional member (such as "100-10"->"New York"), this function creates a block for the combination specified.

  • When you use this function in a calculation script, use it within a FIX statement; for example, FIX on the member for which blocks should be created. Although FIX is not required, using it may improve calculation performance.

  • If you use this function in a member formula, your formula should look like this: @CREATEBLOCK (...).

  • This function does not return a value; rather, it creates the required blocks in the database with a #MISSING value.

  • On sparse dimension members, a formula is executed in top-down mode, creating all possible blocks. However, if the dimension member is dense, it is executed as bottom-up, creating new blocks only based on the existing ones. Therefore, @CREATEBLOCK will not create dense blocks on an empty database.

  • For more discussion of top-down and bottom-up processing, see @CALCMODE.

Example

The following calculation script example uses the Sample.Basic database, but assumes that only the 100-10 and New York block is loaded. The member formula for Sales is @CREATEBLOCK("100").


/* Calling @CREATEBLOCK inside member formula (Sales) */
FIX("100-10", "New York")
   "Sales" (
         @CREATEBLOCK ("100");
     )
ENDFIX

The script creates all possible sparse blocks matching the FIX…ENDFIX statement. In this case, only the block "100"->"New York" is created.

In the following calculation script example, @CREATEBLOCK is not used in any member formula, so it must be assigned in the script using mbrName =.


/* Calling @CREATEBLOCK outside member formula */
Budget = @CREATEBLOCK ("100");

The existing value for Budget member in the current processing block is unchanged, because @CREATEBLOCK does not return a value (see first Note).