![]() Previous |
![]() Next |
The INCLUDE statement includes one model within another model. You can use the INCLUDE statement only within models.
Use INCLUDE to create modular models by placing equations that are common to several models, in a separate model for inclusion on other models as needed. The INCLUDE statement also facilitates what-if analyses. An experimental model can draw equations from a base model and selectively replace them with new equations
Syntax
INCLUDE model
Parameters
The name of a model to include in the current model. The current model is referred to as the parent model. The model that you include is referred to as the base model.
Usage Notes
Guidelines for Coding INCLUDE Statements in a Model
Follow these guidelines for using INCLUDE statements in models:
A model can contain only one INCLUDE statement.
The INCLUDE statement must be before any equations in the model.
A model that contains an INCLUDE statement cannot contain any DIMENSION statements.
How to Nest Models
You can nest models by placing an INCLUDE statement in a base model. For example, model myModel1
can include model myModel2
, and model myModel2
can include model myModel3
. The nested models form a hierarchy. In this example, myModel1
is at the top of the hierarchy, and myModel3
is at the root. A base model cannot include a model at a higher level in the hierarchy. In the preceding example, myModel2
cannot include myModel1
, and myModel3
cannot include myModel1
or myModel2
.
Dependencies Among Equations
When compiling a model that contains an INCLUDE statement, the compiler considers the dependencies among the equations from all the included models when it orders and blocks the equations. Therefore, when you run the MODEL.COMPRPT
program to examine the results of the compilation or when you set the MODTRACE option to YES
before running the parent model, you might find that equations from different levels in the hierarchy of included models are interspersed. See Example: Producing a Compilation Report.
When the compiler finds no dependencies among the equations from the included models, it executes the equations in the root model first and the equations in the parent model last.
Compiling a Parent Model
When you compile a parent model, the compiler compiles all the base models under it in the included hierarchy when compiled code does not already exist. When the compiler detects an error in an included model, neither it nor any model above it in the hierarchy is compiled. When the root model of the included hierarchy contains an error, the higher-level models are unable to inherit any DIMENSION statements from the root model. In this case, the compiler might report an error in a parent model when the source of the error is actually in the root model. For example, the compiler might report that a target dimension value does not exist in any attached analytic workspace. On the other hand, when the compiler detects an error in a parent model but finds no errors in the included models, the included models are compiled even though the parent model is not.
Masking Equations
To support what-if analyses, Oracle OLAP allows equations in a model to mask previous equations. The previous equations can come from the same model or from included models. A masked equation is not executed. When you run the MODEL.COMPRPT
program after compiling the model, the masked equation is not shown in the report on the compiled model.
Masking can take place when an equation assigns a value to a variable or dimension value that is also the target of a previous equation. The masking rules are as follows:
When the target in the earlier equation is qualified the same as the target in the later equation, the earlier equation is masked and the later equation is executed. The following example illustrates two equations with targets that are identically qualified.
Equation from a base model: BUDGET(LINE REVENUE) = 5000 Equation from the parent model: BUDGET(LINE REVENUE) = 3500
In this example, the equation from the base model is masked and the equation from the parent model is executed.
When the target in the earlier equation is more qualified than the target in the later equation, the earlier equation is masked. The later equation is executed.
The target that is more qualified is the one that affects the fewest dimension values. Consider the following equations from a base model and a parent model.
Equation from a base model: BUDGET(LINE REVENUE) = 2500 Equation from the parent model: BUDGET = 4000
The equation from the base model is more qualified because it assigns data only for the REVENUE value of the LINE dimension. The equation from the parent model assigns data to all the values of the LINE dimension. In this example, the equation from the base model is masked and the equation from the parent model is executed.
When the target in the earlier equation is less qualified than the target in the later equation, no masking takes place. Both equations are executed.
Consider the following equations from a base model and a parent model.
Equation from a base model: BUDGET = LAG(ACTUAL, 1, MONTH) Equation from the parent model: BUDGET(LINE REVENUE) = 6500 Equation from the parent model: BUDGET(LINE COGS) = 4000
The equation from the base model assigns data to all the values of the LINE dimension. The equations from the parent model are more qualified because each assigns data only for a single value of the LINE dimension. In this example, the equation from the base model is executed first, and then the equations from the parent model are executed.
This functionality enables you to assign a large number of values with one equation and use subsequent equations to replace or test individual values.
When the target in the earlier equation is qualified differently from the target in the later equation, no masking takes place. Both equations are executed. In the following example, both equations are executed.
Equation from a base model: BUDGET(LINE REVENUE) = 5000 Equation from the parent model: BUDGET(LINE COGS) = 4500
Examples
Including a Model
This example shows a parent model named income.plan
that includes a base model named base.lines
.
DEFINE income.plan MODEL MODEL INCLUDE base.lines revenue = LAG(revenue, 1, month) * 1.02 cogs = LAG(cogs, 1, month) * 1.01 taxes = 0.3 * opr.income END DEFINE BASE.LINES MODEL MODEL DIMENSION line month net.income = opr.income - taxes opr.income = gross.margin - marketing gross.margin = revenue - cogs END
Producing a Compilation Report
The following statements compile the parent model and produce a compilation report.
COMPILE income.plan MODEL.COMPRPT income.plan
These statements produce the following output.
MODEL INCOME.PLAN <LINE MONTH> BLOCK 1 (SIMPLE) INCOME.PLAN 2: revenue = lag(revenue, 1, month) * 1.02 INCOME.PLAN 3: cogs = lag(cogs, 1, month) * 1.01 BASE.LINES 4: gross.margin = revenue - cogs BASE.LINES 3: opr.income = gross.margin - marketing INCOME.PLAN 4: taxes = 0.3 * opr.income BASE.LINES 2: net.income = opr.income - taxes END BLOCK 1