COMPILE

The COMPILE command generates compiled code for a compilable object, such as a program, formula, model, or aggmap without running it and saves the compiled code in the analytic workspace. During compilation, COMPILE checks for format errors, so you can use COMPILE to help debug your code before running it. COMPILE records the errors in the current outfile.

However, you are not required to use the COMPILE command before running a compilable object. When you do not use the COMPILE command, Oracle OLAP automatically compiles a compilable object the first time you run it after entering or changing its contents. This automatic compilation is unnoticeable except for a slight delay while it is happening.

Whether you compile an object explicitly with COMPILE or automatically through running it, the code executes faster whenever you subsequently run the object during the same session, because the code is already compiled. When you update and commit your analytic workspace, the compiled code is saved as part of your analytic workspace and can be used in later sessions. The code thus executes faster the first time it is run in each later session.

Using the COMPILE command to compile code without running a compilable object is especially useful when you are writing code that will be part of a read-only analytic workspace (that is, a analytic workspace that people can use but not update).

Syntax

COMPILE object-name

Arguments

object-name

The name of a compilable object that you want to compile.

Notes

A number of options effect compilation. These options are listed in Table 9-1, "Compilation Options".

When you delete or rename an object in your analytic workspace, Oracle OLAP automatically invalidates the compiled code for every statement in a program and every formula and model that depends on that object. When you try to execute code that refers to the deleted or renamed object, Oracle OLAP tries to compile the code again. Unless you have defined a new object with the same name, you will receive an error message at this time.

When you run a program that contains invalidated code, it is compiled and executed one statement at a time. To save compiled code for the entire program, use the COMPILE command to explicitly compile it.

When a single statement has more than one error, COMPILE finds only the first error. However, COMPILE continues checking for format errors in subsequent statements.

Explicit compilation using the COMPILE command offers several advantages over automatic compilation:

• For any compilable object, COMPILE generates compiled code without executing the code in the object.

• In a program or model, automatic compilation diagnoses an error only in the first statement that contains an error. It then displays the error message and halts the execution of a program or the analysis of a model. So each time a program or model is automatically compiled, only a single error message is displayed. In contrast, COMPILE checks every statement in a program or model for correct format, and generates multiple error messages, one for each statement that contains an error. (In programs, some types of statements cannot be compiled, so they are exceptions. See "Errors COMPILE Does Not Catch".) Since COMPILE shows you every statement that contains at least one error, this minimizes the number of times you must edit the code to correct all errors.

• For a model, you may want to examine the results of the compilation or set options for handling simultaneous equations before you run the model.

Because the COMPILE command does not actually execute code, it can compile code that, for reasons unrelated to format errors, might not be successfully executed when the object were actually run. In a program, for example, you can compile the following statement, even though 'joplin' is not a district.

LIMIT district TO 'joplin'

Although the statement compiles successfully, you will get an error message at runtime.

In programs, certain statements cannot be compiled at all, and are therefore interpreted each time they are executed. These include statements that contain ampersand substitution, statements involving analytic workspace operations, and any statement that calls a program as a command. (Statements that call a program as a function or with the CALL command are compiled.)

You can use the PRGTRACE option to check which statements in a program have been compiled. When you set PRGTRACE to YES and run a program, each statement is recorded in the current outfile before it is executed. A compiled statement is identified with an equal sign.

(PRG= program-name) statement

An uncompiled statement is identified with a colon.

(PRG: program-name) statement

You can use the COMPILE command to compile a model. When you do not use the COMPILE command before you run the model, Oracle OLAP automatically compiles it before solving it. You can use the OBJ function with the ISCOMPILED choice to test whether a model is compiled.

SHOW OBJ(ISCOMPILED 'myModel')

When you compile a model, Oracle OLAP checks for problems that are unique to models. You receive an error message when any of the following occurs:

• The model contains any statements other than DIMENSION (in models), INCLUDE, and assignment (SET) statements.

• The model contains both a DIMENSION command and an INCLUDE command.

• A DIMENSION or INCLUDE command is placed after the first equation in the model.

• The dimension values in a single dimension-based equation refer to two or more different dimensions.

• An equation refers to a name that the compiler cannot identify as an object in any attached analytic workspace. When this error occurs, it may be because an equation refers to the value of a dimension, but you have neglected to include the dimension in a DIMENSION command. In addition, a DIMENSION command may appear to be missing when you are compiling a model that includes another model and the other model fails to compile. When a root model (the innermost model in a hierarchy of included models) fails to compile, the parent model is unable to inherit any DIMENSION commands from the root model. In this case the compiler may report an error in the parent model when the source of the error is actually in the root model. See INCLUDE for additional information.

The model compiler examines each name in an equation to determine the analytic workspace object to which the name refers. Since you can use a variable and a dimension value in exactly the same way in a model equation (basing calculations on it or assigning results to it), a name might be the name of a variable or it might be a value of any dimension listed in a DIMENSION (in models) statement.

To resolve each name reference, the compiler searches through the dimensions listed in explicit or inherited DIMENSION statements, in the order they are listed, to determine whether the name matches a dimension value of a listed dimension. The search concludes as soon as a match is found.

