2.2.5.2.3 Cache Items

Cache items represent specific instances of the entities represented by cache fields (section 2.2.5.2.2). For example, an instance of a Country/Region cache field might be the USA cache item. Having a USA cache item in the Country/Region cache field enables the associated PivotTable view (section 2.2.5.3) to display data by USA.

Each cache item specifies a value and a type. In some cases, a cache item can have additional information associated with it as well.

A cache item is contained in a cache field. A cache field can have zero cache items if the cache field is not in use in the PivotTable view.

A cache item index can be used to reference a cache item within the cache field. Referencing a cache item by index requires an implicit or explicit reference to that cache field because a cache item collection is associated with a specific cache field. A cache field can be referenced by a cache field index, as specified in section 2.2.5.2.2.

If the records that specify the cache field include a sequence of records that conform to the PCDFATBL rule (defined in section 2.1.7.38), then the records that conform to the PCDFATBL rule specify the raw cache items of the cache field.

If the records that specify the cache field include a sequence of records that conform to the PCDFGITEMS rule (defined in section 2.1.7.38), then the records that conform to the PCDFGITEMS rule specify the grouping (section 2.2.5.2.4) cache items of the cache field. These are used for some grouping cache fields in non-OLAP PivotCaches (section 2.2.5.2).

If there are no grouping cache items but there are raw cache items, the cache item index is a zero-based index into the raw cache items.

If there are grouping cache items, then the cache item index is a zero-based index into the grouping cache items.

For raw cache items (records in PCDFATBL), each raw cache item is specified by one of the following:

• A record that conforms to the PCDI rule (defined in section 2.1.7.38), excluding the records specified by the sequence of records that conform to the PCDIRUN rule (defined in section 2.1.7.38).

• A record that conforms to the PCDIA rule (defined in section 2.1.7.38). These raw cache items have additional information.

• An entry in the rgPCDINumber, rgPCDIString, rgPCDIError or rgPCDIDatetime fields of the BrtBeginPCDIRun (section 2.4.147) record.

There can be multiple entries of source data (section 2.2.5.2.1) that have the same combination of value and type for a cache field (section 2.2.5.2.2). Each raw cache item within a cache field MUST have a unique combination of value and type.

For grouping cache items (records in PCDFGITEMS (section 2.1.7.38), each grouping cache item is specified by one of the following:

• A PCDI rule (defined in section 2.1.7.38), excluding the records specified by the PCDIRUN rule (defined in section 2.1.7.38).

• An entry in the rgPCDINumber, rgPCDIString, rgPCDIError or rgPCDIDatetime fields of the BrtBeginPCDIRun record.

A BrtBeginPCDIRun record specifies multiple sequential cache items of the same type and is used to reduce file size.

A grouping (section 2.2.5.2.4) cache field MUST have grouping cache items.

A grouping cache field with the fSrcField field of the BrtBeginPCDField (section 2.4.136) record of the cache field equal to 1 MUST have raw cache items.

A cache field that is not a grouping cache field MUST NOT have grouping cache items.

If there are one or more references by index to cache items of a particular cache field, that cache field MUST have cache items.

For an OLAP PivotCache (section 2.2.5.2) , a measure (section 2.2.5.2.7.1) cache field associated with a cache hierarchy (section 2.2.5.2.7) MUST NOT have cache items.

For an OLAP PivotCache, a cache item with a string value specifies the unique name of an OLAP member, unless the cache field is a member property cache field.

Raw cache items can contain unused cache items, each specified by a sequence of records that conform to the PCDIA rule. Unused cache items are values that did not exist in the source data (section 2.2.5.2.1) when the PivotCache was last refreshed, but existed when the PivotCache was refreshed previously. The PivotCache can retain such unused cache items to preserve information associated with them to reapply that information if the value corresponding to the cache item is added back to the source data. The fGhost field of the PCDIAddlInfo (section 2.5.100) structure specifies whether a cache item is unused.

The following example shows cache items and their association with source data.

Consider a PivotCache based on the following source data table:

Four cache fields exist, and each one corresponds to one of the columns (1): Country/Region, Product, Date, and Sales. Each of the four cache fields can have cache items corresponding to the unique values in the source data columns (1) as illustrated in the following tables.