@XREF

Enables a database calculation to incorporate values from another Essbase database.

The following terminology is used to describe @XREF:

  • Data target: the database on which the current calculation is running (that is, the database on which the @XREF call originates).

  • Data source: the database that is queried by @XREF. This database may be remote (that is, on a different machine than the data target).

  • Point of view: the member combination currently being calculated on the data target (that is, the member combination that identifies the left hand side of a calculation).

The @XREF function retrieves values from a data source to be used in a calculation on a data target. @XREF does not impose member and dimension mapping restrictions, which means that the data source and data target outlines can be different.

Syntax

There are multiple ways to call this function, depending on your goal.

To incorporate values from a remote cube, use:

@XREF (locationAlias [, mbrList])

To incorporate values from another application and database on the same Essbase server instance, use:

@XREF (appname, dbname [, mbrList])

Parameters

locationAlias

A location alias for the data source. A location alias is a descriptor that identifies the data source. A location alias is not needed if the source and target are on the same Essbase server instance.

If used, the location alias must be set on the database on which the calculation script will be run. The location alias is set by the database administrator and specifies a server, application, database, user name, and password for the data source.

mbrList

Optional. A comma-delimited list of member names that qualify the @XREF query. The members you specify for mbrList are sent to the data source in addition to the members in the current point of view in the data target. The data source then constructs a member combination, using in order of precedence:

  • The members specified in mbrList

  • The members in the current point of view

  • The top member in any unspecified dimensions in the data source

The mbrList parameter (1) modifies the point of view on the data target or (2) defines a specific point of view on the data source. For example, the following formula modifies the point of view on the data target:

2003(2003->Jan->Inventory = @XREF(sourceDB,Dec);)

If the cube on the data source (sourceDB) contains data only from 2002, this formula sets Inventory for Jan in 2003 to the Inventory value for Dec from 2002.

The following formula defines a specific point of view on the data target:

Jan = @XREF(sourceDB,January);

Assume that the data target contains the member Jan, while the data source (sourceDB) contains the member January. This formula simply maps the member in the data target (Jan) with its corresponding member in the data source (January), and pulls January from sourceDB.

See Notes for more information about the mbrList parameter.

appname, dbname
Application and cube name. Use only for deployments with only one Essbase server instance.

Notes

  • You must be signed in on the data target, and also provisioned on the data source.

  • An error is returned if the members supplied in mbrList do not exist in the data source.

  • The number of data cells queried on the data source must match the number of data cells expected on the data target.

  • The member list cannot contain functions that return more than one member. For example, the following formula is not valid:

    West = @XREF(SourceDb, @LEVMBRS(Market,0));
  • The member list cannot contain ranges. For example, the following formula is not valid:

    West = @XREF(SourceDb, Jan:Mar);
  • mbrList can contain attribute members. For example, if the data source classifies products based on a color attribute, the following formula would calculate the sum of the sales of all red products and would assign the result to member RedThings:

    RedThings = @XREF(SourceDb, Sales, Red);
  • mbrList can contain attribute operators. For example, the following formula calculates RedThings as the average sales of all red products:

    RedThings = @XREF(SourceDb, Sales, Red, Average);
  • @XREF can query all types of members. For example, members retrieved from a data source can be Dynamic Calc members as well as attribute members. Keep in mind that all performance considerations that apply to dynamic and attribute calculations also apply to @XREF queries that depend on dynamic and attribute members.

  • Over the course of an @XREF calculation, data in the source database may change. @XREF does not incorporate changes made after the beginning of the calculation.

  • @XREF is a top-down formula. For more information on top-down formulas, see Bottom-Up and Top-Down Calculation in Designing and Maintaining Essbase Cubes.

  • For a member that does not exist in either the data source or the data target, @XREF returns the value of the top dimension, not the value #M1.

  • If you are using @PARENT within @XREF, it must be within @NAME. For example:

    COGS=@XREF(Sample, @NAME(@PARENT(Product)),Sales);
  • When running a parallel calculation that includes @XREF, the application times out if the number of threads you specify to use is higher than the number of SERVERTHREADS. For example, the default value of SERVERTHREADS is 20. If you set CALCPARALLEL to 25, an application timeout error is generated.

Example

For this example, consider the following two databases:

Main Database

Year
  Qtr1
  Qtr2
Measures
  Sales
  Units  
Product
  100
    100-10
    100-20
Market
  East
  West
Scenario
  Budget
  Forecast

Inflation Rates Database

Year
  Qtr1
  Qtr2  
Assumptions
  Inflation
  Deflation = Inflation * .5 (Dynamic Calc)  
Country
  US
  Canada
  Europe

The following formula is associated with the Main Database:

Units = Units * @XREF(InflatDB,Inflation,US);

Where InflatDB is the location alias for the Inflation Rates Database and Inflation is the member for which a data value is retrieved from InflatDB.

In this example, Essbase calculates the following member combinations:

Units->Qtr1->100-10->East->Budget = Units->Qtr1->100-10->East->Budget * Inflation->Qtr1->US

Units->Qtr2->100-10->East->Budget = Units->Qtr2->100-10->East->Budget *Inflation->Qtr2->US and so on.