Therefore, when two or more listed dimensions have a dimension value with the same name, the compiler assumes that the value belongs to the dimension named earliest in a DIMENSION statement.

Similarly, the model compiler might misinterpret the dimension to which a literal integer value belongs. For example, the model compiler will assume that the literal value '200' belongs to the first dimension that contains either a value at position 200 or the literal dimension value 200.

To avoid an incorrect identification, you can specify the desired dimension and enclose the value in parentheses and single quotes. See "Formatting Ambiguous Dimension Values".

When the compiler finds that a name is not a value of any dimension specified in a DIMENSION statement, it assumes that the name is the name of an analytic workspace variable. When a variable with that name is not defined in any attached analytic workspace, an error occurs.

The model compiler determines the dimensions over which the statements will loop. When an equation assigns results to a variable, the compiler constructs code that loops over the dimensions (or bases of a composite) of the variable.

When you run a model that contains dimension-based equations, the solution variable that you specify can be dimensioned by more dimensions than are listed in DIMENSION (in models) statements.

When you specify the value of a model dimension as an argument to a user-defined program, the compiler recognizes a dependence introduced by this argument.

For example, an equation might use a program named weight that tests for certain conditions and then weights and returns the Taxes line item based on those conditions. In this example, a model equation might look like the following one.

Net.Income = Opr.Income - weight(Taxes)

The compiler correctly recognizes that Net.Income depends on Opr.Income and Taxes. However, when the weight program refers to any dimension values or variables that are not specified as program arguments, the compiler does not detect any hidden dependencies introduced by these calculations.

The model compiler analyzes dependencies between the equations in the model. A dependence exists when the expression on the right-hand side of the equal sign in one equation refers to the assignment target of another equation. When an equation indirectly depends on itself as the result of the dependencies among equations, a cyclic dependence exists between the equations.

The model compiler structures the model into blocks and orders the equations within blocks and the blocks themselves to reflect dependencies. When you run the model, it is solved one block at a time. The model compiler can produce three types of solution blocks:

• Simple Solution Blocks—Simple blocks are one of the three types of solution blocks that the model compiler can produce. Simple blocks include equations that are independent of each other and equations that have dependencies on each other that are non-cyclic.

  For example, when a block contains equations that solve for values A, B, and C, a non-cyclic dependence can be illustrated as A>B>C. The arrows indicate that A depends on B, and B depends on C.

• Step Solutions Blocks—Step blocks are one of the three types of solution blocks that the model compiler can produce. Step blocks include equations that have a cyclic dependence that is a one-way dimensional dependence. A dimensional dependence occurs when the data for the current dimension value depends on data from previous or later dimension values. The dimensional dependence is one-way when the data depends on previous values only or later values only, but not both.

  Dimensional dependence typically occurs over a time dimension. For example, it is common for a line item value to depend on the value of the same line item or a different line item in a previous time period. When a block contains equations that solve for values A and B, a one-way dimensional dependence can be illustrated as A>B>LAG(A). The arrows indicate that A depends on B, and B depends on the value of A from a previous time period.

• Simultaneous Solution Blocks—Simultaneous blocks are one of the three types of solution blocks that the model compiler can produce.

  When a model contains a block of simultaneous equations, COMPILE gives you a warning message. In this case, you may want to check the settings of the options that control simultaneous solutions before you run the model. Table 17-1, "Model Options" lists these options.

  Simultaneous blocks include equations that have a cyclic dependence that is other than one-way dimensional. The cyclic dependence may involve no dimensional qualifiers at all, or it may be a two-way dimensional dependence.

  An example of a cyclic dependence that does not depend on any dimensional qualifiers can be illustrated as A>B>C>A. The arrows indicate that A depends on B, B depends on C, and C depends on A.

  An example of a cyclic dependence that is a two-way dimensional dependence can be illustrated as A>LEAD(B)>LAG(A). The arrows indicate that A depends on the value of B from a future period, while B depends on the value of A from a previous period.

The solution of a simultaneous block of equations is sensitive to the order of the equations. In general, you should rely on the model compiler to determine the optimal order for the equations. In some cases, however, you may be able to encourage convergence by placing the equations in a particular order.

To force the compiler to leave the simultaneous equations in each block in the order in which you place them, set the MODINPUTORDER option to YES before compiling the model. (MODINPUTORDER has no effect on the order of equations in simple blocks or step blocks.)

When dependence between equations is introduced through any of the following structures, a one-way dimensional dependence occurs:

• A one-way dimensional dependence can occur when you use a LAG or LEAD function and when the argument for the number of time periods is a number. (Otherwise, there may be a two-way dependence, involving both previous and future dimension values, and the compiler assumes that a simultaneous solution is required.) The following example illustrates the use of LAG.

  Opr.Income = Gross.Margin - (Marketing + Selling + R.D)
  Marketing = LAG(Opr.Income, 1, month)
  
  

• A one-way dimensional dependence also can occur when you use a MOVINGAVERAGE, MOVINGMAX, MOVINGMIN, or MOVINGTOTAL function, when that the start and stop arguments are nonzero numbers, and when both the start and top arguments are positive or both are negative. (Otherwise, two-way dimensional dependence is assumed.)

  Opr.Income = Gross.Margin - (Marketing + Selling + R.D)
  Marketing = MOVINGAVERAGE(Opr.Income, -4, -1, 1, month)
  

When dependence is introduced through any of the following structures, the model compiler assumes that two-way dimensional dependence occurs:

• A two-way dimensional dependence can occur when you use an aggregation function, such as AVERAGE, TOTAL, ANY, or COUNT.

  Opr.Income = Gross.Margin -
     (TOTAL(Marketing + Selling + R.D))
  Marketing = LAG(Opr.Income, 1, month)
  

• A two-way dimensional dependence can occur when you use a time-series function that requires a time-period argument, such as CUMSUM or LAG (except for the specific functions and conditions described in "One-Way Dimensional Dependence".

• A two-way dimensional dependence also can occur when you use a financial function, such as DEPRSL or NPV.

  A cyclic dependence across a time dimension that you introduce through a loan or depreciation function may cause unexpected results. The loan functions include FINTSCHED, FPMTSCHED, VINTSCHED, and VPMTSCHED. The depreciation functions include DEPRDECL, DEPRDECLSW, DEPRSL, and DEPRSOYD.

After compiling a model, you can use the following tools to obtain information about the results of the analysis performed by the compiler:

• The MODEL.COMPRPT program produces a report that shows how model equations are grouped into blocks. For step blocks and for simultaneous blocks with a cross-dimensional dependence, the report lists the dimensions involved in the dependence.

• The MODEL.DEPRT program produces a report that lists the variables and dimension values on which each model equation depends. When a dependence is dimensional, the report gives the name of the dimension.

• The INFO function lets you obtain specific items of information about the structure of the model.

When you compile a compilable object that uses objects in another analytic workspace, the second analytic workspace must be attached to your current Oracle OLAP session. You can then run the compilable object with that analytic workspace or another analytic workspace with objects of the same name and type attached. Oracle OLAP checks that the objects have the same name, type (variable, dimension, and so on), data type (INTEGER, TEXT, and so on), and dimensions as the objects used to compile the compilable object.

When you have more than one active analytic workspace, do not have objects of the same name in both analytic workspaces. For example, when you have an analytic workspace of programs and two analytic workspaces with data about the products TEA and COFFEE, both product analytic workspaces can have a MONTH dimension and the programs can refer to MONTH. However, during your session, attach only one product analytic workspace at a time so that there is only one MONTH dimension.

Use the OBJ function with the ISCOMPILED keyword to obtain information about the compilation status of a compilable object.

To have Oracle OLAP display a message when it compiles an object automatically, you can set the COMPILEWARN option to YES.

You use the COMPILEMESSAGE option to specify whether you want Oracle OLAP to record non-fatal messages (those messages that indicate errors that do not prevent a program from compiling) during execution of the COMPILE command.

In order for code to compile, all variables referenced in a program (with the exception of variables in lines containing ampersand substitution) must be loaded into memory. This means Oracle OLAP reads the definition of every variable you use and stores it in a portion of available memory that is dedicated for storing object definitions. When the compilation tries to bind a large variable, this may use a large amount of memory and create a large EXPTEMP file. When the compilation tries to bind a large number of large variables, it may fail and Oracle OLAP will record an error message such as 'Insufficient Main Memory'. See LOAD for more information about loading an object's definition into memory.

Compiling the aggmap object is important for aggregation performed at run-time using the AGGREGATE function. Unless the compiled version of the aggmap has been saved, the aggmap is recompiled by each session that uses it.

There are two ways you can compile an aggmap objects:

• Issue a COMPILE statement.

  A COMPILE statement is the only way to compile an aggmap object that will be used by an AGGREGATE function. Explicitly compiling an aggmap is also useful for finding syntax errors in the aggmap before attempting to use it to generate data. The following statement compiles the sales.agg aggmap.

  COMPILE gpct.aggmap
  
  

• When you aggregate the data using an AGGREGATE command, include the FUNCDATA phrase in the statement.

  When you use the FUNCDATA phrase in an AGGREGATE command, Oracle OLAP compiles the aggmap before it aggregates the data. For example, this statement compiles and precalculates the aggregate data.

  AGGREGATE sales USING gpct.aggmap FUNCDATA
  

  
  

  Important: When some of the data is calculated on the fly, then you must compile and save the aggmap after executing the AGGREGATE command.

  
  

Examples

COMPILE myprog

LIMIT motnh TO LAST 6

ERROR: (MXMSERR00) Analytic workspace object MOTNH does not exist.
In DEMO!MYPROG PROGRAM:
limit month to last 6

DEFINE salesrpt PROGRAM
PROGRAM
ROW WIDTH 80 CENTER Monthly Report
BLANK 2
ROWW 'Total Sales' TOTAL(sales)
END

COMPILE salesrpt

ERROR: You provided extra input starting at 'REPORT'.
In SALESRPT PROGRAM:
ROW WIDTH 80 CENTER Monthly Report
ERROR: ROWW is not a command.
In SALESRPT PROGRAM:
roww 'Total Sales' TOTAL(sales)