10 OLAP DML Commands: H-Z

This chapter provides reference topics for the second set (in alphabetical order) of the OLAP DML commands. There is one topic for each of the OLAP DML commands that begins with the letters H-Z, beginning with HEADING.

Alphabetical and categorical listings of the OLAP DML commands and reference topics for the remaining OLAP DML commands appear in OLAP DML Commands: A-G.

For other OLAP DML reference topics, see OLAP DML Properties, OLAP DML Options, OLAP DML Functions: A - K, and OLAP DML Functions: L - Z.

Tip:

Many OLAP DML statements can be coded as a 3-character abbreviation that consists of the first letter of the statement plus the next two consonants.

10.1 HEADING

The HEADING command produces titles and column headings for a report. The heading output is sent to the current outfile. The form of the HEADING command is the same as that of the ROW command. When you use HEADING, however, Oracle OLAP does not add any numeric values from the heading to column subtotals or grand totals.

Frequently, HEADING statements are used in a PAGEPRG program to produce titles or column headings on each page of a report.

Tip:

When you know ahead of time that you do not need the subtotaling capability of the ROW command, use the HEADING command instead of ROW to produce the lines of your report can provide a time savings, because, in this case, Oracle OLAP does not keep track of subtotals.

Syntax

HEADING [attribs] {expression1|SKIP}, [attribs] {expressionN|SKIP}

Parameters

attribs

The attributes that specify the format for each column. (See the ROW command for a list and detailed explanation of the available attributes.)

expression

The text to be used as a column heading. To use literal text for a column heading, enclose the text in single quotes. (See the ROW command for more information on using expressions, attributes, and ACROSS groups to produce columns.)

SKIP

Used instead of an expression to indicate that the column is to be left blank.

Usage Notes

The notes for the ROW command also apply to the HEADING command (except for the note on row and column arithmetic in ROW).

Creating Titles Using Heading

To create a title or subtitle in a report, use HEADING to produce a single "column" with a width equal to the setting of the LSIZE option. You can then center your text within this "column" to produce a centered title.

Maximum Heading Width

The maximum width of any line in a report, including a heading line, is 4,000 characters.

Examples

Example 10-1 Producing Column Headings

In a report, you want to have headings for your columns. You can use a HEADING statement such as the following in your program.

HEADING UNDER '-' CENTER <WIDTH 15 'Product' -
   ACROSS district FIRST 3: district>

This statement produces the following result.

    Product      Atlanta     Boston    Chicago
--------------- ---------- ---------- ----------

10.2 HIDE

The HIDE command hides the text of a program, so that you cannot display it using a DESCRIBE, EDIT, or OBJ statement. You can perform all other actions on the program, including executing, compiling, renaming, or exporting.

When you hide a program, you supply a seed expression, which Oracle OLAP uses to encode the program text. You can use this seed expression later using an UNHIDE statement to make the text visible.

Note:

This command performs simple encoding. For information on using secure encryption and other security features in Oracle, see About Oracle Database Security in Oracle Database Security Guide.

Syntax

HIDE prog-name seed-exp

Parameters

prog-name

The name of the program whose text you want to hide. Do not enclose the program name in quotes.

seed-exp

A single-line text expression to be used as a seed value when encoding of the program text. Do not specify NA for this value.

Keep a record of this seed expression, so that you can use it later with an UNHIDE statement. The seed expression you specify in the UNHIDE statement must be byte-for-byte the same value as you used in this HIDE statement. Also, the seed expression is case-sensitive, so record uppercase and lowercase characters carefully.

Usage Notes

Exporting and Importing with the Seed

When you export and import a hidden program, the text remains hidden in the analytic workspace in which it is imported. It retains the same seed expression for use with the UNHIDE command.

Examples

Example 10-2 Hiding Program Text

The following example hides the text of a program called sales_rpt.

HIDE sales_rpt 'Crystal' 

10.3 HIERDEPTH

For each hierarchy of relation, the HIERDEPTH command calculates the depth of that hierarchy from the top of all of the hierarchies and stores that value in a previously-defined relation sometimes called the depth relation.

Syntax

HIERDEPTH parent-rel [(qdr-list)] INTO depth-rel [INHIERARCHY inh-valueset ]

Parameters

parent-rel

A child-parent self-relation for the hierarchical dimension. See "Parentrel Relation" for more information.

qdr-list

A list of QDRs that limits the values of parentrel. Specify the QDRs as described in "Syntax of a Qualified Data Reference". When you do not specify a value for qdrlist, HIERHEIGHT uses the values of parentrel that are in current status.

depth-rel

A previously -defined relation that the HIERDEPTH command populates when it executes. This relation can have multiple dimensions; however, it must be dimensioned by the dimensions of parentrel and one other NUMBER dimension that represents the depth of the hierarchical dimension.

For example, assuming that parent-rel has two dimensions, dim1 and dim2, the following lines of code define a NUMBER dimension named numdim with 3 values and, then, define a depth relation named depthrel which is dimensioned by dim1 and dim2 that has as its values the values of numdim.

DEFINE numdim dimension NUMBER(3)
DEFINE depthrel RELATION numdim <dim1 dim2>
inh-valueset

The name of a valueset object whose values are the hierarchical dimension values to be considered when creating grouping ids. Values not included in the valueset are ignored. See "Inhier Valueset or Variable" for more information.

Examples

Example 10-3 Creating and Populating a Depth Relation for Hierarchies

Assume that your analytic workspace contains the geog, geog_hierlist, and geog_parentrel objects described in Example 9-145. You can create a depth relation for the hierarchies represented by these objects by issuing the following DML code.

"   Define the number dimension for the depthrel
DEFINE numdepth DIMENSION NUMBER (3)
"   Define the depth relation
"   Populate the depth relation
HIERDEPTH geog_parentrel INTO depthrel
REPORT DOWN geog depthrel
 
               ------------------DEPTHREL-------------------
               ----------------GEOG_HIERLIST----------------
GEOG               Political_Geog           Sales_Geog
-------------- ---------------------- ----------------------
Boston         3                      3
Springfield    3                      3
Hartford       3                      3
Mansfield      3                      3
Montreal       3                      3
Walla Walla    3                      3
Portland       3                      3
Oakland        3                      3
San Diego      3                      3
MA             2                      2
CT             2                      2
WA             2                      2
CA             2                      2
Quebec         2                      2
East           0                      1
West           0                      1
All Regions    0                      0
USA            1                      0
Canada         1                      0
All Countries  0                      0

10.4 HIERHEIGHT command

The HIERHEIGHT command populates a previously-defined relation with the values of a specified hierarchical dimension by level. Typically, you use the HIERHEIGHT command when you are preparing an analytic workspace for access using the OLAP_TABLE function.

To retrieve the value of a node (by level) for the value of a hierarchical dimension, use the HIERHEIGHT.

See Also:

See "Familyrel Relation"

Syntax

HIERHEIGHT parentrelation [(qdrlist)] INTO{familyrel-        [USING level-relation | A | D] [INHIERARCHY { inh-variable | inh-valueset}]

Parameters

parentrel

A child-parent self-relation for the hierarchical dimension. See "Parentrel Relation" for more information.

qdrlist

A list of QDRs that limits the values of parentrel. Specify the QDRs as described in "Syntax of a Qualified Data Reference". When you do not specify a value for qdrlist, HIERHEIGHT uses the values of parentrel that are in current status.

familyrel

A previously -defined relation that the HIERHEIGHT command populates when it executes. This relation can have multiple dimensions; however, it must be dimensioned by the dimensions of parentrel and one other dimension that represents the levels of the hierarchical dimension. The actual construct of the dimension that represents the levels of the hierarchical dimension varies depending on whether or not the HIERHEIGHT statement includes the USING phrase:

  • When the statement includes the USING phrase, the dimension that represents the levels of the hierarchical dimension is a dimension that contains the names of the levels.

  • When the statement does not include the USING phrase, the dimension that represents the levels of the hierarchical dimension is an INTEGER dimension that has as values the depth of the level.

When familyrel is populated before a HIERHEIGHT statement executes, the HIERHEIGHT statement depopulates it before computing new values.

USING levelrel

Specifies that the relation is populated using the specified levelrel. See "Levelrel Relation" for more information.

A

Specifies that the relation is populated in ascending order.

D

(Default) Specifies that the relation is populated in descending order.

inh-variable

A BOOLEAN variable that is dimensioned by the hierarchical dimension and, when the hierarchical dimension is a multi-hierarchical dimension, by a dimension that is the names of the hierarchies. The values of the variable are TRUE when the dimension value is in a hierarchy and FALSE when it is not.

inh-valueset

The name of a valueset object whose values are the hierarchical dimension values to be considered when creating grouping ids. Values not included in the valueset are ignored. See "Inhier Valueset or Variable" for more information.

Usage Notes

HIERHEIGHT with the OLAP_TABLE Function

Typically, you use a HIERHEIGHT statement when you are preparing an analytic workspace for access using the OLAP_TABLE function.

Examples

Example 10-4 Creating a Relational Representation of a Geography Hierarchy

Assume that there is an analytic workspace named myaw that has a Geography hierarchy defined with analytic objects with the following definitions.

DEFINE geog.hierdim DIMENSION TEXT
LD Hierarchy names for Geography hierarchies

DEFINE geog.leveldim DIMENSION TEXT
LD List of levels for GEOGRAPHY hierarchies

DEFINE geography DIMENSION TEXT WIDTH 12
LD Values for the Geography hierarchies

DEFINE geog.levelrel RELATION geog.leveldim <geography geog.hierdim>
LD Level of each value in the Geography hierarchies

DEFINE geog.parent RELATION geography <geography geog.hierdim>
LD Child-parent relation for the Geography hierarchies

DEFINE geog.familyrel RELATION geography <geography geog.leveldim geog.hierdim>
LD Geography values by level and hierarchy

These objects have the following structures.

GEOGRAPHY
------------------
World
Americas
Canada
USA
Toronto
Montreal
Boston
LosAngeles

GEOG.HIERDIM
------------------
Standard
Consolidated

GEOG.LEVELDIM
------------------
World
Continent
Country
City
Consolidated
Continent
Consolidated
Country

                   ------------GEOG.LEVELREL------------
                   ------------GEOG.HIERDIM-------------
GEOGRAPHY               Standard         Consolidated
------------------ ------------------ ------------------
World              World              NA
Americas           Continent          Consolidated
                                      Continent
Canada             Country            Consolidated
                                      Country
USA                Country            Consolidated
                                      Country
Toronto            City               NA
Montreal           City               NA
Boston             City               NA
LosAngeles         City               NA

                   -------------GEOG.PARENT-------------
                   ------------GEOG.HIERDIM-------------
GEOGRAPHY               Standard         Consolidated
------------------ ------------------ ------------------
World              NA                 NA
Americas           World              NA
Canada             Americas           Americas
USA                Americas           Americas
Toronto            Canada             NA
Montreal           Canada             NA
Boston             USA                NA
LosAngeles         USA                NA

To create a family relation of the Geography hierarchy you define an analytic workspace object with the following definition.

DEFINE geog.familyrel RELATION geography <geography geog.leveldim geog.hierdim>
LD Geography values by level and hierarchy

Then you use a HIERHEIGHT statement as illustrated in the following statement to populate the object.

HIERHEIGHT geog.parent INTO geog.familyrel USING geog.levelrel

By issuing a REPORT statement, you can display the relational representations of both the Standard and Consolidated hierarchies of the geography dimension.

REPORT DOWN geography geog.familyrel
GEOG.HIERDIM: Standard
             -------------------------------GEOG.FAMILYREL--------------------------------
             --------------------------------GEOG.LEVELDIM--------------------------------
                                                                 Consolidated Consolidated
GEOGRAPHY       World      Continent     Country        City      Continent     Country
------------ ------------ ------------ ------------ ------------ ------------ ------------
World        World        NA           NA           NA           NA           NA
Americas     World        Americas     NA           NA           NA           NA
Canada       World        Americas     Canada       NA           NA           NA
USA          World        Americas     USA          NA           NA           NA
Toronto      World        Americas     Canada       Toronto      NA           NA
Montreal     World        Americas     Canada       Montreal     NA           NA
Boston       World        Americas     USA          Boston       NA           NA
LosAngeles   World        Americas     USA          LosAngeles   NA           NA

GEOG.HIERDIM: Consolidated
             -------------------------------GEOG.FAMILYREL--------------------------------
             --------------------------------GEOG.LEVELDIM--------------------------------
                                                                 Consolidated Consolidated
GEOGRAPHY       World      Continent     Country        City      Continent     Country
------------ ------------ ------------ ------------ ------------ ------------ ------------
World        NA           NA           NA           NA           NA           NA
Americas     NA           NA           NA           NA           Americas     NA
Canada       NA           NA           NA           NA           Americas     Canada
USA          NA           NA           NA           NA           Americas     USA
Toronto      NA           NA           NA           NA           NA           NA
Montreal     NA           NA           NA           NA           NA           NA
Boston       NA           NA           NA           NA           NA           NA
LosAngeles   NA           NA           NA           NA           NA           NA

10.5 IF...THEN...ELSE command

Within an OLAP DML program, the IF...THEN...ELSE command executes one or more statements in a program when a specified condition is met. Optionally, it also executes an alternative statement or group of statements when the condition is not met.

Note:

You can also use IF as a conditional operator in an expression. See "IF...THEN...ELSE expression"

Syntax

IF boolean-expression    THEN statement1    [ELSE statement2]

Parameters

boolean-expression

Any valid Boolean expression that returns either TRUE or FALSE.

THEN statement1

Oracle OLAP executes the statement1 argument when the Boolean expression is TRUE. The statement1 must be on the same line as THEN.

ELSE statement2

Oracle OLAP executes the statement2 argument when the Boolean expression is FALSE. The statement2 must be on the same line as ELSE. When you omit the ELSE phrase, execution continues with the statement after the whole IF...THEN... statement in the program.

Usage Notes

IF with DO

You can use an IF statement for conditional execution of two or more statements by following the THEN or ELSE (or both) keywords with a DO ... DOEND sequence. See Example 10-5.

Single or Multiple Lines

When IF is used as an expression, the THEN and ELSE keywords must be on the same line as IF. When IF is used as a command, THEN and ELSE must be on separate lines.

Examples

Example 10-5 Using IF...THEN...ELSE

The following lines from a program illustrate the use of IF...THEN...ELSE.... When the Boolean expression ANY(DOLLARS LT 200000) is TRUE, the statements following THEN (statement group 1) are executed. When the expression is FALSE, the statements following ELSE (statement group 2) are executed instead.

IF ANY(DOLLARS LT 200000)
THEN DO
  ... " (statement group 1)
  DOEND
ELSE DO
  ... "(statement group 2)
   DOEND

Example 10-6 Using IF as a Conditional Operator

In a program that produces a report, you would like to report a previous year's actual expenses or the current year's budget, depending on the year passed to the program as an argument. A conditional expression in a JOINCHARS function produces a heading with the word Actual or Budget. Another conditional expression selects the variable to report. The program would include the following lines.

ARGUMENT cur.year year
 
LIMIT month TO year cur.year
REPORT -
   HEADING JOINCHARS( 'Expenses: ' -
                        IF cur.year LT 'Yr95' -
                        THEN 'Actual FOR ' -
                        ELSE 'Budget FOR ', -
                       cur.year ) -
   IF cur.year LT 'Yr95' THEN actual ELSE budget

10.6 IMPORT

The IMPORT command transfers data to an analytic workspace from a text file, a spreadsheet, or another analytic workspace from an EIF file.

Because the syntax of the IMPORT command is different depending on where the data to be imported is located, separate topics are provided for different types of source files:

10.6.1 IMPORT (EIF)

You can use the IMPORT (from EIF) command to copy data and definitions into your Oracle OLAP analytic workspace from an EIF file. IMPORT also copies any dimensions of the imported data that do not already exist in your workspace, even when you do not specify them in the command.

Tip:

Several options that determine how EIF files are imported and exported. These options are listed in "EIF Options".

IMPORT (from EIF) is commonly used with EXPORT (EIF) to copy parts of one Oracle OLAP analytic workspace to another; you export objects from the source workspace to an EIF file and then import the objects from the EIF file into the target workspace. The source and target workspaces can reside on the same platform or on different platforms. When you transfer an EIF file between computers, you use a binary transfer to overcome file-format incompatibilities between platforms. The EIF file must have been created with the EIFVERSION set to a version that is less than or equal to the version number of the target workspace. Use EVERSION to verify the target version number.

You can also use IMPORT to store information in the EIFNAMES and EIFTYPES options.

Syntax

IMPORT import_item FROM EIF FILE file-id [INTO workspace] -    [MATCH [STATUS]|APPEND|REPLACE [DELETE]] [LIST [ONLY]] [DATA] -    [DFNS] [UPDATE] [NOPROP] [NASKIP] [NLS_CHARSET charset-exp] -    [API |  NOAPI]

where import_item is one of the following:

  • name [AS newname]
  • ALL

Parameters

name [AS newname]

The name of an analytic workspace object to be imported from an EIF file to an attached workspace. You cannot specify a qualified object name for the object, because the object is not yet in any workspace. You can list multiple names at a time. See the INTO workspace argument for information about where the object is imported.

AS newname can be used to rename any type of object being imported except dimensions.

When you have exported a multidimensional object as separate variables, list all the variable names. (See the SCATTER AS keyword in the EXPORT (EIF).)

ALL

(Default) Indicates that you want to import all the objects contained in the EIF file. See the INTO workspace argument for information about where the objects is imported.

INTO workspace

an analytic workspace name that identifies the attached workspace into which objects is imported. When the objects exist in the specified workspace, then their data is overwritten by the imported data. When the objects do not already exist, IMPORT creates them it in the specified workspace. IMPORT ignores identically named objects when they exist in other attached workspaces.

When you do not specify this argument, then Oracle OLAP does the following:

  • When you have not previously defined the objects being imported in an attached workspace, then IMPORT defines them automatically in the current workspace.

  • When the objects already exist in any attached workspace, then IMPORT overwrites the data they contain with the imported data.

FROM EIF FILE file-id

Identifies the file you want to import. File-id is a text expression that represents the name of the file. The name must be in a standard format for a file identifier.

MATCH [STATUS]

Indicates that the IMPORT command should bring in only the data associated with dimension values that match those already in the target workspace. For dimensions other than time dimensions, ensure that corresponding dimension values are spelled and capitalized identically in the EIF file and your target workspace when you want them to match; for example, Tents does not match TENTS. For time dimensions, Oracle OLAP identifies dimension values by the dates they represent rather than by the way they are displayed. Therefore, time dimension values in the EIF file automatically matches time dimension values in your workspace when they represent the same time periods. When you specify MATCH STATUS, IMPORT only imports data associated with the values included in the current status of that dimension. When the dimension is limited in the target workspace, Oracle OLAP ignores any data in the EIF file associated with the values excluded from the status.

APPEND

(Default) Indicates that the IMPORT command should bring in all the dimension values, along with associated data, regardless of whether or not the dimension values match those already present in the target workspace. APPEND adds those that do not match to those already present; it adds new values to the end of the list of dimension values. For time dimensions, APPEND also adds dimension values to fill in any gaps between the dimension values in your target workspace and the new ones.

REPLACE [DELETE]

Indicates that, for objects already defined in the workspace, IMPORT should keep the existing dimension values that match the dimension values in the EIF file. IMPORT deletes dimension values (and their data) that do not match dimension values in the EIF file. IMPORT replaces the associated data for the dimension values kept as part of the new dimension when the associated data variables are included in the EIF file. For text dimensions, the order of the dimension values in the EIF file is also adapted.

When you specify REPLACE DELETE, no matching takes place. Before importing a dimension, Oracle OLAP performs a MAINTAIN DELETE ALL, which discards all data associated with the existing dimension and the dimension values.

Note:

Be careful when using the REPLACE keyword. When you replace the values of a dimension, all variables and relations in the target workspace dimensioned by it are affected. When a variable or relation is not being imported at the same time, replacing the values of one of its dimensions could result in the loss of its data.

LIST
LIST ONLY

Produces a list of the definitions. For dimensions, the output lists the number of values in each dimension, as they are imported into the target workspace. For composites, the output lists the number of dimension value combinations. IMPORT also indicates the number of bytes read and the elapsed time every two minutes or, in any case, after the import procedure.

When you define a conjoint or composite that uses an index type other than the default, the IMPORT LIST command displays the index type. When you use the default index type (HASH for conjoints, BTREE for composites), that information is not displayed.

EXPORT (EIF) sends the list to the current outfile. When you specify LIST ONLY, you get only the listing without actually importing anything.

ONLY

Causes Oracle OLAP to place the correct values in the EIFNAMES and EIFTYPES options without actually importing them. However, Oracle OLAP does not produce a full listing of the object definitions. To produce the list, specify the LIST keyword before the ONLY keyword.

DATA

Indicates that, for objects that already exist in the target workspace, IMPORT should update only the data associated with those objects. For formulas that already exist, IMPORT updates their EQ expressions. Objects that IMPORT creates in the target workspace are created with their full definitions and any associated data. You can specify both DATA and DFNS, but when neither is specified, the default is DATA.

DFNS

Indicates that, for objects that already exist in the target workspace, IMPORT should just update definitions and leave data unchanged. The components of the definition affected by IMPORT DFNS are: LD Command, VNF, and PROPERTY. Objects that IMPORT creates in the target workspace still get their data. You can specify both DATA and DFNS, but when neither is specified, the default is DATA.

UPDATE

Indicates that IMPORT should execute an UPDATE statement after importing each object which can be useful when importing large EIF files that would otherwise cause Oracle OLAP to run out of memory. To control the frequency of updates, use the EIFUPDBYTES option.

NOPROP

Prevents any properties that you have assigned to each object from being read from the EIF file.

NASKIP

Specifies that composite tuples (indexes) that contain only NA data should not be imported into the target workspace. This argument has no effect on tuples that already exist in the workspace.

NLS_CHARSET charset-exp

Specifies the character set that Oracle OLAP uses when importing text data from the file specified by file-id. Normally, an EIF file contains its own specification of its character set, so that this argument is not needed. However, when the EIF file specifies the character set incorrectly or is missing the character set specification, then you must use this argument to specify the character set correctly.

For information about the character sets that you can specify, see Choosing a Character Set in Oracle Database Globalization Support Guide.

This argument must be the last one specified. When this argument is omitted, and Oracle OLAP cannot determine the character set from the EIF file itself, then Oracle OLAP imports the data using the database character set, which is recorded in the NLS_LANG option.

API

(Default) When the EIF file was created using an EXPORT (EIF) command with the API keyword, import any cube metadata defined for the specified items.

Note:

Oracle OLAP automatically executes an UPDATE and a COMMIT after executing this type of import.

NOAPI

Even if the EIF file was created using an EXPORT (EIF) command with the API keyword, do not import any cube metadata defined for the specified items. When you specify this keyword, Oracle OLAP does not automatically execute an UPDATE and a COMMIT after executing the IMPORT command.

Usage Notes

Separate IMPORT Statements

The MATCH, APPEND, REPLACE, DATA, and DFNS arguments you specify affect all the objects you name to be imported. When you want to treat different objects in different ways, use separate IMPORT statements.

Importing and Exporting Hidden Programs

Importing Relations

When you are importing a relation, IMPORT also brings in the definition and values for the related dimension as well.

Importing Concat Dimensions

When you import a concat dimension into an analytic workspace and the concat dimension and none of its component dimensions already exist in the analytic workspace, then Oracle OLAP imports the concat dimension, its component dimensions, and the definitions of all of the dimensions.

When you import a concat dimension that does not already exist but one or more of its component dimensions already exist in the analytic workspace, then Oracle OLAP imports the concat dimension and any new component dimensions and their definitions. For the component dimensions that already exist in the analytic workspace, Oracle OLAP imports the component dimensions as it does other dimensions, obeying any MATCH, APPEND, REPLACE specifications in the IMPORT statement.

When you import a concat dimension with a name and a definition of a concat dimension that already exists in the analytic workspace, then Oracle OLAP imports the concat dimension as it does other dimension.

When you import a concat dimension with the same name as one that already exists in the analytic workspace but the definition of the imported concat dimension is different than the definition of the existing concat dimension, then the definition of the existing concat dimension does not change and the definitions of the component dimensions of the existing concat dimension do not change. Only the component dimensions of the imported concat dimension that are also component dimensions of the existing concat dimension are imported. When the imported concat dimension does not share any component dimensions with the existing concat dimension, an error condition occurs. When you are importing any objects that are dimensioned by the concat dimension, then Oracle OLAP imports only the values of the object that correspond to the values of the imported dimensions.

Importing and Exporting Dimension Surrogates

You can import or export a dimension surrogate to or from an Express Interchange File (EIF). In those operations, a dimension surrogate behaves like a variable that is dimensioned by the dimension of the surrogate. In an EXPORT operation, the dimension for which the surrogate is defined is also exported. In an IMPORT operation, the dimension for which the surrogate is defined is imported but you can use the MATCH, STATUS, DATA, DFNS, APPEND, and REPLACE keywords to affect which values are imported.

Importing a dimension surrogates also imports the definition and values for the dimension for which it is a surrogate. When a dimension with the same definition already exists in the current analytic workspace, then the effects of the IMPORT keywords such as MATCH, APPEND, REPLACE, DATA, and DFNS are the same for the surrogate as they would be for a variable dimensioned by the dimension. When the name and definition of the imported surrogate is the same as a dimension surrogate that already exists in the current analytic workspace and when the imported surrogate has a value that is identical to a value in the existing surrogate, an error condition occurs.

You can import an INTEGER dimension surrogate when no object of the same name exists in the current analytic workspace or when you use the DFNS keyword. Importing an INTEGER dimension surrogate affects existing INTEGER dimension surrogates when the implicit importing of the dimension of the imported surrogate changes the values of the existing dimension.

APPEND Versus REPLACE

When you are importing an INTEGER dimension that already exists in your target workspace, the following considerations apply.

  • When the imported INTEGER dimension is larger than the existing one, APPEND and REPLACE have the same effect. The dimension ends up with the number of values in the larger, imported dimension.

  • When the imported INTEGER dimension is smaller, REPLACE drops the appropriate dimension values from the end of the dimension, along with any associated data, while APPEND leaves the existing dimension values alone.

INTEGER and SHORTINTEGER Data Types

The IMPORT command translates between the INTEGER and SHORTINTEGER data types. When you are importing a variable with one of these data types from an EIF file and it already exists in your workspace as the other type, Oracle OLAP converts the data automatically. The maximum SHORTINTEGER value is 32,767 and the minimum is -32,767. When you import an INTEGER value that exceeds these limits into a SHORTINTEGER variable, the result is NA.

TEXT and ID Data Types

When the EIF file you are importing contains ID data that you want to import into TEXT dimensions, variables, relations, or valuesets, Oracle OLAP automatically converts the ID data to text during the import process.

Existing Programs and Models

When you are importing a program or model that already exists in your workspace, you must specify DFNS. A program or a model is a definition only; it does not have any data. The default option DATA does not import the source code when it already exists.

When you define a program, you may specify a data type or a dimension name, which is used when the program is called as a function. When you specify a data type, it determines the data type of the return value. When you specify a dimension name, the return value is a single value of that dimension. When you import an existing program, the data type or the dimension in the imported program definition and the existing program definition must match. Otherwise, Oracle OLAP produces an error message.

PERMIT Statements

The PERMIT statements associated with an object are imported with the object definition. You can see them when you describe the object. However, permission conditions are not evaluated when the object is imported.

When an object with the same name already exists in the target workspace and you specify the DFNS keyword, the PERMIT statements for the object are updated. However, you must execute a PERMITRESET to put the new permission into effect. When an object with the same name already exists in the target workspace and you do not specify the DFNS keyword, the PERMIT statements for the object are not updated. When there is no pre-existing object in the target workspace, and you import with or without the DFNS keyword, the PERMIT statements for the object are updated, but you must execute a PERMITRESET to put the new permission into effect. (See the PERMIT command.)

When you export and import an entire workspace, then update, detach, and reattach the workspace, Oracle OLAP ensures that all the permissions that were in effect before exporting are in place in the target workspace.

Reducing Workspace Size

You can use IMPORT with an EXPORT statement to compact an entire workspace at once. To do this, first export the workspace and then import it under a different name. You can then delete the old workspace and rename the new one with the original name.

Preserving Conjoint Type

When you export a HASH, BTREE, or NOHASH conjoint dimension to an EIF file, the conjoint type is exported along with the definition in the EIF file. When you then import the conjoint dimension into an analytic workspace, Oracle OLAP preserves the conjoint type when you import into a new dimension or a dimension already using that conjoint type. When you import the dimension into an existing dimension that does not use the same conjoint type, Oracle OLAP does not preserve the original conjoint type that was saved in the EIF file.

EIFBYTES, EIFNAMES, and EIFTYPES

You can use the EIFBYTES option to learn the number of bytes read or written by the most recent IMPORT (EIF File) statement. You can use the EIFNAMES option to get a list of the names of all the objects imported by the most recent IMPORT statement and use the EIFTYPES option to learn the types of objects in that list.

The following format causes IMPORT to store information about the specified objects into the EIFNAMES and EIFTYPES options without actually importing the objects. IMPORT places a list of the object names specified by the IMPORT command in the EIFNAMES option. IMPORT also places a list of the type of each object listed in EIFNAMES into the EIFTYPES option. You may use the LIST keyword to send to the current outfile a full listing of the object definitions.

IMPORT name FROM EIF FILE file-id [LIST] ONLY

For more information, see the entries for EIFBYTES, EIFNAMES, and EIFTYPES options.

Importing Unnamed Composites

When you define variables or other objects with the SPARSE keyword in the dimension list, Oracle OLAP creates an unnamed composite that corresponds to the SPARSE dimension list. When you export or import an object with the unnamed composite in its definition, the composite is automatically exported or imported with the object. Because the unnamed composite is not a regular workspace object, you cannot import or export it independently.

Variable Segments Specified with SEGWIDTH

When you use a CHGDFN statement with the SEGWIDTH keyword to specify the length of variable segments, segment information cannot be exported and imported automatically. You can save your SEGWIDTH settings by exporting the entire workspace, creating a new workspace, importing only the workspace objects into the new workspace, specifying segmentation, and then importing the variable data into the new workspace.

Importing TEXT and NTEXT Values

You can export and import TEXT and NTEXT values. Both data types can be exported to a single EIF file.

  • Exported TEXT values are stored in the EIF file using the character set specified for the file in the EXPORT (EIF).

  • Exported NTEXT values are stored in the EIF file as NTEXT (UTF8 Unicode).

  • NTEXT values imported into TEXT objects are converted into the database character set which can result in data loss when the NTEXT values cannot be represented in the database character set.

  • TEXT values imported into NTEXT objects are converted into the NTEXT (UTF8 Unicode) character set.

Examples

Example 10-7 Importing Dimensions from an EIF File

This example shows how to import the contents and dimensions of two variables into the current Oracle OLAP workspace from a disk file called finance.eif in the current directory object.

IMPORT actual budget FROM EIF FILE 'finance.eif'

Example 10-8 IIMPORTING a Concat Dimension

This example shows the result of importing a concat dimension that has a definition that is different than a concat dimension that already exists in the current analytic workspace. Suppose that a DESCRIBE statement returns the following definitions for dimensions and variables in the current analytic workspace.

DEFINE city TEXT DIMENSION
DEFINE state TEXT DIMENSION
DEFINE country TEXT DIMENSION
DEFINE locality DIMENSION CONCAT (city, state)
DEFINE geog DIMENSION CONCAT (locality, country)
DEFINE sales INTEGER VARIABLE <geog>

The following statement reports the sales data.

REPORT sales

The preceding statement produces the following results.

GEOG                SALES
------------------- -----
<city: Boston>       1000
<city: Springfield>  2000
<state: Ma>          3000
<country: Usa>       4000

A DESCRIBE statement returns the following definitions for dimensions and variables in the diffconcat.eif file.

DEFINE CITY TEXT DIMENSION
DEFINE REGION TEXT DIMENSION
DEFINE COUNTRY TEXT DIMENSION
DEFINE GEOG DIMENSION CONCAT (CITY, REGION, COUNTRY)
DEFINE SALES INTEGER VARIABLE <GEOG>

The following statement reports the sales data for the dimension values in the analytic workspace from which you exported the concat dimension that is in the diffconcat.eif file.

REPORT sales

The preceding statement produces the following results.

GEOG               SALES
------------------ -----
<city: Boston>      1111
<city: Worcester>   2222
<region: East>      3333
<country: Usa>      4444

The following statement imports the sales variable from the diffconcat.eif file and implicitly imports the concat dimension geog. The APPEND keyword causes Oracle OLAP to add the value Worcester to the city dimension. After that, it imports new values for sales that correspond to <city: Boston>, <city: Worcester>, and <country: Usa>.

IMPORT sales FROM EIF FILE diffconcat.eif APPEND

After the import operation, reporting the SALES values produces the following results.

GEOG                SALES
------------------- -----
<city: Boston>       1111
<city: Springfield>  2000
<city: Worcester>    2222
<state: Ma>          3000
<country: Usa>       4444

10.6.2 IMPORT (text)

You can use the IMPORT (from text) command to copy data from a text file into an Oracle OLAP worksheet object. A worksheet's rows are similar to the lines of a text file.

IMPORT is commonly used to copy text files into an analytic workspace from other software products.

Typically, you use a FILEREAD statement for text files instead of IMPORT. FILEREAD is more efficient and does not require a worksheet object or separate handling of each column of data.

Syntax

IMPORT worksheetname FROM [TEXT|STRUCTURED|RULED [RULER ruler-exp] -    PRN FILE file-id [STOPAFTER n] [TEXTSTART schar] [TEXTEND echar] -   [DELIMITER dchar] [NLS_CHARSET charset-exp]

Parameters

worksheetname

A text expression that specifies the name of an Oracle OLAP worksheet object. When you have not previously defined worksheetname in your workspace, IMPORT defines it for you automatically, using the default dimensions WKSCOL and WKSROW. Any previous contents of worksheetname are overwritten. In any one IMPORT statement, you can import only one worksheetname from one text file.

FROM . . . PRN

Indicates that you want to import your Oracle OLAP worksheet from a text file.

TEXT

Imports a whole source file as-is into an Oracle OLAP worksheet on a line-by-line basis. The source file is copied into a single wide worksheet column with a data type of TEXT. The column is always column 1 of the worksheet. Each line in the source file is imported into a separate cell on a separate row in the first column, using as many rows as there are lines in the source file. A blank line in the source file produces a TEXT value with zero characters (a null) in the corresponding row of the worksheet's first column. (TEXT is the default.)

STRUCTURED

Imports a source file into a target worksheet on a cell-by-cell basis, automatically performing three functions:

  1. Each line of characters in the source file is copied into a single row of the target worksheet.

  2. Each group of characters on a line in the source file is copied into a separate TEXT cell on the target worksheet row. A group of characters is defined by two conditions: an uninterrupted (except by a decimal point) sequence of numbers, or enclosure in double quotes. Consequently, numbers containing commas to mark off thousands are split up into different cells unless the commas are first removed.

  3. Any non-numeric characters not enclosed in double quotes are ignored, except minus signs that immediately precede numbers and so are copied into the same TEXT cell along with the numbers. (Be sure there are no spaces between a minus sign and its number in the source file.)

A blank line in the source file results in an NA in the first cell of the corresponding worksheet row.

When your file format does not conform to the pattern described here, you can use the TEXTSTART, TEXTEND, and DELIMITER keywords. These arguments let you customize the delimiters IMPORT uses to identify the start and end of each field.

RULED

Indicates import of a file on a column-by-column basis into worksheet cells of various data types. Every line in the source file must follow the same pattern of data along its length as every other line in the file. You describe this data pattern to Oracle OLAP in the one-line ruler-exp using the RULER keyword. IMPORT loops over each line in the source file and copies its contents into a corresponding pattern of cells on a row of the target worksheet, one row for each line. As ruler-exp loops over successive lines in the source file, it adds row after row to the target worksheet, building vertical columns of similar cells as it goes along. Status messages are sent to the current outfile every 20 rows, starting with the message 20 rows processed.

When the source file contains records that follow several different patterns of character groups, use the less exacting options, STRUCTURED or TEXT, to import the data.

RULER ruler-exp

Used only with the RULED keyword to specify the data type, length, and repeat count of each character group in the record pattern of the source file. Ruler-exp consists of a list of character-group specifications. Each character-group specification must be separated by a comma (,), by backslash N (\n), or by a space( ). You do not have to include enough specifications to account for all the characters in the basic record pattern (or line pattern) of the source file; RULER steps to the next record as soon as it runs out of specifications on each line, regardless of how far it is from the end of the current record. Remember to enclose literal text in single quotes.

The specifications for groups of characters are of three types: T for TEXT, A for numeric (INTEGER or DECIMAL), and S for skip or ignore. The formats for these types are shown in the following table:

Table 10-1 Character-Group Specifications for IMPORT from Text

Format Description

[mm]Tnn

Specifies that Oracle OLAP should copy mm groups (default = 1) of nn characters (bytes) apiece as TEXT. Specifying a group (or groups) of 0 characters leaves an empty cell(s) in the corresponding position in the worksheet. Each group may consist of up to 498 characters. Trailing blanks are stripped.

[mm]Ann

Specifies that Oracle OLAP should copy mm groups (default = 1) of nn characters (bytes) apiece and try to convert each group to a number. When a character group cannot be converted to a number, it is copied into a TEXT cell and any trailing blanks are stripped. A valid number includes anything you can type for a GET(DECIMAL) function except NA.

Commas embedded in a number before a period (decimal point) are ignored. Consequently, multiple numbers separated only by commas or two numbers separated only by a single period are treated as parts of a single number (when you want the numbers treated separately, insert spaces between them in the source file). Leading dollar signs ($) and trailing percent signs (%) are ignored, and leading and trailing spaces are stripped. Multiple periods are treated as excess decimal points and ignored (to undo the effects of dotfill). For example,...17... is treated as though the field is 17.

Numbers preceded by a hyphen, or a hyphen and spaces, and numbers enclosed in parentheses, are treated as negative. Specifying a group (or groups) of 0 (zero) characters leaves an empty cell (or cells) in the corresponding position in the worksheet. Each group may consist of up to 4,000 characters.

[mm]Snn

Specifies that Oracle OLAP should skip or ignore mm groups of nn characters (bytes). The limit for nn is 32,767. (You would probably only use mm to expand this limit to handle a very long record.)

FILE file-id

Identifies the file you want to import. File-id is a text expression that represents the name of the file. The name must be in a standard format for a file identifier.

STOPAFTER n

Specifies that no more than n records should be read from the file. When STOPAFTER is omitted, Oracle OLAP reads the whole file.

TEXTSTART schar

The schar argument is a text expression that specifies a single character that you want Oracle OLAP to interpret as the start of a text field in a structured file. The default character is a double quote (").

TEXTEND echar

The echar argument is a text expression that specifies a single character that you want Oracle OLAP to interpret as the end of a text field in a structured file. The default character is a double quote (").

DELIMITER dchar

The dchar argument is a text expression that specifies a single character that you want Oracle OLAP to interpret as the general field delimiter in a structured file. Oracle OLAP uses the general field delimiter to identify both numeric and text fields. The default character is a comma (,).

NLS_CHARSET charset-exp

Specifies the character set that Oracle OLAP uses when importing text data from the file specified by file-id which allows Oracle OLAP to convert the data accurately from that character set. This argument must be the last one specified. When this argument is omitted, and Oracle OLAP cannot determine the character set from the file itself, then Oracle OLAP imports the data in the database character set, which is recorded in the NLS_LANG option.

Usage Notes

WKSROW and WKSCOL Dimensions

The WKSROW (the default worksheet row) dimension of an Oracle OLAP worksheet object corresponds to the lines of a text file. The WKSCOL (the default worksheet column) dimension of a worksheet divides each row into cells that can be used to separate data types when there are potentially several types on each line of the source file. WKSROW and WKSCOL are INTEGER dimensions with values of 1, 2, 3, and so on.

Minimum Worksheet Size

Oracle OLAP sets up a minimum-size worksheet that is 63 cells square, regardless of whether or not all the cells are used. When the source text file requires an Oracle OLAP worksheet larger than the minimum, IMPORT automatically increases the dimension values of WKSCOL and WKSROW as needed.

Importing Numbers

When importing a number from a text file, IMPORT gives it an INTEGER data type.

File Transfer to Another Computer

When the file you are importing originated on another computer, ensure that its character set is appropriate. When you transfer a text file to another computer, the communications program handling the transfer makes any necessary character translations; for example, from ASCII to EBCDIC. Set the parameters of the transfer program so that the resulting file is in the correct character set for the receiving computer.

Examples

Example 10-9 Importing Columns Without the RULER Keyword

Suppose you have a file named abctxt in your current directory. It has 10 five-digit groups of INTEGER values, followed by a group of 20 characters of text. To import this file into an Oracle OLAP worksheet called sheet1, use the following statement.

IMPORT sheet1 FROM RULED PRN FILE 'abctxt' ruler '10a5, t20'

The actual format for the file name must follow the conventions for your operating system.

Example 10-10 Importing Columns with the RULER Keyword

Suppose a file called mix has no line delimiters, with records containing 100 characters apiece. Each record has the character distribution illustrated in the following table.

Character Content

1 - 10

To be ignored

11 - 17

Decimal number

18 - 28

To be ignored

29 - 30

Two single-character code

31 - 35

Integer

36 - 100

To be ignored

To import this file into an Oracle OLAP worksheet called sheet2, use the following statement.

DEFINE sheet2 WORKSHEET temp
IMPORT sheet2 FROM RULED PRN FILE 'mix' RULER -
   's10, a7, s11, 2t1, a5' 

10.6.3 IMPORT (spreadsheet)

You can use the IMPORT (from spreadsheet) command to copy data (not formulas) from a spreadsheet file into an Oracle OLAP worksheet object. A worksheet's dimensions are similar to the columns and rows of a spreadsheet. IMPORT always copies an entire spreadsheet file at a time.

IMPORT is commonly used to copy data from other software products (for example, a Lotus spreadsheet) into an Oracle OLAP workspace.

Syntax

IMPORT worksheetname FROM source [INTO workspace]

where source is one of the following:

  • WKS FILE file-id [NLS_CHARSET charset-exp]
  • WK1 FILE file-id [NLS_CHARSET charset-exp]
  • WRK FILE file-id [NLS_CHARSET charset-exp]
  • WR1 FILE file-id [NLS_CHARSET charset-exp]
  • DIF FILE file-id [NLS_CHARSET charset-exp]
  • CSV FILE file-id [STOPAFTER n|DELIMITER dchar|NLS_CHARSET charset-exp]

Parameters

worksheetname

An Oracle OLAP worksheet object. In any one IMPORT statement, you can import only one worksheetname from one spreadsheet file. You can specify a qualified object name for the worksheet; however, when you specify the INTO worksheet argument, the target workspace specified must be identical. See the INTO workspace argument for information about where the worksheet object is imported.

FROM WKS
FROM WK1
FROM WRK
FROM WR1
FROM DIF

Indicates that you want to import your Oracle OLAP worksheet from a 1-2-3 file, Version 1 (WKS) or Version 2 (WK1); a Symphony file, Version 1.0 (WRK) or Version 1.1 (WR1); or a data interchange format file (DIF).

Oracle OLAP does not recognize numbers in E format (exponential notation) in DIF files.

INTO workspace

An analytic workspace name that identifies the attached workspace into which data is imported. When worksheetname exists in the specified workspace, then its data is overwritten by the imported data. When worksheetname does not already exist, IMPORT creates it in the specified workspace. IMPORT ignores an identically named worksheet when it exists in another attached workspace.

When you do not specify this argument, then Oracle OLAP does the following:

  • When you have not previously defined worksheetname in an attached workspace, IMPORT defines it automatically in the current workspace using the default dimensions WKSCOL and WKSROW.

  • When worksheetname already exists in any attached workspace, IMPORT overwrites the data it contains with the imported data.

FILE file-id

Identifies the file you want to import. The file-id argument is a text expression that represents the name of the file. The name must be in a standard format for a file identifier.

NLS_CHARSET charset-exp

Specifies the character set that Oracle OLAP uses when importing text data from the file specified by file-id which allows Oracle OLAP to convert the data accurately from that character set. This argument must be the last one specified. When this argument is omitted, and Oracle OLAP cannot determine the character set from the worksheet itself, then Oracle OLAP imports the data in the database character set, which is recorded in the NLS_LANG option.

Note:

The NTEXT data type is not supported in worksheets.

FROM CSV FILE file-id [STOPAFTER n] [DELIMITER dchar]

Indicates that you want to import from a source file on a cell-by-cell basis. See "CSV Import".

STOPAFTER n specifies that no more than n records should be read from the file. When STOPAFTER is omitted, Oracle OLAP reads the whole file.

DELIMITER dchar identifies the single character (dchar) that you want Oracle OLAP to interpret as the general field delimiter. The default value is comma.

Usage Notes

Default Dimensions of an Oracle OLAP worksheet object

The default dimensions of an Oracle OLAP worksheet are WKSCOL and WKSROW, which correspond to the columns and rows of a spreadsheet. WKSCOL and WKSROW are INTEGER dimensions with values of 1, 2, 3, and so on. When these dimensions already exist in an attached workspace but not in the current workspace, the IMPORT statement fails when it tries to create these dimensions. You can prevent this problem by first defining the worksheet with different dimensions. (See "Worksheet Dimensions" for more information.)

Addition of Cells when Needed

When the source spreadsheet contains more cells than are defined by the dimensions of the worksheet, IMPORT automatically adds dimension values to provide the required number of cells.

Empty and NA Cells

IMPORT merges the source file with the worksheet on a cell-by-cell basis. Cells from the source file that are not empty, even when they just contain NA, overwrite the contents of the corresponding cells in the worksheet; empty cells in the source file do not overwrite the worksheet; source-file cells beyond the end of the current worksheet are appended to it so that no data is discarded.

Numbers in DIF Files

When importing any number from DIF files, IMPORT gives it a DECIMAL data type.

CSV Import

The CSV import option automatically performs the following functions when importing from a source file into the cells of a worksheet:

  • Each line of characters in the source file is copied into a single row in the target worksheet.

  • Each group of characters on a line in the source file is copied into a separate TEXT cell in the target worksheet row, and groups are separated by the delimiter character.

When a group of characters is inside double quotation marks:

  • A delimiter character found in this group is treated as a literal.

  • When a double quotation mark occurs within this group, it must be followed by another double quotation mark.

  • A linefeed (\n) found within the group is ignored.

  • Spaces or tabs found before a starting quotation mark and after an end quotation mark are ignored.

Examples

Example 10-11 Importing a DIF File

This example shows how to import a spreadsheet in DIF format in a file called mortgage.dif. We define the worksheet first as a temporary object, which saves memory and storage space. IMPORT would define the worksheet sheet1 automatically when it did not already exist. When it had already been used in a previous IMPORT statement, any data in it would be overwritten with new data.

DEFINE sheet1 WORKSHEET TEMP
IMPORT sheet1 FROM DIF FILE 'mortgage.dif' 

10.7 INFILE

The INFILE command causes Oracle OLAP to read statement input from a specified file.

Syntax

INFILE {file-id|EOF} [NOW] [NLS_CHARSET charset-exp

Parameters

file-id

The name of a file from which to read input. File-id is a text expression that represents the name of the file. The name must be in a standard format for a file identifier.

The input file must contain only OLAP DML statements, along with appropriate responses to any prompts generated by the statements. Each statement or response must appear on a separate line in the file.

EOF

Terminates the reading of input from the current file and causes Oracle OLAP to resume reading input from the location from which the INFILE statement was executed. Use of INFILE EOF is optional. See "About the Input File" and "INFILE with Both NOW and EOF".

NOW

Indicates that Oracle OLAP should open the input file specified in the INFILE and read its statements immediately upon encountering the INFILE instead of waiting until the program containing the INFILE is finished which has the effect of nesting the input file's statements within the program. See "INFILE with Both NOW and EOF". This argument must be specified after file-id.

NLS_CHARSET charset-exp

Specifies the character set that Oracle OLAP uses when reading data from the file specified by file-id which allows Oracle OLAP to convert the data accurately into the current character set, as identified by the NLS_LANG option. This argument must be specified after file-id. When this argument is omitted, then Oracle OLAP handles the data in the file as having the database character set, which is recorded in the NLS_LANG option.

Usage Notes

About the Input File

When the end of the input file is reached, Oracle OLAP resumes reading input from the location from which the INFILE statement was executed (which could be another input file). You do not have to end the input file with the statement INFILE EOF.

INFILE ignores trailing blanks at the end of a line, or between the last text on a line and a continuation mark. INFILE also ignores blank lines.

When you use the NOW keyword and the input file ends with a continued statement, the statement is ignored. For example, if the file ends with "show - ," Oracle OLAP ignores a SHOW statement.

Using INFILE in a Program

When you include an INFILE statement without the NOW keyword in a program, the INFILE statement is not executed until the program has finished executing. In a nested program, it is not executed until all the programs involved have finished executing. Also, when several INFILE commands have been executed by a program, the input files are read in the opposite order from which they were specified.

For example, assume that program.a calls program.b which calls program.c, and each program contains two INFILE commands, one before and one after the call to the next program (as illustrated in the following code). In this case, the order of execution is: a2, b2, c2, c1, b1, a1.

program.a
   INFILE a1
   "
        program.b
           INFILE b1
           "
                program.c
                   INFILE c1
                   INFILE c2
           "
           INFILE b2
   "
   INFILE a2

When you include an INFILE statement in a program with the NOW keyword, the INFILE statement executes immediately. However, INFILE with the NOW keyword requires more space than usual on the program stack. To conserve stack space, use the NOW keyword only when it is necessary.

INFILE with NOW Outside of Programs

The NOW keyword is intended for use within programs, but you can use it at any time. When you use it when the input file would not ordinarily be deferred, the NOW keyword has no visible effect. However, because NOW requires extra stack space, do not use it in these situations.

INFILE with Both NOW and EOF

When you use both the NOW and EOF keywords, the NOW keyword is ignored.

Displaying Infiled Statements and Responses

When you want the statements from a disk file to be copied to a debugging file as they are executed, see the DBGOUTFILE command.

Examples

Example 10-12 Reading the Input File Immediately

The following line of code in a program causes the file called newdefs to be read in immediately.

INFILE 'newdefs' NOW 

10.8 LD

The LD command adds the description to the current object definition. The description consists of text that you specify to describe the object. You can assign a description to any type of definition.

Tip:

The current object definition is the definition of the object that has been most recently defined or considered during the current session. To make an object definition the current definition, use a CONSIDER statement.

Syntax

LD [text]

Parameters

text

The text of the description you want to assign to the definition. When text is omitted, any existing description for the current definition is deleted.

You can create a multiline description by using a hyphen as a continuation character. However, you cannot create a description with an initial blank line with an LD statement.

Examples

Example 10-13 Adding a Description to the Definition of a Variable

This example changes the description associated with the variable units. First, execute the CONSIDER statement to make units the current definition. Then use a LD statement to assign a new description. The units variable has the following definition.

DEFINE units VARIABLE INTEGER <month product district>
LD Actual Unit Shipments

The statements

CONSIDER units
ld Actual Unit Shipments for Each Division
DESCRIBE units

produce the following definition for units.

DEFINE units VARIABLE INTEGER <month product district>
LD Actual Unit Shipments for Each Division

10.9 LIMIT command

The LIMIT command sets the current status list of a dimension and its dimension surrogates, or assigns values to a valuesets the current status list of a dimension and its dimension surrogates, or assigns values to a valueset. You use LIMIT to restrict the data values you are working on by temporarily limiting the range of the dimensions of the data. Using LIMIT, you create a current status list for a dimension. The current status list of a dimension is an ordered list of currently accessible values for the dimension. Values that are in the current status list of a dimension are said to be "in status." For more information on dimension status and its importance when working with analytic workspace data, see "How to Specify the Set of Data that OLAP DML Operations Work Against".

Tip:

You set the current status list of one or more base dimensions of a composite, conjoint dimension, concat dimension, or a partition template based on the selected values of that object, see the LIMIT BASEDIMS command.

Syntax

LIMIT {dimension | valueset } [concat-component] limit-type [limit-clause] [IFNONE label]

where limit-type is one of the following keywords that specify how Oracle OLAP should modify the current status list:

  • TO
  • ADD
  • INSERT [FIRST|LAST|BEFORE position|AFTER position]
  • KEE
  • REMOVE
  • KEEP REORDER
  • COMPLEMENT
  • SORT [NAFIRST]

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values.

concat-component

Specifies the name of the component of the concat dimension whose values are used to determine the limit. When you specify a value for concat-component, the limit sets the status of the specified concat dimension using the values of dimension which is a component of the concat dimension. This limit-clause applies only when dimension is a concat dimension. The status of a concat dimension and of its component dimensions are not shared. Changing the status of a component dimension after you have used that dimension as the limit-clause in setting the status of a concat dimension does not change the status of the concat dimension.

TO

Replaces the status of a dimension or valueset with the values specified by the limit-clause arguments. The TO keyword selects values from the default status of a dimension in the same order as they appear in the LIMIT statement or in the order implied by the valuelist argument. When you use arguments that imply ordering, the ordering of the values is based on their positions in the default status.

ADD

Expands the status of a dimension or valueset by adding the values specified by the limit-clause arguments that are not already in status. The ADD keywords selects values from the default status of a dimension in the same order as they appear in the LIMIT statement or in the order implied by the valuelist argument. When you use arguments that imply ordering, the ordering of the values is based on their positions in the default status. ADD adds unique dimension values in the specified order after the current status list or valueset list.

INSERT

Expands the status of a dimension or valueset by inserting the values specified by the limit-clause arguments in a specified position in the current status. The INSERT keyword selects values from the default status of a dimension in the same order as they appear in the LIMIT statement or in the order implied by the valuelist argument.

When you use arguments that imply ordering (for example,value1TOvalue2), the ordering of the values is based on their positions in the default status. INSERT adds values to a specified position in the current status. When an added value is already in status, it is removed from its position in the current status and added in the order in which it appears in the valuelist, preserving the order of the added values.

FIRST

Inserts the new values before the first value in status.

LAST

Inserts new values after the last value in status.

BEFORE
AFTER

Specifies whether new values Oracle OLAP inserts new values before or after position in the current status.

position

A dimension value in the current status, a character expression whose value is a dimension value in the current status, or an INTEGER expression whose value represents the position of a dimension value in the default status.

KEEP

Reduces the status of a dimension or valueset by keeping only the values specified by the limit-clause arguments. Oracle OLAP performs the selection based on the current dimension status. KEEP preserves the current order of values among the values that remain in the status.

KEEP REORDER

Like a simple KEEP, KEEP REORDER reduces the status of a dimension or valueset by keeping only the values specified by the limit-clause arguments. Oracle OLAP performs the selection based on the current dimension status. However, KEEP REORDER orders the result in the order of the selection arguments (that is, the limit-clause arguments) rather than by the current status order.

REMOVE

Reduces the status of a dimension or a valueset by removing the values specified by the limit-clause arguments. Oracle OLAP performs the selection based on the current dimension status. KEEP preserves the current order of values among the values that remain in the status.

COMPLEMENT

Replaces the status of a dimension or valueset with the values that are not specified by the limit-clause arguments. When you do not specify any arguments after COMPLEMENT, status is replaced by all values not now in status. Oracle OLAP performs the selection based on the current dimension status. COMPLEMENT leaves dimension values that remain in their default order. (Abbreviated COMP)

SORT

Sorts the values of a dimension or valueset according to the limit-clause arguments. LIMIT creates a temporary list of values based on the limit-clause arguments, and uses this list to sort the current status list. Any values not present in the temporary list are moved to the end of the current status list.

NAFIRST

Specifies that NA values are placed first in the sort list rather than last.

limit-clause

Specifies the values to use for the limit. The syntax is quite complex and, consequently, has been divided into the following topics:

IFNONE

(For use only within an OLAP DML program) Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). In either case, the null status is not put into effect when program execution branches. Instead, the original status, before the LIMIT statement was executed, is retained even when OKNULLSTATUS is YES. Within an OLAP DML program, you cannot use both IFNONE and NULL in the same statement.

label

The name of a label elsewhere in the program constructed following the "Guidelines for Constructing a Label". Execution of the program branches to the line directly following the specified label.

Note that label, as specified in IFNONE, must not be followed by a colon. However, the actual label elsewhere in the program must end with a colon.

Usage Notes

Specifying a Value of a Concat Dimension

To specify a value of a nonunique concat dimension, use the following syntax.

<base-dimension: value>.

Default Status List

When you first attach an analytic workspace, the current status list of each dimension consists of all of the values of the dimension that have read permission, in the order in which the values are stored. This list of values is called the default status list for the dimension.

Unique Values

LIMIT selects only unique values of a dimension. When a value appears more than once in a LIMIT statement, it is placed in status in the order of its first appearance. For example, the following lines.

LIMIT time TO 'Jan97', 'Feb97', 'Jan97'
STATUS time

produce this output.

The current status of TIME is:
JAN97, FEB97 

Nonexistent Values

Oracle OLAP does not signal an error when you try to set the status of a dimension or valueset that has no values, unless you explicitly list values that do not exist. For example, assume that you have not added any values to a newly defined dimension WEEK. In this case, the statement LIMIT week TO FIRST 10 does not cause an error. However, LIMIT week TO 'Pete' causes an error because Pete is not a value. Similarly, LIMIT week TO 20 causes an error because week does not have a value at position 20.

Setting the Status of a Dimension or Valueset to Null

Oracle OLAP allows the status of a dimension or valueset to be set to null (empty status) only when you have explicitly specified that you want null status to be permitted. You can give this permission in either of two ways:

  • Set the OKNULLSTATUS option to YES. This specification indicates that null status should be allowed whenever it occurs (unless the IFNONE argument is present in a LIMIT statement).

  • Use the NULL keyword in a LIMIT statement to set the status of a particular dimension or valueset to null. You can do this by specifying TO NULL or KEEP NULL. This specification indicates that null status should be allowed for this LIMIT statement only.

When you have not used either of these two methods to give permission for null status and you execute a LIMIT statement that would result in null status, Oracle OLAP does not change the status to null when it executes the statement. Instead, Oracle OLAP leaves the status as it was before the statement was issued and either signals an error (when IFNONE is not present) or branches to the IFNONE label (when IFNONE is present).

An IFNONE argument indicates that you do not want program execution to take its normal course when a dimension's status were to be set to null. Therefore, when IFNONE is present, Oracle OLAP branches to the IFNONE label and does not set the status to null, even when OKNULLSTATUS is YES. When the NULL keyword is present with IFNONE, Oracle OLAP signals the inconsistency with an error.

IFNONE requires the use of unstructured programming techniques. Oracle OLAP now provides alternative structured techniques, so the use of IFNONE is discouraged. IFNONE has been retained for compatibility with previous versions of Oracle OLAP.

Limiting a Conjoint

To limit a conjoint dimension to a value list, you can use the following constructions:

  • Specify the actual values, surrounding each combination with angle brackets

    LIMIT proddist TO '<Tents, Boston>' -
       '<Footwear, Denver>'
  • Use a variable name for the values, surrounding the combination with angle brackets.

    prodname = 'Canoes'
    distname = 'Seattle'
    LIMIT proddist To <prodname, distname>
    
  • Create a multiline list, where each line is a combination surrounded by angle brackets.

    namelist = '<Tents Boston>\n<Footwear, -
       Denver>\n <Canoes, Seattle>'
    LIMIT proddist TO namelist
  • Use the implicit relation between a conjoint dimension and its base dimension to limit the conjoint dimension. For example, use the following statement to limit PRODDIST to all conjoint values having "Canoes" as one of its base values.

    LIMIT proddist TO product 'Canoes'

    Note:

    You can use logical position numbers for base dimension values in a conjoint dimension. "Example 7-125" illustrates using logical position numbers

For an example of how you can limit a conjoint dimension that has a concat base dimension, see Example 10-25.

Limiting a Concat

You can define a concat dimension using simple dimensions, conjoint dimensions, and other concat dimensions as the base dimensions of the concat. The syntax for limiting a concat dimension to one of its values is the following.

LIMIT concatdim TO <base-dim: value>

For example, the concat dimension reg.dist.ccdim has the simple dimensions region and district as its base dimensions. The following statement sets the status of reg.dist.ccdim to two of its values, region: East and district: Atlanta.

LIMIT reg.dist.ccdim TO <region: 'East'> <district: 'Atlanta'>

For other methods of setting the status of a concat dimension, see Example 10-16.

Alternative to Branching Using an IFNONE Label

As an alternative to branching to an IFNONE label, you can also handle null status for a dimension with the OKNULLSTATUS option. When you set OKNULLSTATUS to YES, then you are allowed to set the status of a dimension to null. You can then check for null status and execute appropriate commands with an IF...THEN...ELSE command, or you can handle null status as a case in a SWITCH command.

OKNULLSTATUS = YES
LIMIT month TO sales GT salesnum
IF STATLEN(month) LT 1
   THEN GOTO showerr

Examples

Example 10-14 Adding and Removing Values

These lines add values to the status for the month dimension.

LIMIT month TO 'Jan96' TO 'Jun96'
LIMIT month ADD 'Jul96' 'Sep96'

Issuing a STATUS month statement produces this output.

The current status of MONTH is:
Jan96 TO Jul96, Sep96

This line removes values from the status for the month dimension.

LIMIT month REMOVE 'Jan96' TO 'Mar96'

Now, issuing a STATUS month statement produces this output

The current status of MONTH is:
Apr96 TO Jul96, Sep96

Example 10-15 Limiting with a Dimension Surrogate

A dimension and any dimension surrogates for it share the same status.

For example, assume that there is a NUMBER dimension named store_id that has the values 25, 410, 150, 205, 310, and 10. It also uses storepos, an INTEGER dimension surrogate for store_id. The dimension surrogate storepos has the values 1, 2, 3, 4, 5, and 6. A TEXT dimension surrogate for store_id is storename. It has the text values Raoul's - Boston, Poldy's Potpourri, Molly's Emporium, Raoul's - Atlanta, Kinch's Kitchen Supplies, and Raoul's - Chicago. The following statements are equivalent.

LIMIT store_id TO 25 410 150
LIMIT store_id TO storepos 1 2 3
LIMIT storepos TO 1 TO 3
LIMIT storepos TO first 3
LIMIT storename TO first 3
LIMIT storename TO 'Raoul\'s - Boston' TO 'Molly\'s Emporium'
LIMIT store_id TO storename storepos 1 2 3
LIMIT storename TO store_id 25 TO 150

The following statements set the status of the store_id dimension by limiting storename, which is a TEXT dimension surrogate for store_id, and report the values of store_id.

LIMIT storename TO 'Raoul\'s Sweets' TO 'Henry\'s Flowers'
REPORT store_id

The preceding statement produces the following output.

STORE_ID
--------------
10
20
30

Example 10-16 Limiting a Concat Dimension

In the following examples, the concat dimension reg.dist.ccdim has the simple dimensions region and district as its base dimensions. A concat dimension has an implicit relation to each of its component dimensions.

  • The following statement sets the status of the concat dimension using the related dimension syntax and specifying the positions of the component (related) dimension.

    LIMIT reg.dist.ccdim TO district 1, 4, 5
    

    Issuing a STATUS reg.dist.ccdim statement produces the following output.

    The current status of REG.DIST.CCDIM is:
    <DISTRICT: BOSTON>, <DISTRICT: DALLAS>, <DISTRICT: DENVER>
    
  • The following statement limits the concat dimension directly to the values specified by positions of the concat dimension.

    LIMIT reg.dist.ccdim TO 1, 4, 5
    

    Issuing a STATUS reg.dist.ccdim statement produces the following output.

    The current status of REG.DIST.CCDIM is:
    <REGION: EAST>, <DISTRICT: BOSTON>, <DISTRICT: ATLANTA>
    
  • The following statements set the status of district and then limit reg.dist.ccdim to the status of district.

    LIMIT district TO LAST 3
    LIMIT reg.dist.ccdim TO district
    

    Issuing a REPORT reg.dist.ccdim statement produces the following output.

    REG.DIST.CCDIM
    ----------------------
    <district: Dallas>
    <district: Denver>
    <district: Seattle>
    
  • In the following statement, the limit-clause argument is a list of values of the concat dimension.

    LIMIT reg.dist.ccdim TO <region: 'East'> <district:  'Boston'> <district: 'Atlanta'>
    
  • The following statements define a valueset for reg.dist.ccdim, store the current status of the concat dimension in the valueset, reset the status of the concat to ALL, and then limit the concat to the valueset and report the values of the concat in status.

    DEFINE regdist.vset VALUESET reg.dist.ccdim
    LIMIT regdist.vset TO reg.dist.ccdim
    LIMIT reg.dist.ccdim TO ALL
    LIMIT reg.dist.ccdim TO regdist.vset
    RPR W 22 reg.dist.ccdim
    

    The preceding statements produce the following result.

    REG.DIST.CCDIM
    ----------------------
    <region: East>
    <district: Boston>
    <district: Atlanta>
    

You can also limit a concat dimension using a valueset of one of its component dimensions:

  • When the component dimensions contain identical values, you can limit the concat dimension to those values by using a Boolean expression. When the district and region dimensions both have New York as a value, then the following statement limits the reg.dist.ccdim to those values.

    LIMIT reg.dist.ccdim TO BASEVAL(reg.dist.ccdim) EQ 'New York'
    
  • In the following example, the concat dimension geog has the simple dimension region and the conjoint dimension cityandstate as its base dimensions. The following statement sets the status of the concat dimension by limiting the conjoint base dimension.

    LIMIT geog TO cityandstate <'Princeton' 'New Jersey'> -
       <'Patterson' 'New Jersey'>
    

    Issuing a STATUS geog statement produces the following output.

    The current status of GEOG is:
    <CITYANDSTATE: <PRINCETON, NEW JERSEY>, <CITYANDSTATE: <PATTERSON, NEW JERSEY>>
    
  • The following statements sets the status of the concat dimension by limiting the conjoint base dimension by specifying a value of a base dimension of the conjoint dimension.

    LIMIT geog TO cityandstate city 'Princeton'
    RPR W 30 geog
    

    The preceding statement produces the following output.

    GEOG
    ------------------------------
    <cityandstate: <Princeton, New Jersey>>
    <cityandstate: <Princeton, Indiana>>

Example 10-17 Limiting with a Worksheet

This example shows how to limit a dimension to the values that are contained in a column of a worksheet. Here the dimension month is limited to the values that are contained in the first column of the worksheet workitem. The following statements produce a workitem report, which is shown following the statements.

LIMIT month TO ALL
LIMIT wkscol TO 1
LIMIT wksrow TO workitem NE NA
REPORT workitem
               -WORKITEM-
               --WKSCOL--
WKSROW             1
-------------- ----------
             1 Jan96
             2 Feb96
             3 Mar96
             4 Apr96
             5 May96
             6 Jun96
             7 Jul96
             8 Aug96
             9 Sep96
            10 Oct96
            11 Nov96
            12 Dec96

The following statement limits the month dimension to the values that are listed in the first column of workitem.

LIMIT month TO CHARLIST(workitem)

Issuing a STATUS month statement produces the following output.

The current status of MONTH is:
Jan96 TO Dec96

Example 10-18 Using Ampersand Substitution with LIMIT

Assume that you want to specify exactly two products for a program named product.rpt. In this case, you could declare two dimension-value arguments to handle them. But when you want to be able to specify any number of products using LIMIT commands, then you can use a single argument with ampersand substitution.

Suppose you use the following commands in your program.

ARGUMENT natext TEXT
ARGUMENT widthamt INTEGER
ARGUMENT rptprod TEXT
    ...
LIMIT product TO &rptprod

You can run the program and specify that you want the first three products in the report.

CALL product.rpt ('Missing' 8 'first 3')

The single quotation marks are necessary to indicate that "first 3" should be taken as a single argument, rather than two separate arguments separated by a space. The ampersand causes the LIMIT command to interpret 'first 3' as a keyword expression rather than as a dimension value.

Example 10-19 Branching on Null Status

Your program might try to set or refine the status of the product dimension to include only the products for which unit sales are greater than 500. When no products have unit sales of more than 500, then you can use the IFNONE keyword to specify that execution branch to the novals label.

LIMIT product KEEP units GT 500 IFNONE novals

In the commands following the novals label, you can handle the special situation in which no products have units sales greater than 500.

10.9.1 LIMIT (using values) command

A LIMIT command with a using values limit clause assigns values to a valueset or sets the current status list of a dimension or dimension surrogates to:

  • Specified value or values. The values can be any of the following:

    • Dimension values, expressed as literal values separated by commas, or as a multiline text expression, each line of which is a value of the dimension.

    • Ranges of dimension values, expressed as value1 TO value2.

    • Integer values that represent the logical positions of dimension values, expressed as comma-delimited INTEGER values.

    • Ranges of INTEGER values that represent the logical positions of dimension values, expressed as value1 TO value2.

    • Valuesets.

  • Values for which a Boolean expression is TRUE.

  • The top or bottom performers of a dimension based on a criterion

  • The top or bottom performers of a dimension, by percentage, based on a criterion represented as an expression

Syntax

LIMIT {dimension | valueset} [concat-component] limit-type -

     {inclusive-val-args....| exclusive-val-args} [IFNONE label]

where:

  • inclusive-val-args is one or more of the following constructs:

    •      intvaluelist 
    •      text-expression
    •      value1 TO value2
    •      valuelist
    •      valueset
  • exclusive-val-args is one of the following constructs:

    •      ALL
    •      boolean-expression
    •      {BOTTOM|TOP} BASEDON expression
    •      {BOTTOM|TOP} n-percent PERCENTOF expression
    •      {FIRST|LAST} n
    •      NTH {n |n TO n}...
    •      LONGLIST
    •      LONGLIST
    • SESSION
    • STATUS
    •      NULL

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A keyword that specifies how Oracle OLAP should modify the current status list. (See the main entry for LIMIT command for a list and descriptions of these keywords.)

intvaluelist

A list of one or more INTEGER values, or the name of a single-cell variable that holds a numeric value. Separate the values with commas (,). Numeric values with decimal places (SHORTDECIMAL or DECIMAL values) are automatically truncated to INTEGER values before being used as dimension values. An INTEGER specifies a dimension value by its logical position in the full set of dimension values. You cannot specify a NUMBER dimension value by an INTEGER position. When the values of the NUMBER dimension are INTEGER values, then you can set the status of the dimension by specifying dimension values, as in intvalue1, intvalue2 and so on.

text-expression

A multiline text expression, each line of which is a value of dimension.

value1 TO value2

Specifies a range of dimension values where value1 and value2 can be either INTEGER values or dimension values. Such a range can be increasing (for example, 1 to 10) or decreasing (for example, 10 to 1). When you specify an INTEGER value, that value is the logical position of a value in the default status list for the dimension. When you specify a dimension value, the command convertsthe value to the logical position of the value in the default status list for the dimensioon. The current status of the dimension or valueset is assigned accordingly.

Tip:

You cannot specify the values of a NUMBER dimension using INTEGER positions. Instead, define an INTEGER dimension surrogate for the NUMBER dimension and limit the dimension by the positions of the surrogate.

valuelist

A list of one or more values of dimension. A dimension value can be specified as a text expression whose value is a valid dimension value. For a NUMBER dimension, dimension values are numbers. For dimensions with a type of DAY, WEEK, MONTH, QUARTER, or YEAR, dimension values can also be specified as DATE expressions.

valueset

An analytic workspace valueset object that is a saved list that holds the values for the dimension whose status is being set. You cannot define a valueset for a dimension surrogate, therefore you cannot specify a valueset when setting the status of a dimension surrogate. However, when you limit a dimension with a valueset, then you automatically limit to the same set any dimension surrogates of that dimension. You can also specify a LIMIT function.

ALL

Specifies that all dimension values in the default status are to be included in the status. The default status is made up of all dimension values for which read permission is granted, in the same order as when the dimension was last maintained. When you start up an analytic workspace, the status for each dimension in your analytic workspace is the default status. Changing the read permission for a dimension with PERMIT or PERMITRESET statement changes the default status for the dimension.

boolean-expression

An expression whose TRUE values are used by Oracle OLAP when limiting the dimension or status. The boolean-expression must be dimensioned by the dimension whose status is being set. For a dimension surrogate, the Boolean expression is evaluated over the dimension for which it is a surrogate. The data types of the expressions you are comparing in the Boolean expression must be similar. See the CONVERT function for information on converting data types. To correctly use LIMIT with a Boolean expression you must understand how it works with a Boolean expression that has with multiple dimensions, see "How LIMIT Handles Boolean Expressions With More Than One Dimension" for details.

BOTTOM  n BASEDON expression
TOP n BASEDON expression

Specifies that the status of a dimension or valueset is set based on a criterion, where n is the number of values to select and expression is the criterion on which to base the selection. All dimensions of expression other than the one whose status is being set must be limited to a single value. TOP results in the status sorted in descending order, BOTTOM results in the status sorted in ascending order. You cannot use a composite after the BASEDON keyword. When you attempt to do so, an error message is displayed.

BOTTOM n-percent PERCENTOF expression
TOP n-percent PERCENTOF expression

Specifies that the status of a dimension or valueset is set by finding the top or bottom performers based on a criterion represented as an expression. This construction sorts values and adds them to the status that is based on their contribution, by percentage, to an expression.

For example, the following statement sorts products in descending order by each product's contribution to TOTAL(sales) and then add values to the status, starting from the top, until the cumulative total of sales by product reaches or exceeds 30 percent of all sales.

LIMIT product TO TOP 30 PERCENTOF TOTAL(sales, product)

Note:

Do not use a criterion expression that causes a side effect or changes its own value.

FIRST n
LAST n

Specifies the first n, last n values in the dimension's full set of values when used with TO, ADD, COMPLEMENT, or INSERT. When used with KEEP or REMOVE, specifies the first n, last n or nth values in the current status.

Note:

It can happen that the last item in status, based on a PERCENTOF criterion, is one of several dimension values having the same associated criterion value. In this case, LIMIT includes all dimension values with that criterion value in the resulting status, even when that causes the total of the criterion value to far exceed the specified percentage.

NTH {n |n TO n}

Specifies the n values in the dimension's full set of values when used with TO, ADD, COMPLEMENT, or INSERT. When used with KEEP or REMOVE, specifies the n values in the current status. You can specify any number of values or range of values.

LONGLIST

Indicates that there can be up to 2,000 arguments in the LIMIT statement. When there are less than 300 arguments, LONGLIST is not needed.

SESSION

Specifies that Oracle OLAP use only those dimension members that were created using a MAINTAIN ADD SESSION statement when performing the limit.

STATUS

Specifies that Oracle OLAP use the values that are presently in status when performing the limit. Specifying this keyword is equivalent to (but more efficient than) using a VALUES (dimname) statement.

NULL

Indicates an empty dimension or valueset list. Using this keyword with the TO or KEEP arguments removes all values from the current status, leaving an empty dimension or valueset list, even when OKNULLSTATUS is NO. You cannot use IFNONE and NULL in the same LIMIT statement. ADD, INSERT, and REMOVE NULL leave status unchanged. COMPLEMENT NULL places all values in status.

IFNONE label

Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

Usage Notes

Considerations When Specifying Values

Keep the following points in mind when specifying values in limit-clause:

  • The setting of the LIMITSTRICT option determines how Oracle OLAP behaves when a list of values in a LIMIT command, a LIMIT function, or a QDR contains a nonexistent value. By default, when you specify a nonexistent value, Oracle OLAP treats the nonexistent value as an invalid value and stops executing the limit and issues an error. If, instead, you want Oracle OLAP to treat a nonexistent value as an NA value, set the value of LIMITSTRICT to NO.

  • You can embed a quoted string within a quoted string, which is necessary when there are special characters in a base dimension value of a composite or conjoint dimension, such as Joe's Deli. See the "Text Literals".

  • When the dimension has the NTEXT data type and an argument that represents a dimension value has the TEXT data type, LIMIT converts the argument value to NTEXT. Similarly, when the dimension has the TEXT data type and an argument that represents a dimension value has the NTEXT data type, LIMIT converts the argument value to TEXT; however, in this case, the conversion can result in data loss when the NTEXT value cannot be represented in the database character set.

  • When you specify a value of a dimension with a type of DAY, WEEK, MONTH, QUARTER, or YEAR, the value can be in the format specified by the VNF (value name format) for the dimension (or in the default VNF for the type of dimension you are limiting when the dimension does not have a VNF) or in a valid input style for DATE values.

    You must only provide the date components that are relevant for the type of dimension you are limiting. For a DAY or WEEK dimension, you must supply the day, month, and year components. For a MONTH or QUARTER dimension, you must only supply the month and year (for example, Jun95 or 0695 for June 1995). For a YEAR dimension, you must only specify the year (for example, 95 for 1995). The valid input styles for dates are discussed in DATEORDER.

    When you specify a DATE expression or a text value that represents a complete date, you can specify any date that falls within the time period that is represented by the desired dimension value. Oracle OLAP uses the DATEORDER option to resolve any ambiguities.

How LIMIT Handles Boolean Expressions With More Than One Dimension

When you have used this type of LIMIT command (or LIMIT function) to limit only one dimension of a multi-dimensional Boolean expression, you effectively limit that expression to the values of limited dimension and only the current values of the unlimited dimensions.

For example, assume that you you have a sales variable is dimensioned by three dimensions: product, district, and month.

Let's look first at what happens when you explicitly limit district and month dimensions to single values and then limit product using a Boolean expression.

LIMIT month TO 'Jan95'
LIMIT district TO 'Boston'
LIMIT product TO sales GT 90000
STATUS product

The STATUS statement produces the following output.

The current status of PRODUCT is:
Footwear

In this case, the resulting status is all of the products whose sales exceed $90,000 for the month of January 1995 in the Boston district, which is only Footwear.

Now consider the following example in which the MONTH dimension is not limited to a single value.

LIMIT product TO ALL
LIMIT month TO 'Jan95' 'Feb95' 'Mar95'
LIMIT district TO 'Boston'

When you execute a REPORT sales statement, you can see the BOSTON sales figures for three months.

DISTRICT: BOSTON
               -------------SALES--------------
               -------------MONTH--------------
PRODUCT          Jan95      Feb95      Mar95
-------------- ---------- ---------- ----------
Tents           32,153.52  32,536.30  43,062.75
Canoes          66,013.92  76,083.84  91,748.16
Racquets        52,420.86  56,837.88  58,838.04
Sportswear      53,194.70  58,913.40  62,797.80
Footwear        91,406.82  86,827.32 100,199.46

However, the following LIMIT and STATUS commands produce the output shown following them. Again, only Footwear is in the status for month.

LIMIT product TO sales GT 90000
STATUS product
 
The current status of PRODUCT is:
Footwear

In this case, each product has three sales figures, one for each month. For each product, LIMIT evaluates the sales data for only the first month in status. A product is added to the status when its sales data exceeds $90,000 in that month.

When you would like all months evaluated for each product, you can use the EVERY, ANY, or NONE functions. For example, the following LIMIT statement adds a product to the status when any of its months has a sales figure that exceeds $90,000.

LIMIT product TO ANY(sales GT 90000, product)

In this case a STATUS product statement produces the following output.

The current status of product is:
Canoes, Footwear

Limiting Using Implicit Relations

Every dimension with a type of DAY, WEEK, MONTH, QUARTER, or YEAR is related to all other dimensions of this type through an implicit relation. When you limit the values of one DAY, WEEK, MONTH, QUARTER, or YEAR dimension by specifying another DAY, WEEK, MONTH, QUARTER, or YEAR dimension as the related-dimension, Oracle OLAP uses the implicit relation by default. However, when an explicit relation is defined between the two of these types of dimensions, you can override the default by specifying the name of the explicit relation as the related-dimension. For example, you can issue the following statement.

LIMIT month TO quarter year

This statement temporarily limits quarter to year, then limits month to quarter, and finally, restores quarter to its original status.

Examples

Example 10-20 Using LIMIT to Partially Populate Variables

DEFINE GEOG DIMENSION TEXT
DEFINE PRODUCTS DIMENSION TEXT
DEFINE SALES VARIABLE DECIMAL <PRODUCTS GEOG>
DEFINE COSTS VARIABLE DECIMAL <PRODUCTS GEOG>

Assume also as shown by the following reports that you have populated the dimensions but not the variables. All of the elements of the costs and sales variables appear in the report and all have the value of NA.

PRODUCTS
------------
TVs
Radios
Skis
Bikes
 
GEOG
------------
Boston
Springfield
New Orleans
Baton Rouge
Quebec City
Montreal
Toronto
Norfolk
 
             -------------------SALES-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston               NA         NA         NA         NA
Springfield          NA         NA         NA         NA
New Orleans          NA         NA         NA         NA
Baton Rouge          NA         NA         NA         NA
Quebec City          NA         NA         NA         NA
Montreal             NA         NA         NA         NA
Toronto              NA         NA         NA         NA
Norfolk              NA         NA         NA         NA
 
             -------------------COSTS-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston               NA         NA         NA         NA
Springfield          NA         NA         NA         NA
New Orleans          NA         NA         NA         NA
Baton Rouge          NA         NA         NA         NA
Quebec City          NA         NA         NA         NA
Montreal             NA         NA         NA         NA
Toronto              NA         NA         NA         NA
Norfolk              NA         NA         NA         NA
 

Now you issue the following LIMIT command so that only values indexed by Boston and Springfield values of the geog dimension are accessible to Oracle OLAP.

LIMIT geog TO 'Boston' 'Springfield'
 

Now you issue new reports for geog, costs, and sales. For the geog dimension only the Boston and Springfield elements values appear. Also, only the elements of the costs and sales variables that are indexed by Boston and Springfield appear in the report.

GEOG
------------
Boston
Springfield
 
             -------------------SALES-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston               NA         NA         NA         NA
Springfield          NA         NA         NA         NA
 
             -------------------COSTS-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston               NA         NA         NA         NA
Springfield          NA         NA         NA         NA
 

Now you issue two assignment statements that use the RANDOM function to populate the costs and sales variables, followed by the LIMIT command that sets the status of the geog dimension to its default status of ALL.

 
sales = RANDOM (200)
costs = RANDOM (100)
LIMIT geog to ALL
 

Now you issue new reports for geog, costs, and sales. All of the values of the geog dimension and all of the elements of the costs and sales variables appear. However, only the elements of the costs and sales variables that are indexed by Boston and Springfield have non-NA values.

 
GEOG
------------
Boston
Springfield
New Orleans
Baton Rouge
Quebec City
Montreal
Toronto
Norfolk
 
             -------------------SALES-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston           199.97     133.82      10.07     148.17
Springfield      173.94      27.56      32.21      47.40
New Orleans          NA         NA         NA         NA
Baton Rouge          NA         NA         NA         NA
Quebec City          NA         NA         NA         NA
Montreal             NA         NA         NA         NA
Toronto              NA         NA         NA         NA
Norfolk              NA         NA         NA         NA
 
             -------------------COSTS-------------------
             -----------------PRODUCTS------------------
GEOG            TVs       Radios      Skis      Bikes
------------ ---------- ---------- ---------- ----------
Boston            43.52      25.32      68.68      10.38
Springfield        9.49      27.96      61.76      16.12
New Orleans          NA         NA         NA         NA
Baton Rouge          NA         NA         NA         NA
Quebec City          NA         NA         NA         NA
Montreal             NA         NA         NA         NA
Toronto              NA         NA         NA         NA
Norfolk              NA         NA         NA         NA

Example 10-21 Limiting with a Boolean Expression

You can limit a dimension or valueset according to the values of a Boolean expression. In this example, the values of the TOTALL function are broken out by product and compared to a constant. The LIMIT statement sets the status to all the products whose sales, totaled for all months and districts, are greater than 12 million.

LIMIT product TO TOTAL(sales product) GT 12000000

Example 10-22 Limiting with a Formula

When you use the same criterion frequently to limit a dimension, you can save the expression as a formula and use the name of the formula as the limit expression.

DEFINE criterion FORMULA TOTAL(sales product) GT 12000000
LIMIT product TO criterion

Example 10-23 Limiting with a Valueset

You can save a status list in a valueset and use those values later to limit the status. When it takes several LIMIT commands to produce the status list you want, the valueset keeps you from having to repeat those LIMIT commands each time you need the same list. The following statements limit district to the districts in which sportswear sales exceeded $1,000,000 in 1996. The status is saved in the valueset sports.district, and you can limit district to the same list with one LIMIT statement.

DEFINE sports.district VALUESET district
LIMIT product TO 'Sportswear'
LIMIT month TO year 'Yr96'
LIMIT sports.district TO TOTAL(sales district) GT 1000000
LIMIT district TO sports.district

Issuing a STATUS district statement produces this output.

The current status of DISTRICT is:
ATLANTA TO DENVER

Example 10-24 Limiting with a Variable

Here the TOP and BASEDON keywords are used to limit the status of a dimension, using the values of a variable as a criterion. The status list is sorted in descending order according to the values of sales.

LIMIT product TO 'Sportswear'
LIMIT month TO 'Jul96'
LIMIT district TO TOP 2 BASEDON sales

The following REPORT statement

REPORT DOWN district sales

produces this output, which shows the results of the LIMIT commands.

PRODUCT: SPORTSWEAR
               --SALES---
               --MONTH---
DISTRICT         Jul96
-------------- ----------
Dallas         220,416.81
Atlanta        211,666.14

Example 10-25 Limiting a Conjoint Dimension with a Concat Base Dimension

Assume that your analytic workspace contains a conjoint dimension named prod.regdist that has the product simple dimension and the reg.dist.ccdim concat dimension as its base dimensions. The conjoint dimension prod.regdist has the following values.

Tents   <region: East>
Tents   <region: West>
Canoes  <region: East>
Canoes  <region: West>
Tents   <district: Boston>
Tents   <district: Atlanta>
Tents   <district: Denver>
Canoes  <district: Atlanta>
Canoes  <district: Seattle>

There are two different ways that you can set the status of a conjoint dimension that has a concat dimension as a base dimension:

  • By specifying the concat dimension, one of its component dimensions, and a value of the component dimension. The following LIMIT statement sets the status of prod.regdist in this manner.

    LIMIT prod.regdist TO reg.proddist.ccdim district 'Atlanta'
    RPR W 20 prod.regdist
    

    The preceding statement produces the following output.

    --------------PROD.REGDIST---------------
          PRODUCT           REG.DIST.CCDIM
    -------------------- --------------------
    Tents                <district: Atlanta>
    Canoes               <district: Atlanta>
    
  • You can also set the status of the conjoint by specifying its values. The following LIMIT statement sets the status of prod.regdist in this manner.

    LIMIT prod.regdist TO <'Tents' '<region: East>'> <'Tents' '<district: Boston>'>
    RPR W 20 prod.regdist
    

    The preceding statement produces the following output.

    --------------PROD.REGDIST---------------
          PRODUCT           REG.DIST.CCDIM
    -------------------- --------------------
    Tents                <region: East>
    Tents                <district: Boston>

10.9.2 LIMIT using LEVELREL command

A LIMIT command that uses only dimension values that are at the same level as the current level of the hierarchical dimension or dimension surrogate when setting status or assigning values to a valueset.

Syntax

LIMIT {dimension | valueset} [concat-component] limit-type-

     LEVELREL level-relation-clause [IFNONE label]

where the syntax of level-relation-clause varies depending on the dimensionality of the object you want to specify:

  • To specify a level relation which is multidimensional you use the following syntax:

    RELATION level-relation-name [QUALIFY relation-dimension-name [inclusive-val-args...]...]

    (You can also use this syntax when the level relation is one-dimensional.)

  • To specify a level relation which is one-dimensional, you can use the following simplified syntax:

     level-relation-name [valueset2]   

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values; or a LIMIT function.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A keyword that specifies how Oracle OLAP should modify the current status list. (See the main entry for LIMIT command for a list and descriptions of these keywords.)

LEVELREL

Sets the status of a hierarchical dimension to all of the values of the hierarchical dimension that are at the same level as the current value of the dimension; or, that limits a hierarchical dimension to those values of the hierarchical dimension that are at the same level as the current value of the dimension and that are also in a specified valueset.

RELATION

Specifies that Oracle OLAP performs the limit based on the values of the relation specified by level-relation-name. Specify this keyword if level-relation-name is a multidimensional relation.

level-relation-name

Specifies the name of a level relation for the hierarchical dimension you want to limit. See "Levelrel Relation" for more information.

QUALIFY relation-dimension-name [inclusive-val-args]

Identifies the values by which Oracle OLAP performs the limit.

  • relation-dimension-name is the name of a dimension of the relation specified by level-relation-name.

  • inclusive-val-args specifies the values of relation-dimension-name to use when determining the values of level-relation-name by which to perform the limit. You can specify any inclusive valuelist argument as described in the syntax of the inclusive-val-args argument for the valuelist clause for LIMIT command. (See LIMIT (using values) command for detailed syntax.) When you omit this argument, Oracle OLAP uses the current status of the dimension when performing the limit.

valueset2

Specifies the name of a valueset object is dimensioned by the level dimension for the hierarchical dimension that you want to limit. The result of using this argument is the individual valueset that corresponds to the level value of the current position of the dimensions.

You can also specify aLIMIT function.

IFNONE label

Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

Examples

Example 10-26 Limiting to a Single Time Period of a Hierarchical Time Dimension

Assume that you have defined a hierarchical text dimension named time, a level dimension named timelevels that has Month and Year as values, and a relation named timelevelsrel that is dimensioned by time and that has timelevels as a related dimension (that is, for each value of the time dimension, timelevelsre contains a value of either Month or Year) When you want to limit the values of time that are already in status to only those values that are at the same level as Jan99, you can issue the following statement.

LIMIT time TO LEVELREL timelevelsrel

This is equivalent to issuing the following statement

LIMIT time TO RELATION timelevelsrel QUALIFY time CURRENT

10.9.3 LIMIT (using related dimension) command

A LIMIT command with a related-dimension limit clause that uses the values of a different related dimension to assign values to a valueset or to set the status of a dimension or a dimension surrogate.

Syntax

LIMIT {dimension | valueset} limit-type related-dim-clause [IFNONE label]

where the syntax of related-dim-clause varies depending on the type of object being specified:

  • When you want to specify a relation, the syntax is:

    RELATION relation-name [QUALIFY relation-dimension-name [inclusive-val-args...]...]

  • When you want to specify a dimension that is related to the dimension being limited, the syntax is:

     related-dimension-name [related-dimension-valuelist]   

    (You can also use this simplified syntax when the object is a one-dimensional relation.)

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values; or a LIMIT function.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A keyword that specifies how Oracle OLAP should modify the current status list. (See the main entry for LIMIT command for a list and descriptions of these keywords.)

RELATION relation-name

Specifies that Oracle OLAP performs the limit based on the values of the relation specified by relation-name. Specify this keyword if relation-name is a multidimensional relation. Also, when there are multiple relations between the dimension being limited and the dimension specified by related-dimension-name, you can use this phrase to identify which relation Oracle OLAP uses to perform the limit.

QUALIFY relation-dimension-name [inclusive-val-args]

Identifies the values by which Oracle OLAP performs the limit, where:

  • relation-dimension-name is the name of a dimension of the relation specified by relation-name.

  • inclusive-val-args specifies the values of relation-dimension-name to use when determining the parent values. You can specify any inclusive valuelist argument as described in the syntax of the inclusive-val-args argument for the valuelist clause for LIMIT command. See LIMIT (using values) command for detailed syntax. When you omit this argument, Oracle OLAP uses the current status list of the related dimensions when performing the limit.

related-dimension-name

Specifies the name of a one-dimensional relation or a dimension that is related to the dimension being limited. For related-dimension-name, you can also specify a dimension surrogate for the dimension you are limiting, or a dimension surrogate of the related dimension. For example, dimsurr is a dimension surrogate of dim2 and dim2 is related to dim1. The dimension surrogate dimsurr has the values Dsv1, Dsv2, Dsv3 and Dsv4. The following statement limits dim1 by specifying values of dimsurr.

LIMIT dim1 TO dimsurr dsv1 dsv3
related-dimension-valuelist

The values of the related dimension or a dimension surrogate for the related dimension or the dimension specified using the syntax shown in LIMIT command. See LIMIT (using values) command for detailed syntax. When this argument is present in a LIMIT statement, status is obtained by selecting the values of the dimension being limited, which are related to the related-dimension values. When valuelist is omitted, the current status value of related-dimension is used.

IFNONE label

Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

Usage Notes

Limiting to a Related Dimension Is a Two-Step Process

When you limit a dimension or valueset to a related dimension, the resulting status is determined in a two-step process:

  1. The dimension values are arranged in the order of the values of the related dimension.

  2. When there are multiple values of the dimension for any value of the related dimension, those values are arranged in the order of their default status.

Suppressing the Sort When Limiting to a Related Dimension

You can suppress the sort that occurs when you limit a dimension or valueset to a related dimension by setting LIMITSORTREL to NO which can significantly improve performance when the dimension you are limiting is large.

Note:

When LIMIT.SORTREL is NO, printed output of a dimension may not appear in logical order.

Examples

Example 10-27 Limiting with a Related Dimension

Here the status of a dimension is limited using a related dimension. This statement limits district to Boston and Atlanta, which are in the East region.

LIMIT district TO region 'East'

This statement limits product to Sportswear and Footwear, which are in the division that appears last in the list of division values.

LIMIT product TO division LAST 1

10.9.4 LIMIT (using parent relation)

A LIMIT command that uses a parent relation in its limit clause to set the status of a hierarchical dimension or its dimension surrogate, or assigns values to a valueset, based on family relationships within the hierarchy.

Syntax

LIMIT {dimension | valueset} [concat-component] limit-type-

     [family-keyword ] USING parent-relation-clause [IFNONE label]

where:

  • family-keyword has one of the following constructs:

    •      PARENTS
    •      CHILDREN
    •       ANCESTORS [DISTANCE generation ]
    •       DESCENDANTS [DISTANCE generation ]
    •       SIBLINGS
    • TOPANCESTORS
    • BOTTOMDESCENDANTS
    •       HIERARCHY [INVERTED] [NOORIGIN] [SKIP n] [DEPTH n] [RUN textexp]] 
  • The syntax for parent-relation-clause varies depending on its dimensionality of the object you want to specify:

    • When the parent relation is multidimensional, use the following syntax:

      RELATION parentrel [QUALIFY relation-dimension-name [inclusive-val-args... | CURRENT]...]

      (You can also use this syntax when the parent relation is one-dimensional.)

    • When the parent relation is one-dimensional, you can use the following simplified syntax:

       parentrel [inclusive-val-args | CURRENT] 

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values; or a LIMIT function.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A keyword that specifies how Oracle OLAP should modify the current status list. (See the main entry for LIMIT command for a list and descriptions of these keywords.)

PARENTS

Finds the parent of each value in valuelist. For a dimension, when there is no valuelist, finds the parent for each value in status. For a valueset, when there is no valuelist, it finds the parent of each value in the valueset. It uses the parent-relation to look up the parent.

CHILDREN

Finds the children of each value in valuelist. For a dimension, when there is no valuelist, finds the children for each value in status. For a valueset, when there is no valuelist, it finds the children of each value in the valueset. It uses the parent-relation to look up the children.

ANCESTORS [DISTANCE generation]

When you do not include the DISTANCE phrase:

  • Finds the ancestors (that is, parents, grandparents, and so on) of each value in valuelist. For a dimension, when there is no valuelist, it finds the ancestors of each value in status.

  • For a valueset, when there is no valuelist, it finds the ancestors of each value in the valueset. In other words it finds "parents" for the values and the "parents of the parents" until there are no new parents.

When you include the DISTANCE phrase, limits to the ancestors who are members of the generation specified by generation:

  • For generation, specify 0 for the current generation, 1 for parents, 2 for grandparents, 3 for great grandparents, and so on.

  • For negative values, the command returns descendant generations (that is -1 returns children, -2 returns grandchildren, and so on).

DESCENDANTS [DISTANCE generation]

When you do not include the DISTANCE phrase:

  • Finds the descendants (that is, children, grandchildren, and so on) of each value in valuelist. For a dimension, when there is no valuelist, it finds descendants for each value in status.

  • For a valueset, when there is no valuelist, it finds the descendants of each value in the valueset. In other words, it finds the children of the values and the children of the children until there are no new children.

When you include the DISTANCE phrase, limits to the descendants who are members of the generation specified by generation:

  • For generation, specify 0 for the current generation, 1 for children, 2 for grandchildren, 3 for great grandchildren, and so on.

  • For negative, the command returns ancestor generations (that is -1 returns parents, -2 returns grandparents, and so on).

SIBLINGS

Finds all siblings of each value in valuelist, including the valuelist values, themselves. Issuing one LIMIT statement with the SIBLIGS keyword is the same as issuing two consecutive LIMIT statements: 1) LIMIT with PARENTS, 2) LIMIT with CHILDREN. For a dimension, when there is no valuelist, it finds siblings for each value in status. For a valueset, when there is no valuelist, it finds the siblings of each value in the valueset.

TOPANCESTORS

(Abbreviated TOPANC) Finds those members that are at the top of the hierarchy; that is, those members that do not have any ancestors which is equivalent to issuing the following two LIMIT commands.

   LIMIT dimension to ANCESTORS ....
   LIMIT dimension REMOVE DESCENDANTS....
BOTTOMDESCENDANTS

(Abbreviated BOTTOMDESC) Finds those members that are at the bottom of the hierarchy; that is, those members that do not have any descendants.

HIERARCHY

Finds the descendants (that is, children, grandchildren, and so on) based on a particular parent-relation. The difference is the order of the values. DESCENDANTS groups the values by level (all children, then all grandchildren, and so on); HIERARCHY places each group of children next to its parent. HIERARCHY includes the original values (that is, those in status before the LIMIT statement was executed) in status.

INVERTED

Indicates that children should be listed before their parents. By default, children are listed after their parents.

NOORIGIN

Excludes the original values from the status. The default is to include original values.

SKIP

Skips n generations for each value in valuelist. For dimensions, when there is no valuelist, it skips n generations for each value in status. For a valueset, when there is no valuelist, it skips n generations for each value in the valueset. This keyword, in combination with DEPTH, is helpful when drilling down; see Example 10-29.

DEPTH

Includes n generations down from each value of valuelist. For dimensions, when there is no valuelist, it includes n generations for each value in status. For a valueset, when there is no valuelist, it includes n generations of each value in the valueset. The default depth value is 99. This keyword, in combination with SKIP, is helpful when drilling down on values.

RUN

Executes a statement, represented as a text expression, every time a group of children is constructed. For example, you can sort each group of children based on information stored in an Oracle OLAP variable. In the following statement, markets are sorted in increasing order based on unit sales every time a group of children is constructed.

LIMIT market TO HIERARCHY RUN 'SORT market a unit.m' USING -
  market.market

Note:

In this example, when you use KEEP or REMOVE instead of TO in your LIMIT statement, the SORT statement would have no effect.

USING 

Specifies the values to use when determining parent values.

parentrel

Specifies the name of the parent relation for the dimension.

To limit a dimension surrogate, use the parent relation for the dimension for which it is a surrogate.

RELATION  

Identifies the beginning of the parent-relation-clause. You use this keyword when parentrel is a multidimensional relation.

QUALIFY relation-dimension-name 

Specifies the name of a dimension of parentrel. The use of this clause varies depending on whether you are coding a LIMIT command or a LIMIT function as described in "Looping Behavior of LIMIT (using parent relation)".

inclusive-val-args

Specifies the values to use when determining the parent values. You can specify any inclusive valuelist argument as described in the syntax of the inclusive-val-args argument for the valuelist clause for LIMIT command. See LIMIT (using values) command for detailed syntax.

CURENT

Specifies that you want to limit to the values of the children of the current value of the dimension. (This is the same as specifying dimension_name +0.)

IFNONE label

Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

Usage Notes

Looping Behavior of LIMIT (using parent relation)

When you do not include a QUALIFY clause, the set of values that this LIMIT puts into status when parentrel is multi-dimensional varies depending on whether or not you are issuing a LIMIT command or a LIMIT function:

  • LIMIT command. All of the in-status values of the related dimensions of parentrel are included in the set of in-status values. If you only want the current values of the related dimensions of parentrel to be included in the set of in-status values, specify a QUALIFY related-dimension CURRENT clause for each of the related dimensions of parentrel.

  • LIMIT function. Only the current values of the related dimensions of parentrel are included in the set of in-status values. If you want all of the in-status values of the related dimensions of parentrel to be included in the set of in-status values, specify a QUALIFY related-dimension related-dimension clause for each of the related dimensions of parentrel.

Examples

Example 10-28 A Simple Drill Down

This example drills down on districts from the region level of the market dimension. First, the market dimension, which has embedded totals at the district, region, and total U.S. level, is limited to the region level data. This LIMIT is done using the relation mlv.market, which is a relation between market and market.level.

Issuing a REPORT mlv.market statement produces the following output, which shows the values of mlv.market.

MARKET         MLV.MARKET
-------------- ----------
Totus          Totus
East           Region
Boston         District
Atlanta        District
Central        Region
Chicago        District
Dallas         District
West           Region
Denver         District
Seattle        District

The following LIMIT statement limits the values of MARKET, and the STATUS statement produces the values currently in status. The output of STATUS is shown following the statements.

LIMIT market TO mlv.market 'Region'
STATUS market
 
The current status of MARKET is:
EAST, CENTRAL, WEST

To drill down on the district level data from the region level, you can use LIMIT with the CHILDREN keyword. The following example uses a parent-relation called market.market to perform the drill down. For each value of the market dimension, this relation contains the name of its parent.

DEFINE market.market RELATION market <market>
LD Self-relation for the Market Dimension

A report of market.market produces the following output.

MARKET         MARKET.MARKET
-------------- -------------
Totus          NA
East           Totus
Boston         Central
Atlanta        East
Central        Totus
Chicago        Central
Dallas         Central
West           Totus
Denver         West
Seattle        West

You can limit market to the children of the East, Central, and West regions by using the CHILDREN keyword with LIMIT.

LIMIT market TO mlv.market 'Region'
Limit market TO CHILDREN USING market.market

A report of market produces the following output.

MARKET
-------------
Boston
Atlanta
Chicago
Dallas
Denver
Seattle

Example 10-29 Drilling Down Using SKIP and DEPT

Consider the following statement.

LIMIT market TO HIERARCHY DEPTH 2 SKIP 1 USING market.market 'Totus'

Oracle OLAP looks in the child-parent relation (market.market) to find the children and the grandchildren (DEPTH 2) of Totus and it discards the first generation (SKIP 1). The resulting status follows.

Totus
Boston
Atlanta
Chicago
Dallas
Denver
Seattle

Note that Totus is included in status. With HIERARCHY, the original values are included in status.

10.9.5 LIMIT NOCONVERT command

The LIMIT command sets the current status list of a dimension and its dimension surrogates, or assigns values to a valueset.

A LIMIT command with the NOCONVERT keyword sets the status of one dimension based on the numeric position of values in a different dimension.

Syntax

LIMIT{dimension | valueset} [concat-component] limit-type -

     NOCONVERT [{unrelated-dimension|numeric-valueset}] -      [IFNONE label]

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values; or a LIMIT function.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A keyword that specifies how Oracle OLAP should modify the current status list. (See the main entry for LIMIT command for a list and descriptions of these keywords.)

NOCONVERT

Sets the status of a dimension based on the numeric position of the specified values in the status list of an another dimension.

unrelated-dimension

Specifies the name of a dimension not related to the dimension being limited. Using this argument specifies that the status of a dimension or valueset is set based on the numeric position of each value in status of the unrelated-dimension. Setting status based on in status values in unrelated dimensions is particularly useful when the two dimensions are in different analytic workspaces (for example, when a one-to-one correspondence exists between the product dimension in two analytic workspaces).

numeric-valueset

Specifies a numeric valueset. When you use this argument, NOCONVERT sets the status based on the numeric values in the valueset. The numeric values represent the positions of the values in the default status of the dimension.

IFNONE label

(For use only within an OLAP DML program) Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

10.9.6 LIMIT command (using POSLIST)

The LIMIT command sets the current status list of a dimension and its dimension surrogates, or assigns values to a valueset.

A LIMIT command with the POSLIST keyword sets the status of a dimension based on the position of the values within that dimension.

Syntax

LIMIT {dimension | valueset} [concat-component] limit-type -

     POSLIST poslist-exp [IFNONE label]

Parameters

dimension

The name of the dimension or dimension surrogate for which you are setting status.

valueset

The name of the valueset for which you are assigning values; or a LIMIT function.

concat-component

The name of the component of the concat dimension whose values are used to determine the limit. (See the main entry for LIMIT command for complete description of this argument.)

limit-type

A standard keyword (documented in the main entry for LIMIT command) that specifies how Oracle OLAP should modify the current status list.

POSLIST poslist-textexp

Sets the status of a dimension based on the position of a value within a dimension. poslist-textexp is a text expression, each line of which is a numeric value that evaluates to a numeric position of the dimension being limited.

IFNONE label

Specifies that program execution should branch to label when the requested status has null status or is based on a related dimension that turns out to have null status (that is, to have no values). (See the main entry for LIMIT command for complete description of this phrase.)

10.10 LIMIT BASEDIMS

The LIMIT BASEDIMS command sets the current status list of one or more base dimensions of a composite, conjoint dimension, concat dimension, or a partition template based on the selected values of that object.

You use LIMIT BASEDIMS to produce a status of dimension values for each dimension that exists in the sparse object's tuples, possibly filtered by some arbitrary input status. You can also use the this command to assign a value to one or more valuesets for the base dimensions.

Values that are in the current status list of a dimension are said to be "in status." The status of the base dimensions of a composite, conjoint dimension, concat dimension, or a partition template is determined by the current status of its base dimensions.

See Also:

For more information on working with dimension status, see "OLAP DML Statements Apply to All of the Values of a Data Object" and LIMIT command

Syntax

LIMIT BASEDIMS {<dimlist>}TO object [ [KEEP] limit-clause ]

Parameters

dimlist

A space-delimited list of objects that identifies the base dimensions for which you want Oracle OLAP to change status and the valuesets for which you want Oracle OLAP to add values. Within dimlist, you can specify the following values:

  • base-dimension-name
  • The name of a base dimension of object.
  • relation-name
  • The name of a relation. When you specify a relation, Oracle OLAP sets the status of the related dimension.
  • valueset-name
  • The name of a valueset for a base dimension; or a LIMIT function. When you specify the name of a valueset, Oracle OLAP assigns a single value to the specified valueset.

The default value of dimlist is the completely expanded list of the base dimensions of object.

object

The name of a composite, a conjoint dimension, a concat dimension, or a partition template object.

KEEP

Specifies that Oracle OLAP performs the selection based on the current dimension status of the base dimensions of the object. KEEP preserves the current order of values among the values that remain in the status.

limit-clause

Specifies how Oracle OLAP should select values from object to modify the current status lists of the base dimensions.

The syntax of limit-clause is the same syntax as any of the non-positional limit-clause arguments in the various forms of the LIMIT command (that is, the syntax of the LIMIT command after the limit-type argument such as "TO"). For the syntax of these arguments, see LIMIT (using values) command, LIMIT using LEVELREL command, LIMIT (using parent relation), LIMIT (using related dimension) command, LIMIT NOCONVERT command, and LIMIT command (using POSLIST).

When this optional argument is not specified, Oracle OLAP sets the status of the base dimensions to the current status of the dimensions.

10.11 LISTBY

The LISTBY program produces a report of the names of all objects in an analytic workspace that are dimensioned by or related to one or more specified dimensions or composites. You can use LISTBY with a dimension or composite in any attached workspace.

Syntax

LISTBY dimensions

Parameters

dimensions

A list of one or more dimensions or composites, separated by spaces. When you list multiple dimensions, all the dimensions must be in the same workspace. LISTBY returns a list of objects that are dimensioned by all the dimensions you specify. When you specify an unnamed composite, use the following format:

LISTBY SPARSE dim1 dim2 ...

Usage Notes

Composites and Conjoint Dimensions

The report produced by LISTBY includes any named or unnamed composite, or conjoint dimension, whose base dimension list includes the dimensions you specify.

The report also includes any object whose dimension list includes a named or unnamed composite that in turn has the specified dimensions as base dimensions.

Examples

Example 10-30 Using LISTBY

LISTBY is used here to list the name of every object that is dimensioned by or related to product. The statement LISTBY product produces the following output.

15 objects dimensioned by or related to PRODUCT
----------------------------------------------------------------
ADVERTISING          DIVISION.PRODUCT     EXPENSE
INDUSTRY.SALES       NAME.PRODUCT         NATIONAL.SALES
PRICE                PRODUCT.MEMO         PRODUCTSET
SALES                SALES.FORECAST       SALES.PLAN
SHARE                UNITS                UNITS.M

Example 10-31 Specifying More Than One Dimension

In this example LISTBY is used to list the name of every object that is dimensioned by or related to both product and market.

LISTBY product market
1 objects dimensioned by or related to PRODUCT, MARKET
----------------------------------------------------------
UNITS.M

10.12 LISTFILES

The LISTFILES command lists all the open files that can be referenced by the FILEQUERY function which includes all files opened by FILEOPEN, OUTFILE, and LOG command.

Syntax

LISTFILES

Examples

Example 10-32 Listing Open Files

The following example shows how to use LISTFILES to see which open files can be referenced by the FILEQUERY function.

DEFINE fil.unit VARIABLE INTEGER
fil.unit = FILEOPEN('report' WRITE)
LISTFILES

These statements produce the following output.

10 w  D:\WINNT35\SYSTEM32\report

10.13 LISTNAMES

The LISTNAMES program produces a report that lists the names of the objects in an analytic workspace. You can limit the list to particular types of objects, and you can have the names for each type of object listed in alphabetical order.

Syntax

LISTNAMES [AW workspace|'*'] [objtype-list|ALL] -      [SORTED|UNSORTED] [LIKE 'pattern']

Parameters

AW workspace
AW '*'

Specifies the name of an attached workspace whose objects you want to list. When you omit the workspace name, LISTNAMES lists the objects in the current workspace. When you use the '*' (asterisk) argument instead of an analytic workspace name, LISTNAMES produces a separate report for each attached workspace.

objtype-list
ALL

Specifies one or more of the following types of objects whose names you want to list: AGGMAP, COMPOSITE, DIMENSION, FORMULA, MODEL, OPTION, PROGRAM, RELATION, VALUESET, VARIABLE, and WORKSHEET. You can include a trailing "S" on any object type, for example, DIMENSIONS. You can list these object types in any order. ALL (the default) specifies that the names of objects of all these types should be listed.

SORTED
UNSORTED

SORTED (the default, abbreviated SORT) specifies that the object names should be sorted alphabetically. UNSORTED (abbreviated UNSORT) specifies that the object names should not be sorted alphabetically.

LIKE 'pattern'

Compares the names of the definitions in an analytic workspace to the text pattern you specify and lists the names that match. A definition name is like a text pattern when corresponding characters match. Besides literal matching, LIKE lets you use wildcard characters to match multiple characters in a string. An underscore (_) character in a pattern matches any single character. A percent (%) character in a pattern matches zero or more characters.

Usage Notes

NAME Dimension

NAME is a special dimension that is used by Oracle OLAP to organize the list of objects in an analytic workspace. Its values are the names of the objects defined in the current workspace. (

You cannot explicitly change the values of the NAME dimension. Instead the values are changed as DEFINE, DELETE, MOVE, or RENAME statements execute. Also, you cannot use a qualified object name to specify the NAME dimension of an analytic workspace that is not the current workspace.

See Also:

LISTNAMES program

Example 10-33 Listing Dimensions

Suppose you want a list of all the dimensions in an analytic workspace. First, use a LIMIT command and the OBJ function to limit the status of the NAME dimension. Then use a STATUS statement to produce a list of dimensions. Because the values returned by OBJ(TYPE) are always in uppercase, you must use 'DIMENSION' (not 'dimension') in the LIMIT statement to get a match. The statements

LIMIT NAME TO OBJ(TYPE) EQ 'DIMENSION'
STATUS NAME

produce the following output.

The current status of NAME is:
PRODUCT, DISTRICT, DIVISION, LINE, REGION, MARKETLEVEL, MARKET,
MONTH, YEAR, QUARTER

Example 10-34 Listing Relations

Suppose you want to see the definitions of all the relations in an analytic workspace. Use the LIMIT command and the OBJ function to select these names. Then use DESCRIBE to produce a list of their definitions. The statements

LIMIT NAME TO OBJ(TYPE) EQ 'RELATION'
DESCRIBE

produce the following output.

DEFINE REGION.DISTRICT RELATION REGION <DISTRICT>
LD REGION for each DISTRICT
 
DEFINE DIVISION.PRODUCT RELATION DIVISION <PRODUCT>
LD DIVISION for each PRODUCT
 
DEFINE MLV.MARKET RELATION MARKETLEVEL <MARKET>
 
DEFINE MARKET.MARKET RELATION MARKET <MARKET>
LD Self-relation for the Market Dimension 

Examples

Example 10-35 Listing of DEMO Workspace Objects

This example lists the dimensions, variables, and relations in the current workspace. The statement

LISTNAMES dimension variable relation

produces the following output for the DEMO workspace.

10 DIMENSIONs      18 VARIABLEs       4 RELATIONs
----------------   ----------------   ----------------
DISTRICT           ACTUAL             DIVISION.PRODUCT
DIVISION           ADVERTISING        MARKET.MARKET
LINE               BUDGET             MLV.MARKET
MARKET             DEMOVER            REGION.DISTRICT
MARKETLEVEL        EXPENSE
MONTH              FCST
PRODUCT            INDUSTRY.SALES
QUARTER            NAME.LINE
REGION             NAME.PRODUCT
YEAR               NATIONAL.SALES
                   PRICE
                   PRODUCT.MEMO
                   SALES
                   SALES.FORECAST
                   SALES.PLAN
                   SHARE
                   UNITS
                   UNITS.M 

10.14 LOAD

The LOAD command loads the definition of a program, formula, or model into memory. It is usually used in startup programs, to save time when a program is first used in a session.

Syntax

LOAD object. . .

Parameters

object. . .

The name of a program, formula, or model.

Usage Notes

Definitions Loaded on First Use

All of the objects in an analytic workspace (except for programs, formulas, and models) are loaded into memory when the analytic workspace is attached. Programs, models, and formulas are loaded into memory when first used or when requested using the LOAD command. The time required for loading is small but perceptible, and an application builder fine-tuning a system might want to preload objects in a startup program so that the application runs up to speed from the beginning of a session.

Effect of Loading Many Objects

Loading too many objects into memory can cause Oracle OLAP to run out of memory when it processes a long statement. It is best to use LOAD sparingly, choosing the objects for maximum effect.

LOAD Does Not Compile Programs

When a program is not compiled, LOAD does not automatically compile it. For best performance, always compile the program and save the compiled code by updating your workspace. Then when you load the program in another session (for example, with an AUTOGO program), the program is ready to run. See the COMPILE command for more information about compilation.

Examples

Example 10-36 Loading Two Programs

The following statement loads the two programs choose.months and sales.rpt.

LOAD choose.months sales.rpt

Example 10-37 Loading All the Programs in an analytic workspace

The following statements load all the programs in the analytic workspace.

LIMIT NAME TO OBJ(TYPE) EQ 'program'
LOAD &VALUES(NAME)

10.15 LOG command

The LOG command starts or stops the recording of a session to a disk file. All lines of input and output are recorded.

Note:

Do not confuse the LOG command with the function of the same name which is a mathematical function.

Syntax

LOG EOF | TRACEFILE | SAVE | {[APPEND] file-name}

Parameters

EOF

Stops recording of the session and closes any opened log record file.

TRACEFILE

Specifies that the session information should be directed to the Oracle trace file, which is identified by the TRACEFILEUNIT option.

SAVE

Forces Oracle OLAP to update the log file. Lines of input and output are not always written to disk as they are generated. Instead, the lines are stored temporarily then written to disk periodically. LOG SAVE effectively issues the LOG EOF and LOG APPEND file-name commands which ensures that all appropriate lines are written to disk by closing the log file and reopening it. Additional lines of input and output are appended to the file.

APPEND

Specifies that the record of your session should be added to the end of an existing disk file. When you omit this argument, the new output replaces the current contents of the file.

file-name

A text expression that is the name of the file to which session information should be written. Unless the file is in the current directory, you must include the name of the directory object in the name of the file.

Note:

Directory objects are defined in the database, and they control access to directories and file in those directories. You can use a CDA statement to identify and specify a current directory object. Contact your Oracle DBA for access rights to a directory object where your database user name can read and write files.

Usage Notes

Automatic Closing of a Log File

When you use LOG file-name to start recording in a disk file, LOG closes any log record file that is currently open. LOG issues this close even when the new file is not actually opened (as when you specify an invalid file name in the LOG statement).

Examples

Example 10-38 Keeping a Log File

To record your session in a file called session.log, use a statement like the following.

LOG 'session.log' 

10.16 MAINTAIN

The MAINTAIN command enters and maintains the values of dimensions, composites, and partition template objects.

Note:

You can also issue a MAINTAIN statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN object {ADD|DELETE|RENAME|MOVE|MERGE} args

The keywords that you can use with the MAINTAIN command varies by object:

  • MAINTAIN dimension {ADD|DELETE|RENAME|MOVE|MERGE} args

    The keyword that you can use varies by the type of dimension that you want to maintain:

    • With a non-concat dimension, you can use the ADD, DELETE, RENAME, MOVE, or MERGE keywords to add, delete, rename, move, or merge non-concat dimension values. You can also use the ADD keyword to add temporary calculated members to a dimension.

    • With a concat dimension, you can only use the MOVE keyword to move concat dimension values.

  • MAINTAIN composite {ADD|DELETE|MERGE} args

  • MAINTAIN partition-template {ADD|DELETE|MOVE} args

The specific syntax varies by keyword. Consequently, there are separate topics for each keyword of the MAINTAIN command:

For information that applies to the MAINTAIN command in general, see the Usage Notes in this topic.

Usage Notes

Triggering Program Execution When MAINTAIN Executes

Using the TRIGGER command, you can make the execution of a MAINTAIN statement an event that automatically executes an OLAP DML program. See "Trigger Programs" for more information.

Automatic Status Reset

When you use the ADD, DELETE, MERGE, or MOVE keyword to maintain a dimension or composite whose status is not currently ALL, the MAINTAIN command automatically resets status to ALL before performing the maintenance function. However, when you use the RENAME keyword to maintain a dimension whose status is not currently ALL, the MAINTAIN command does not change the status of the dimension.

Maintain Permission

You cannot perform maintenance on a dimension when a PERMIT MAINTAIN statement denies maintain permission for the dimension. Maintain permission is implicitly denied whenever read permission is restricted for a dimension, even when you specify maintain permission for the dimension. (See the PERMIT command.)

Maintaining Dimensions in Multiwriter Analytic Workspaces

Keep the following points in mind when maintaining dimensions in an analytic workspace that is attached in multiwriter mode:

  • You cannot update a variable when any of its dimensions have been acquired and modified.

  • Reverting a dimension after adding dimension values is not recommended because it can result in suboptimal space allocation for variables dimensioned by the dimension.

  • When an acquired variable is dimensioned by an acquired dimension that has been maintained, you cannot update the variable until the dimension is updated or released.

  • You do not have to acquire composites in order for them to be maintained, Oracle OLAP automatically performs concurrent dimension maintenance for the composite dimensions.

Also, before you can maintain dimensions in an analytic workspace that is attached in multiwriter mode, you must first acquire the dimension using an ACQUIRE statement.

For example, assume that user A and user B both have to perform what-if computations on both actuals and budget. After performing the what-if computations, user A needs to modify actuals and B needs to modify budget. Finally, both user A and user B have to add a new time dimension value and add data corresponding to that new dimension value to actuals or budget.

User A issues the following OLAP DML statements.

AW ATTACH myworkspace MULTI
...make modifications 
ACQUIRE actuals
...make more modifications
ACQUIRE time
MAINTAIN time ADD 'Y2002'
actuals (time 'Y2002', ...) = ...
UPDATE MULTI actuals, time
COMMIT
RELEASE actuals, time
AW DETACH myworkspace

User B issues the following OLAP DML statements.

AW ATTACH myworkspace MULTI
...make modifications 
ACQUIRE budget
...make more modifications
ACQUIRE time--> failed
ACQUIRE RESYNC time WAIT
MAINTAIN time ADD 'Y2003'
budget (time 'Y2003', ...) = ...
UPDATE MULTI budget, time
COMMIT
RELEASE budget, time
AW DETACH myworkspace

MAINTAIN and Dimension Surrogates

You cannot use a MAINTAIN statement on a dimension surrogate. You can only use MAINTAIN to add values to or delete them from a dimension. However, when you add or delete a dimension value, then Oracle OLAP adds or removes a position from surrogates of that dimension. When you add a position to a dimension, the corresponding position in a surrogate for that dimension receives an NA value.

Maintaining a Concat Dimension

A concat dimension contains the values of its component dimensions. You do not directly add, merge, or delete the values of a concat dimension using MAINTAIN statements. Instead, when you add, merge, or delete values from a component dimension of the concat, Oracle OLAP automatically adds or deletes the values from the concat dimension. You can use the MOVE keyword of the MAINTAIN command to change the order of the values of a concat dimension.

10.16.1 MAINTAIN ADD

The MAINTAIN command with the ADD keyword adds new TEXT, ID, and INTEGER values to a non-concat dimension, composite, or partition; or adds a new temporary calculated member to a dimension.

Note:

You can also issue a MAINTAIN ADD for TEXT, ID, and INTEGER Values statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program one time for each value; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

The syntax for using the MAINTAIN command with the ADD keyword depends on the type of the object being maintained and whether you are adding a permanent or temporary member.

For this reason, the following separate entries are provided for MAINTAIN ADD:

10.16.1.1 MAINTAIN ADD for TEXT, ID, and INTEGER Values

The MAINTAIN command with the ADD keyword adds new TEXT, ID, or INTEGER values to a non-concat dimension or composite.

Note:

You can also issue this MAINTAIN ADD statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program one time for each value in valuelist; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN composite|dimension ADD valuelist [FIRST|LAST|BEFORE position|AFTER position]

Parameters

dimension

A non-concat dimension, already defined in an attached analytic workspace.

composite

A composite. When the composite is a named composite, it must be defined in an attached analytic workspace. When the composite is unnamed, it must have been used in defining an object in an attached analytic workspace. Use the SPARSE keyword to refer to an unnamed composite (for example, SPARSE <market product>).

ADD valuelist

Specifies that the values in valuelist are to be added to the dimension or composite:

  • When you use this argument to add values to a composite or a dimension of type TEXT or ID, the valuelist can be text literals or a TEXT or ID expression. When it is a multiline text expression, each element (line) is treated as a separate value.Do not add null dimension values (empty single quotes) or values that consists of spaces only, because there is no way you can refer to such values in the future.

  • When dimension is INTEGER, valuelist can be an INTEGER quantity, such as 5 or 100.

FIRST
LAST

Specify the logical position at which dimension values are added. FIRST indicates that the new values are inserted before any existing values. LAST indicates that new values are added after the current values. LAST is the default. When you are adding a certain quantity of INTEGER values to an INTEGER dimension, that quantity of INTEGER values are added before or after any existing INTEGER values (depending on your specification), and all the INTEGER values in the resulting series are automatically adjusted into simple numeric order.

All values specified before the keyword FIRST or LAST are placed in that position, not just the one value immediately preceding the keyword in your statement.

BEFORE position
AFTER position

Specify a position before or after which the dimension values are to be added. For position you can specify an existing dimension value, a character expression whose value is an existing dimension value, or an INTEGER expression whose value represents the position of a dimension value. When you are adding a certain quantity of INTEGER values to an INTEGER dimension, that quantity of INTEGER values are added before or after the INTEGER position you specify, and the INTEGER values in the whole of the resulting series are automatically adjusted into simple numeric order.

All values specified before the keywords BEFORE or AFTER are placed in that position, not just the one value immediately preceding the keyword in your statement.

Usage Notes

Performance When Using MAINTAIN ADD BEFORE or AFTER position

The cost performance of using MAINTAIN ADD BEFORE or MAINTAIN MOVE AFTER statements depends on the number of values in the dimension rather than the number of values being added. Consequently, instead of issuing many of these statements one after another:

  1. Add the values using simple MAINTAIN ADD statements

  2. Set the status of the dimension status to the values you are concerned with.

  3. Order the added values, by issuing a single MAINTAIN MOVE dimension value statement

Adding Values to an INTEGER Dimension

When you use MAINTAIN to add values in an INTEGER dimension, the values are renumbered to keep the normal sequence of INTEGER values (1, 2, 3, ...).

Conjoint Dimensions and Composites

Each value of a conjoint dimension or composite is a combination of values from each of the dimensions (and composites, if any) in its dimension list. To add values to a conjoint dimension or composite, specify each value combination enclosed in angle brackets. The values in a given combination must be in the same order as the dimensions and composites in the definition of the conjoint dimension or composite. Each dimension value in the combination must already exist as a value in the corresponding base dimension. However, when a composite value in the combination does not exist, Oracle OLAP automatically adds the value to the appropriate composite.

Examples

Example 10-39 Adding Values to a TEXT Dimension

This statement adds Omaha and Seattle to the end of the dimension values for the city dimension.

MAINTAIN city ADD 'Omaha' 'Seattle'

This statement adds Atlanta at the beginning of the list of cities and inserts Peoria after Omaha.

MAINTAIN city ADD 'Atlanta' FIRST, 'Peoria' AFTER 'Omaha'

Here the value of the TEXT variable textvar is inserted before the fifth dimension value of city. When you assign the value Columbus to textvar, you must make sure it is in mixed case, because you want the dimension value to be in mixed case.

textvar = 'Columbus'
MAINTAIN city ADD textvar BEFORE 5

Example 10-40 Adding Values to a Conjoint Dimension

The following is an example of adding values to a conjoint dimension.

DEFINE proddist DIMENSION <product, district>
MAINTAIN proddist ADD <'Tents' 'Boston'> <'Footwear' 'Denver'>

You can also assign a value of a base dimension to a text variable and use the name of the variable inside the angle brackets.

prodname = 'Canoes'
distname = 'Seattle'
MAINTAIN proddist ADD <prodname, distname>
10.16.1.2 MAINTAIN ADD for DAY, WEEK, MONTH, QUARTER, and YEAR Values

The MAINTAIN command with the ADD keyword adds new values to a dimension of type DAY, WEEK, MONTH, QUARTER, and YEAR.

Syntax

MAINTAIN dimension ADD {valuelist|{n PERIODS FIRST}|{n PERIODS LAST}}

Parameters

dimension

A non-concat dimension, already defined in an attached analytic workspace.

ADD valuelist

Specifies that the values in valuelist are to be added to the dimension. When dimension is of type DAY, WEEK, MONTH, QUARTER, or YEAR, then valuelist can be text constants or a TEXT, ID, or DATE expression. When the values are TEXT, they can be in the format specified by the VNF (value name format) for the dimension (or in the default format for the type of dimension you are maintaining when the dimension does not have a VNF) or in a valid input style for date values. When the values are specified as a TEXT expression, each element or line is treated as a separate value.

When the values are in the format specified by the VNF or in the default format for this type of dimension, each value explicitly indicates the time period you want to add. For example, assume that the VNF for a month dimension is '<MTXT><YY>'. In this case, the value JAN99 represents the month January 1999.

When you specify a value for a DAY, WEEK, MONTH, QUARTER, or YEAR dimension as a date, you must provide only the date components that are relevant for the type of dimension you are maintaining. For a DAY or WEEK dimension, you must supply the day, month, and year components. For a MONTH or QUARTER dimension, you must supply only the month and year (for example, 'JUN98' or '0698' for June 1998). For a YEAR dimension, you must specify only the year (for example, '98' for 1998). For information about the valid input styles for dates, see the DATEORDER option.

When you add a dimension value by specifying a DATE expression or a TEXT value that represents a complete date, you can specify any date that falls within the time period you want to add. For example, to add the month January 1999, you can specify any date from '01JAN99' through '31JAN99'. Oracle OLAP uses the DATEORDER option to resolve any ambiguities.

When adding values to a DAY, WEEK, MONTH, QUARTER, or YEAR dimension that does not yet have values, you must specify only the first and last values you want to add for the dimension. Oracle OLAP automatically fills in the gaps with appropriate values for the intervening time periods.

When a DAY, WEEK, MONTH, QUARTER, or YEAR dimension already has values, you can add values only at the beginning or the end of the existing list. To add values, you must specify only the first or last value you want to add. Oracle OLAP automatically fills in the gap between the existing list and the value you specify.

n PERIODS FIRST
n PERIODS LAST

Specifies the number of periods to add at the beginning or end of an existing list of dimension values.

Examples

Example 10-41 Adding Values to Dimension of Type QUARTER

In this example you define a new QUARTER dimension, called qtr, and you add dimension values for the quarters in 1998 and 1999. You must only add the first and last dimension values you want. Oracle OLAP fills in the intervening values. To add the first and last quarters, you can specify any dates that fall within those quarters.

DEFINE qtr DIMENSION QUARTER
MAINTAIN qtr ADD '01jan98' '31dec99'
10.16.1.3 MAINTAIN ADD SESSION

The MAINTAIN command with the ADD SESSION keywords adds a temporary calculated member to a dimension and applies it to the specified objects; or applies a previously-defined calculated member to the specified objects. The calculated member and its definition do not persist from session to session; both are deleted after the session in which they are created.

Syntax

MAINTAIN dimension ADD SESSION member_name [= calculation] -       [STEP DIMENSION (stepdim...)][apply-to]

where:

  • calculation is one of the following:

    • model-equation
    • AGGREGATION (dimension-members....)
  • apply-to specifies the basis on which the custom aggregation is added using one of the following phrases:

    • APPLY TO AGGMAP aggmaps
    • APPLY FOR VARIABLE variables
    • APPLY WITH RELATION relations

Parameters

dimension

A dimension that is already defined in an attached analytic workspace. You can specify any type of dimension for dimension except a non-unique concat dimension or a base dimension of either a unique or non-unique concat dimension.

ADD SESSION

ADD SESSION indicates maintenance of a temporary calculated member.

member-name

Specifies the name of the temporary calculated member.

=

Indicates that you are defining a new calculated member.

model-equation

A text expression that specifies the calculation used as a dynamic model to calculate custom member values. (See the SET command for more information about model equations.)

AGGREGATION

Indicates that the temporary calculated member is added as a custom aggregation using the specified dimension members. This clause effectively modifies the RELATION statement of aggmap objects that are the aggregation specification for variables dimensioned by dimension. Consequently, a MAINTAIN ADD SESSION statement that contains an AGGREGATION clause must also contain an APPLY WITH RELATION clause.

dimension-members

A text expression that specifies one or more dimension values to be used by the custom aggregation. When using a literal to specify multiple dimension members, separate the values with commas

STEP DIMENSIONS

Indicates that the calculation is a time-series function.

stepdim

A text expression that specifies the dimension along which the time-series function is calculated. When using a literal to specify multiple dimension names, separate the names with commas.

APPLY TO AGGMAP

Indicates that the calculated temporary member is added only to dimensions used by the specified aggmap objects.

aggmaps

A text expression that specifies the name of one or more aggmap objects to which the temporary calculated member is added. When using a literal to specify multiple aggmap objects, separate the names with commas. The temporary calculated member is added to each of the specified aggmap objects.

APPLY FOR VARIABLE

Indicates that the temporary calculated member is added only to dimensions used by the default aggmap objects for the specified variables.

variables

A text expression that specifies the one or more variable names for which the temporary calculated member is added to. When using a literal to specify multiple variable names, separate the names with commas. The temporary calculated member is added to the default aggmap object of each specified variable.

Note:

When a specified variable does not have a default aggmap, using this clause generates an error. Use AGGMAP SET or $AGGMAP to specify a default aggmap for the variable.

APPLY WITH RELATION

Indicates that the temporary calculated member is added dimensions used by the aggregation specifications that contain a RELATION statement for the specified relation.

relation

A text expression that specifies the name of the relation for which there must be a RELATION statement in the AGGMAP statement.

Usage Notes

Finding Out Information About Temporary Calculated Members

Once you have added a temporary calculated member using a MAINTAIN statement, you can use AGGMAPINFO to discover the temporary calculated members you have added, the equations used to calculate members, and the dimension members used in the right-hand side of equations used to calculate custom members.

Examples

Example 10-42 Creating Calculated Dimension Members with Aggregated Values

Assume that an analytic workspace has a dimension named letter and a variable named my_quantity with the following definitions and permanent values.

DEFINE letter DIMENSION TEXT
DEFINE my_quantity VARIABLE DECIMAL <letter>

LETTER                  MY_QUANTITY
-------------- ------------------------------
A                                       10.00
B                                      100.00

You can define temporary dimension members for the letter dimension and aggregate data in my_quantity for those members following these steps:

  1. Determine the aggregation that you want to perform and define and populate the necessary supporting objects.

    1. Create an empty child-parent relation for the letter dimension

      DEFINE letter.parentrel RELATION letter <letter>
      
      LETTER                LETTER.PARENTREL
      -------------- ------------------------------
      A              NA
      B              NA
      
    2. Define a simple model to be used to calculate values associated with the letter dimension

      DEFINE my_model MODEL
      MODEL 
        DIMENSION letter
       END
      
    3. Define and compile a simple aggmap to be used to calculate my_quantity values associated with the letter dimension

      DEFINE my_aggmap AGGMAP
      AGGMAP 
         RELATION letter.parentrel PRECOMPUTE(NA)
         MODEL my_model PRECOMPUTE(NA)
        END
      
      COMPILE my_aggmap
      
    4. Define a variable to contain the definition for the custom aggregation, This new variable is the same as my_quantity except that has my_aggmap as its default aggmap.

      DEFINE my_quantity_definition VARIABLE DECIMAL <letter>
      
      CONSIDER my_quantity_definition
      PROPERTY '$AGGMAP' 'my_aggmap'
      
      REPORT my_quantity_definition
      
      LETTER             MY_QUANTITY_DEFINITION
      -------------- ------------------------------
      A                                          NA
      B                                          NA
      
  2. Add temporary members to the letter dimension and specify how variable values for those members are to be calculated.

    MAINTAIN letter ADD SESSION 'C' = 'A' * 'B'
    MAINTAIN letter ADD SESSION 'D' = AGGREGATION('A', 'B') -
        APPLY TO AGGMAP my_aggmap
    MAINTAIN letter ADD SESSION 'E' = 'C' + 'D' -
        APPLY WITH RELATION letter.parentrel
    MAINTAIN letter ADD SESSION 'F' = 10 * 'E' -
        APPLY FOR VARIABLE my_quantity_definition
    

    A report of the letter dimension shows the new dimension members.

    LETTER
    --------------
    A
    B
    C
    D
    E
    F
    
  3. Aggregate my_quantity using the aggmap object named my_aggmap.

    REPORT AGGREGATE(my_quantity USING my_aggmap)
    
                    AGGREGATE(MY_QUANTITY USING
    LETTER                   MY_AGGMAP)
    -------------- ------------------------------
    A                                       10.00
    B                                      100.00
    C                                    1,000.00
    D                                      110.00
    E                                    1,110.00
    F                                   11,100.00
    

Assume now that you issue the UPDATE and COMMIT statements to update and commit your analytic workspace. Then you detach the analytic workspace and end your session.

Later you start a new session and attach the same analytic workspace. When you ask for a description of the analytic workspace you can see that all of the objects that were in the analytic workspace when the UPDATE was issued still exist.

DEFINE LETTER DIMENSION TEXT

DEFINE LETTER.PARENTREL RELATION LETTER <LETTER>

DEFINE MY_QUANTITY VARIABLE DECIMAL <LETTER>

DEFINE MY_MODEL MODEL
MODEL
DIMENSION letter
END

DEFINE MY_AGGMAP AGGMAP
AGGMAP
RELATION letter.parentrel PRECOMPUTE(NA)
MODEL my_model PRECOMPUTE(NA)
END

DEFINE MY_QUANTITY_DEFINITION VARIABLE DECIMAL <LETTER>

However, when you report on the letter dimension and the my_quantity variable, the temporary dimension members that you added in the previous session and their related values in the my_quantity variable do not exist.

LETTER
--------------
A
B

REPORT letter.parentrel

LETTER                LETTER.PARENTREL
-------------- ------------------------------
A              NA
B              NA

REPORT my_quantity

LETTER                  MY_QUANTITY
-------------- ------------------------------
A                                       10.00
B                                      100.00

LETTER             MY_QUANTITY_DEFINITION
-------------- ------------------------------
A                                          NA
B                                          NA

REPORT AGGREGATE(my_quantity USING my_aggmap)

                AGGREGATE(MY_QUANTITY USING
LETTER                   MY_AGGMAP)
-------------- ------------------------------
A                                       10.00
B                                      100.00
10.16.1.4 MAINTAIN ADD TO PARTITION

The MAINTAIN ADD TO PARTITION statement adds previously-populated dimension or composite values to a partition of a previously-defined partition template object.

Tip:

Use MAINTAIN MOVE TO PARTITION to maintain partition values when you have already populated a partitioned variable.

Syntax

MAINTAIN partition-template ADD TO PARTITION partition valuelist

Parameters

partition-template

A text expression that is the name of a previously-defined partition template object.

ADD TO PARTITION

Specifies that values are to be added to the partition.

partition

A text expression that is the name of a previously-defined partition in the partition template specified by partition-template.

valuelist

Text literals or a TEXT or ID expression specifying the values to be added. When it is a TEXT expression, each element (line) is treated as a separate value. The values in the expression are added exactly as they are typed.

For a concat dimension, you can specify a value of the concat dimension, or the name of a component dimension and a value or position of that dimension. You can use the values of a dimension surrogate as the values of value.

Note that you cannot partition along an INTEGER dimension.

TO

Indicates a range of values.

Examples

For an example of adding values to a partition, see Example 10-48.

10.16.2 MAINTAIN DELETE

The MAINTAIN command with the DELETE keyword deletes members from non-concat dimensions and composites; or deletes the data of previously-partitioned variables from one partition to another as it changes the dimension or composite values defined for a partition in the partition template which the variables are dimensioned.

Note:

You can also issue a MAINTAIN DELETE statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

The syntax for using the DELETE keyword of the MAINTAIN command to delete members varies depending on the type of object from which you are deleting the members. For this reason, the following separate entries are provided for MAINTAIN DELETE:

10.16.2.1 MAINTAIN DELETE dimension

The MAINTAIN command with the DELETE keyword deletes dimension members from non-concat dimensions.

Note:

You can also issue a MAINTAIN DELETE statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN dimension DELETE limit-clause

Parameters

dimension

A non-concat dimension, already defined in an attached analytic workspace, whose values are to be deleted.

Note:

You cannot use a dimension surrogate as the dimension argument of a MAINTAIN DELETE command. However, you can use a dimension surrogate as a value within the limit-clause parameter.

limit-clause

Specifies the values to delete from the dimension.

The syntax of limit-clause is the same syntax as any of the limit-clause arguments in the various forms of the LIMIT command (that is, the syntax of the LIMIT command after the limit-type argument such as "TO"). For the syntax of these arguments, see LIMIT (using values) command, LIMIT using LEVELREL command, LIMIT (using parent relation), LIMIT (using related dimension) command, LIMIT NOCONVERT command, and LIMIT command (using POSLIST).

Usage Notes

Deleting Temporary Calculated Members From Dimensions

When you use a MAINTAIN DELETE statement to delete a temporary calculated member, Oracle OLAP:

  1. Deletes the member from the dimension.

  2. Removes the calculation from all aggmap objects that currently contain the corresponding calculation.

Deleting Values in an Integer Dimension

When you use MAINTAIN to delete values in an INTEGER dimension, the values are renumbered to keep the normal sequence of INTEGER values (1, 2, 3, ...).

Examples

Example 10-43 Deleting Dimension Values by Value

This statement deletes Omaha and Newark from the values for city.

MAINTAIN city DELETE 'Omaha' 'Newark'

Example 10-44 Deleting the First Five Values of a Dimension

In this example, you use the INTEGER variable intvar to remove the first five cities from the dimension city.

intvar = 5
MAINTAIN city DELETE FIRST intvar

Example 10-45 Deleting Dimension Values Based on a Boolean Expression

Here you remove from city all those cities with a population of less than 75,000 people. You use the variable population.c, which contains the population for each city.

MAINTAIN city DELETE population.c LT 75000

Example 10-46 Deleting Dimension Values Using Surrogate to Specify Values

Assume that prodid is a NUMBER dimension and prodtype is a TEXT dimension surrogate for prodid. Assume also that the values of prodid are 17, 40, and 56. The values of prodtype are Two-Person Tent, Three-person Tent, and Four-person Tent. The following statement deletes a value from prodid and from its surrogate.

MAINTAIN prodid DELETE prodid(prodtype 'Three-Person Tent')

Example 10-47 Deleting Related MONTH Values

In this example, you use the related dimension quarter to remove values of the dimension month. All months related to the values of quarter currently in the status are deleted.

LIMIT quarter TO FIRST 1

MAINTAIN month DELETE quarter

10.16.2.2 MAINTAIN DELETE composite

The MAINTAIN command with the DELETE keyword deletes dimension members from composites.

Syntax

MAINTAIN composite DELETE comp-arg

where comp-arg is one of the following constructs:

  • valuelist
  • ALL
  • base-dim [valuelist]
  • boolean-expression
  • {TOP | BOTTOM} BASEDON exp
  • {TOP | BOTTOM} n-percent PERCENTOF expression
  • LONGLIST

Parameters

composite

A composite whose values are to be deleted. When the composite is a named composite, it must be defined in an attached analytic workspace. When the composite is unnamed, it must have been used in defining an object in an attached analytic workspace.

Use the SPARSE keyword to refer to an unnamed composite (for example, SPARSE <market product>).

valuelist

Specifies one or more values to be deleted from the composite. The valuelist can be text constants or a text expression.

ALL

Deletes all composite values, but does not delete the definition of the composite itself.

base-dim [valuelist]

Deletes the values that include the listed values of a base dimension of the composite. The argument valuelist can be one value, a list of values, or a range of values (using TO to specify an inclusive range). You cannot use position numbers to specify a range of values. When you omit valuelist, Oracle OLAP deletes all values that include base-dim values currently in status.

boolean-expression

Deletes all composite values for which the Boolean expression is TRUE. The boolean-expression must be dimensioned by the dimension or the composite from which you the values deleted. When it has additional dimensions, their status must each be limited to one value.

TOP n BASEDON exp
BOTTOM n BASEDON exp

Deletes the top or bottom n values based on the highest (TOP) or lowest (BOTTOM) values in exp. The expression must be dimensioned by the composite from which you the values deleted. When it has additional dimensions, their status must each be limited to one value.

BOTTOM n-percent PERCENTOF expression
TOP n-percent PERCENTOF expression

Deletes values by finding the top or bottom performers based on a criterion. This construction sorts values and deletes them based on their contribution, by percentage, to an expression.

LONGLIST

Indicates a long list (up to 2,000 values) of individual values to delete. When there are fewer than 300 values, LONGLIST is not needed.

10.16.2.3 MAINTAIN DELETE FROM PARTITION

The MAINTAIN DELETE FROM PARTITION command deletes the data of previously-partitioned variables from one partition to another as it changes the dimension or composite values defined for a partition in the partition template which the variables are dimensioned.

Tip:

Use MAINTAIN MOVE TO PARTITION to maintain partition values when you have already populated a partitioned variable.

Syntax

MAINTAIN partition-template DELETE FROM PARTITION partition { dim-arg| comp-arg}

Parameters

partition-template

A text expression that is the name of a previously-defined partition template object.

partition

A text expression that is the name of a previously-defined partition in the partition template specified by partition-template.

DELETE FROM PARTITION

Specifies that values are to be deleted from the partition and from partitioned variables dimensioned using a partition template that includes the partition.

dim-args

Specifies the values of a dimension that to use when deleting partitioned variable values and when redefining the values that are in the partition You can use any of the constructs specified for the dim-arg argument in MAINTAIN DELETE dimension.

comp--args

Specifies the values of a composite to use when deleting partitioned variable values and when redefining the values that are in the partition You can use any of the constructs specified for the comp-arg argument in MAINTAIN DELETE composite.

Examples

Example 10-48 Adding and Deleting Partition Values

Assume that you have defined the following objects in your analytic workspace. on

DEFINE time DIMENSION TEXT
DEFINE time_parentrel RELATION time <time>
DEFINE product DIMENSION TEXT
DEFINE partition_sales_by_year PARTITION TEMPLATE <time product> -
   PARTITION BY LIST (time) -
    (PARTITION time_2004 VALUES ('2004', 'Dec2004', 'Jan2004', '31Dec2004', - 
          '01Dec2004', '31Jan2004', '01Jan2004') <TIME PRODUCT> -
     PARTITION time_2003 VALUES ('2003', 'Dec2003', 'Jan2003', '31Dec2003', -
         '01Dec2003', '31Jan2003', '01Jan2003') <TIME PRODUCT> -
     PARTITION time_2002 VALUES ('2002', 'Dec2002', 'Jan2002', '31Dec2002', -
         '01Dec2002', '31Jan2002', '01Jan2002') <TIME PRODUCT>)

Assume that instead of having all sales values dimensioned levels by all time values of a year in a partition, you want to have partitions by days and by summary time values (month and year). To change partition_sales_by_year to reflect this new partitioning scheme, you issue the following statements.

"Create the new partition
CHGDFN partition_sales_by_year DEFINE -
         (PARTITION partition_month_years VALUES () <time product>)
"Delete the values for months and years from the partitions for years
MAINTAIN partition_sales_by_year DELETE FROM PARTITION time_2004 '2004'- 
        'Dec2004' 'Jan2004'
MAINTAIN partition_sales_by_year DELETE FROM PARTITION time_2003 '2003'-
        'Dec2003''Jan2003'
MAINTAIN partition_sales_by_year DELETE FROM PARTITION time_2002 '2002'-
       'Dec2002' 'Jan2002'
"Add the month and year values to the new partition for summary values
MAINTAIN partition_sales_by_year ADD TO PARTITION partition_month_years '2004'-
      'Dec2004' 'Jan2004' '2003' 'Dec2003''Jan2003' '2002' 'Dec2002' 'Jan2002'

The partition_sales_by_year partition template object now has the following definition.

DEFINE PARTITION_SALES_BY_YEAR PARTITION TEMPLATE <TIME PRODUCT> -
   PARTITION BY LIST (TIME) -
    (PARTITION TIME_2004 VALUES ('31Dec2004', '01Dec2004', '31Jan2004', -
       '01Jan2004') <TIME PRODUCT> -
     PARTITION TIME_2003 VALUES ('31Dec2003', '01Dec2003', '31Jan2003', -
       '01Jan2003') <TIME PRODUCT> -
     PARTITION TIME_2002 VALUES ('31Dec2002', '01Dec2002', '31Jan2002', -
       '01Jan2002') <TIME PRODUCT> -
     PARTITION PARTITION_MONTH_YEARS VALUES ('2004', 'Dec2004', 'Jan2004', -
       '2003', 'Dec2003', 'Jan2003', '2002', 'Dec2002', 'Jan2002')-
         <TIME PRODUCT>)

10.16.3 MAINTAIN MERGE

The MAINTAIN command with the MERGE keyword provides a quick way to make sure all dimension or composite values on a separate list are included in a non-concat dimension or composite. Using the MERGE keyword with the MAINTAIN command automatically adds the new values from the list and ignores the duplicates. This method of entering dimension values can save a significant amount of time when you have a large number of values to enter.

You can use MERGE with dimensions of any data type, including DAY, WEEK, MONTH, QUARTER, and YEAR dimensions. However, because Oracle OLAP provides a quick way of adding values of DAY, WEEK, MONTH, QUARTER, and YEAR dimensions through the ADD keyword, the MERGE keyword may not be as useful with DAY, WEEK, MONTH, QUARTER, and YEAR dimensions as it is with TEXT or ID dimensions.

At the same time as you are merging values into a dimension, you can also update a relation that involves that dimension.

Note:

You can also issue this MAINTAIN MERGE statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program one time for each value in exp; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN dimension|composite MERGE exp [RELATE relation]

dimension

A non-concat dimension, already defined in an attached analytic workspace, whose values are to be entered or changed.

composite

A composite whose values are to be added, deleted, or merged. When the composite is a named composite, it must be defined in an attached analytic workspace. When the composite is unnamed, it must have been used in defining an object in an attached analytic workspace. Use the SPARSE keyword to refer to an unnamed composite (for example, SPARSE <market product>).

exp

Specifies an expression whose values are to be merged with dimension; for example, the name of a dimensioned text variable that contains dimension values, or a single-cell text variable whose value is a multiline list of dimension values. MAINTAIN MERGE ignores any NAs in exp. When dimension is an INTEGER dimension, then exp specifies the number of values that you want in the dimension. When the actual total is less, MAINTAIN MERGE adds enough values to reach the specified total. For example, when an INTEGER dimension has 10 positions, MERGE 5 has no effect; but MERGE 15 would add 5 values.

RELATE relation

Specifies a relation to be updated as new values from exp are merged into dimension. At least one dimension of exp must also appear in the definition of relation. When exp is a single-cell value, you cannot use the RELATE phrase.

Examples

Example 10-49 Using the MERGE Keyword with Composites

Suppose you want to define a composite that is made up of all combinations of the first three values of the product dimension and the first five values of the district dimension. You can efficiently include all 15 values with the following statements.

DEFINE comp_proddist COMPOSITE <product district>
LIMIT product TO FIRST 3
LIMIT district TO FIRST 5
MAINTAIN comp_proddist MERGE <product district>

This method works with conjoint dimensions as well.

10.16.4 MAINTAIN MOVE

A MAINTAIN command with the MOVE keyword has different effects depending on the object on which it operates:

  • When maintaining a dimension, MAINTAIN MOVE changes the position of one or more values in a non-concat dimension or a dimension of type TEXT, ID, or INTEGER or adds previously-populated dimension or composite values to a partition

    Note:

    You can also issue a MAINTAIN MOVE dimension value statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

  • When maintaining a partition, MAINTAIN MOVE moves the data of a previously-partitioned variables from one partition to another as it changes the dimension or composite values defined for a partition in the partition template which the variables are dimensioned.

Syntax

The syntax for using the MAINTAIN command with the MOVE keyword depends on the type of the object being maintained.

For this reason, the following separate entries are provided for MAINTAIN MOVE:

10.16.4.1 MAINTAIN MOVE dimension value

A simple MAINTAIN MOVE statement changes the position of one or more values in a non-concat dimension or a dimension of type TEXT, ID, or INTEGER. You cannot use the MOVE keyword of the MAINTAIN command with composites or with dimensions of type DAY, WEEK, MONTH, QUARTER, or YEAR.

Note:

You can also issue a MAINTAIN MOVE statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN dimension MOVE limit-clause

Parameters

dimension

A non-concat dimension, already defined in an attached analytic workspace, whose values are to be entered or changed. The dimension must be of type TEXT, ID, or INTEGER. You cannot specify a dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR.

limit-clause

Specifies the values you want to move.

The syntax of limit-clause is the same syntax as any of the limit-clause arguments in the various forms of the LIMIT command (that is, the syntax of the LIMIT command after the limit-type argument such as "TO"). For the syntax of these arguments, see LIMIT (using values) command, LIMIT using LEVELREL command, LIMIT (using parent relation), LIMIT (using related dimension) command, LIMIT NOCONVERT command, and LIMIT command (using POSLIST).

Usage Notes

What Effects Performance of MAINTAIN MOVE

The performance cost of issuing a MAINTAIN MOVE command is dependent on the length of the dimension, not on the number of values being moved. Consequently, when moving values in a large dimension, do not issue several MAINTAIN MOVE statements one after another; instead, set up the dimension status to what you want and then issue a single MAINTAIN MOVE command.

Reordering or Sorting Values within a Dimension

When you want to reorder or sort dimension values using a MAINTAIN MOVE statement, to specify that you want to use all of the dimension values that are in status, use the STATUS keyword of the limit-clause argument of LIMIT (using values) command rather than a VALUES command.

Examples

Example 10-50 Moving a Dimension Value to a Specific Position

This statement moves the position of the city Houston to the position following the fifth dimension value.

MAINTAIN city MOVE 'Houston' AFTER 5

Example 10-51 Moving a Dimension Value to the End of the Status List

In this example, you use the TEXT variable textvar to move Seattle to the end of the list of cities.

textvar = 'Seattle'
MAINTAIN city MOVE textvar LAST

Example 10-52 Moving Values of Concat Dimensions

The following statement moves the reg.dist.ccdim concat dimension value <district: 'Denver'> after the concat dimension value <region: 'West'>.

MAINTAIN reg.dist.ccdim MOVE <district: 'Denver'> AFTER <region: 'West'>

The following statement moves the concat dimension value <district: 'Denver'> after the position that corresponds to the first value of the component district dimension. If the first value in the status of district is Atlanta, then <district: 'Denver'> moves after the value <district: 'Atlanta'> in the concat dimension.

MAINTAIN reg.dist.ccdim MOVE <district: 'Denver'> AFTER <district: 1>

The following statement moves the concat dimension value <district: 'Dallas'> after the third value of the concat dimension.

MAINTAIN reg.dist.ccdim MOVE <district: 'Dallas'> AFTER 3
10.16.4.2 MAINTAIN MOVE TO PARTITION

A MAINTAIN MOVE TO PARTITION statement combines both add and move capabilities. You can use a MAINTAIN MOVE TO PARTITION statement to:

  • Add previously-populated dimension or composite values to a partition in the same manner as MAINTAIN ADD TO PARTITION

  • Change the dimension or composite values defined for a partition in the partition template by which the variables are dimensioned and, at the same time, move the data of a previously-partitioned variables dimensioned by those dimensions and composites from one partition to another.

Syntax

MAINTAIN partition-template MOVE TO PARTITION partition value [TO value]

Parameters

partition-template

A text expression that is the name of a previously-defined partition template object.

MOVE TO PARTITION

Specifies that values are to be added to the partition or moved from one partition to another.

partition

A text expression that is the name of a previously-defined partition in the partition template specified by partition-template.

value

Specifies one or more values of a previously-populated dimension or composite. You can specify these values as:

  • A literal value.

  • An expression whose value is a dimension value.

  • For all dimensions except NUMBER dimensions, an INTEGER expression whose value represents the position of a dimension value.

  • A valueset; or a LIMIT function.

For a concat dimension, you can specify a value of the concat dimension, or the name of a component dimension and a value or position of that dimension. You can use the values of a dimension surrogate as the values of value.

TO

Indicates a range of values.

Examples

Example 10-53 Specifying the Values of a Partition Using Valuesets

Assume that you have defined a partition template object with the following definition that does not specify the actual dimension values for each partition.

DEFINE PARTITION_SALES_BY_YEAR PARTITION TEMPLATE <TIME PRODUCT> -
   PARTITION BY LIST (TIME) -
    (PARTITION TIME_2004 VALUES () <TIME PRODUCT> -
     PARTITION TIME_2003 VALUES () <TIME PRODUCT> -
     PARTITION TIME_2002 VALUES () <TIME PRODUCT>)

To specify the values of each partition using valuesets, you take the following steps:

  1. Define a valueset for each year's values.

    DEFINE vs_2004 VALUESET time
    LIMIT vs_2004 to '01Dec2004' '31Dec2004' '01Jan2004''31Jan2004' -
         'Jan2004' 'Dec2004' '2004'
    DEFINE vs_2003 VALUESET time
    LIMIT vs_2003 to '01Dec2003' '31Dec2003' '01Jan2003''31Jan2003' -
         'Jan2003' 'Dec2003' '2003'
    DEFINE vs_2002 VALUESET time
    LIMIT vs_2002 to '01Dec2002' '31Dec2002' '01Jan2002''31Jan2002' -
         'Jan2002' 'Dec2002' '2002'
    
  2. Using MAINTAIN MOVE statements, specify values for the partitions of the partition template.

    MAINTAIN partition_sales_by_year MOVE TO PARTITION time_2004 vs_2004
    MAINTAIN partition_sales_by_year MOVE TO PARTITION time_2003 vs_2003
    MAINTAIN partition_sales_by_year MOVE TO PARTITION time_2002 vs_2002
    

When you issue a DESCRIBE statement, you can see that the description of the partition_sales_by_year partition template now includes the appropriate values of time in each partition definition.

DEFINE PARTITION_SALES_BY_YEAR PARTITION TEMPLATE <TIME PRODUCT> - 
    PARTITION BY LIST (TIME) -
    (PARTITION TIME_2004 VALUES -
('2004','Dec2004','Jan2004', 31Dec2004',01Dec2004','31Jan2004','01Jan2004')-
     PARTITION TIME_2003 VALUES -
('2003','Dec2003','Jan2003', 31Dec2003',01Dec2003','31Jan2003','01Jan2003')-
      PARTITION TIME_2002 VALUES -
                     ('2002','Dec2002','Jan2002', 31Dec2002',01Dec2002','31Jan2002','01Jan2002'))

10.16.5 MAINTAIN RENAME

The MAINTAIN command with the RENAME keyword changes the spelling of one or more dimension values. You cannot use RENAME keyword with a composite or with dimensions of type INTEGER, DAY, WEEK, MONTH, QUARTER, or YEAR.

Note:

You can also issue a MAINTAIN RENAME statement for a surrogate dimension that has a Maintain trigger. In this case, Oracle OLAP only executes the Maintain trigger program; no other action occurs. See "Trigger Programs" for more information for more information. Issuing a MAINTAIN statement for a surrogate dimension that does not have a Maintain trigger, returns an error.

Syntax

MAINTAIN dimension RENAME {value new-value}...

Parameters

dimension

A non-concat dimension of type TEXT or ID that is already defined in an attached analytic workspace and whose values are to be renamed. You cannot specify a dimension of type INTEGER, DAY, WEEK, MONTH, QUARTER, or YEAR.

value

Specifies an existing dimension value to be renamed. You can specify a dimension value, a character expression whose value is a dimension value, or an INTEGER expression whose value represents the position of a dimension value.

new-value

A text constant or a TEXT or ID expression that is the new spelling for the dimension value.

Examples

Example 10-54 Renaming Values of a TEXT Dimension

This statement changes the spelling of the cities Chic and Bost to Chicago and Boston.

MAINTAIN city RENAME 'Chic' 'Chicago' 'Bost' 'Boston'

In this example you use the TEXT variable textvar to change the second city to Atlanta.

textvar = 'Atlanta'
MAINTAIN city RENAME 2 textvar

10.17 MODEL

The MODEL command enters a completely new specification into a new or existing model object. When the model already has a specification, Oracle OLAP overwrites it. To use MODEL to assign an model specification to a model object, the definition must be the one most recently defined or considered during the current session. When it is not, you must first use a CONSIDER statement to make it the current definition.

An alternative to a MODEL statement is an EDIT MODEL statement, which is available only in OLAP Worksheet. An EDIT MODEL statement opens an Edit window in which you can add, delete, or change the specification for a model object.

Adding a specification to a model object is just one step in modeling data. For more information on models, see "OLAP DML Model Objects".

Syntax

MODEL specification

Parameters

specification

A multiline text expression that contains one or more of the following OLAP DML statements:

The maximum number of lines you can have in a model is 4,000. Each statement is a line of the multiline text expression. When coding an ALLOCMAP statement at the command line level, separate statements with newline delimiters (\n), or use JOINLINES.

For a discussion of designing a model specification, see "Model Specification".

Usage Notes

Model Specification

The model specification consists of the following OLAP DML statements:

  1. One of the following:

    • Exactly one INCLUDE statement that specifies the name of another model to include. See "Nesting Models" for more information.

    • One or more DIMENSION (in models) statements coded following the "Guidelines for Writing DIMENSION Statements in a Model".

      Note:

      When a model contains an INCLUDE statement, then it cannot contain any DIMENSION statements. However, the model referenced in the INCLUDE statement or the root model in a hierarchy must contain the DIMENSION statements needed by the parent model(s).

  2. One or more SET commands or equations written following the "Rules for Equations in Models".

    See Also:

    "Dimension Status and Model Equations" for information on how Oracle OLAP processes equations in a model

  3. A final END statement that indicates the end of the model specification. (Omit when coding the specification in an Edit window of the OLAP Worksheet.)

The maximum number of lines you can have in a model is 32,000.

MODEL Statement in an Aggregation Specification

Within an aggmap, you can use a special MODEL statement to execute a predefined model. (See the MODEL (in an aggregation) statement under the AGGMAP command for more information.

Methods of Calculating Data Within a Variable

Both models and aggmap objects calculate data values within a variable based on relationships among dimension members. When a parent-child relationship exists among dimension members (that is, the dimension has a hierarchical structure) and all aggregate values can be calculated using the same method, then you can use a RELATION statement within an aggregation specification to calculate the values. However, when the dimension is not hierarchical and different equations are needed to calculate the values, then you must define a model. You can use a MODEL (in an aggregation) to execute the MODEL within an aggregation specification or you can run a model at the command line using the syntax shown in "Running a Model".

Deleting a Model Specification

You can remove the specification of a model without deleting the model definition. Consider the model with a CONSIDER statement. Then issue a MODEL statement and enter the word END as the model specification.

Examples

Example 10-55 Model Specified in a Program

In the following example, a simple model is created (or overwritten) in a program called myprog. The first line in the program defines or considers the model. The second line contains the MODEL statement, which provides the lines of the model.

This model calculates the line items in a budget. The model equations are based on a line dimension.

DEFINE myprog PROGRAM
PROGRAM
IF NOT EXISTS('myModel')
  THEN DEFINE myModel
  ELSE CONSIDER myModel
MODEL JOINLINES(-
  'DIMENSION line month' -
  'Opr.Income = Gross.Margin - Marketing' -
  'Gross.Margin = Revenue - Cogs' -
  'Revenue = LAG(Revenue, 1, month) * 1.02' -
  'Cogs = LAG(Cogs, 1, MONTH) * 1.01' -
  'Marketing = LAG(Opr.Income, 1, month) * 0.20' -
  'END')
END

Example 10-56 Model from an Input File

This example presents the text of the same simple model, but it is stored in an ASCII disk file called budget.txt.

DEFINE income.budget MODEL
MODEL
DIMENSION line month
Opr.Income = Gross.Margin - Marketing
Gross.Margin = Revenue - Cogs
Revenue = LAG(Revenue, 1, month) * 1.02
Cogs = LAG(Cogs, 1, month) * 1.01
Marketing = LAG(Opr.Income, 1, month) * 0.20
END

To include the income.budget model in your analytic workspace, execute the following statement in which myinpfiles is a directory object.

INFILE 'myinpfiles/budget.txt'

Example 10-57 Creating a Model

Suppose that you define a model, called income.calc, that calculates line items in the income statement.

define income.calc model
ld Calculate line items in income statement

After defining the model, you can use a MODEL statement or the OLAP Worksheet editor to enter the specification for the model. A model specification can contain DIMENSION commands, assignment statements and comments. All the DIMENSION commands must come before the first equation. For the current example, you can specify the lines shown in the following model.

DEFINE INCOME.CALC MODEL
LD Calculate line items in income statement
MODEL
DIMENSION line
net.income = opr.income ‐ taxes
opr.income = gross.margin ‐ (marketing + selling + r.d)
gross.margin = revenue ‐ cogs
END

When you write the equations in a model, you can place them in any order. When you compile the model, either by issuing a COMPILE statement or by running the model, Oracle OLAP identifies the logical order in which the model equations are solved. When the calculated results of one equation are used as input to another equation, then the equations are solved in the order in which they are needed.

To run the income.calc model and use actual as the solution variable, you execute the following statement.

income.calc actual

When the solution variable has dimensions other than the dimensions on which model equations are based, then a loop is performed automatically over the current status list of each of those dimensions. For example, actual is dimensioned by month , division, and line. When division is limited to ALL, and month is limited to OCT96 to DEC96, then the income.calc model is solved for the three months in the status for each of the divisions.

Example 10-58 Building a Scenario Model

Suppose, for example, you want to calculate profit figures based on optimistic, pessimistic, and best-guess revenue figures for each division. The steps for building this scenario model are explained in the following example.

You can call the scenario dimension scenario and give it values that represent the scenarios you want to calculate.

These commands give scenario the values optimistic, pessimistic and bestguess.

DEFINE scenario DIMENSION TEXT
LD Names of scenarios
MAINTAIN scenario ADD optimistic pessimistic bestguess

These commands create a variable named plan dimensioned by three other dimensions (month, line, and division) in addition to the scenario dimension.

DEFINE plan DECIMAL <month line division scenario>
LD Scenarios for financials

For this example, you must enter input data, such as revenue and cost of goods sold, into the plan variable.

For the best-guess data, you can use the data in the budget variable. Limit the line dimension to the input line items, and then copy the budget data into the plan variable.

LIMIT scenario TO 'BESTGUESS'
LIMIT line TO 'REVENUE' 'COGS' 'MARKETING' 'SELLING' 'R.D'
plan = budget

You might want to base the optimistic and pessimistic data on the best-guess data. For example, optimistic data might be fifteen percent higher than best-guess data, and pessimistic data might be twelve percent less than best-guess data. With line still limited to the input line items, execute the following commands.

plan(scenario 'OPTIMISTIC') = 1.15 * plan(scenario 'BESTGUESS')
plan(scenario 'PESSIMISTIC') = .88 * plan(scenario 'BESTGUESS')

The final step in building a scenario model is to write a model that calculates results based on input data. The model might contain calculations very similar to those in the budget.calc model shown earlier in this chapter.

You can use the same equations for each scenario or you can use different equations. For example, you might want to calculate the cost of goods sold and use a different constant factor in the calculation for each scenario. To use a different constant factor for each scenario, you can define a variable dimensioned by scenario and place the appropriate values in the variable. When the name of your variable is cogsval, then your model might include the following equation for calculating the cogs line item.

cogs = cogsval * revenue

By using variables dimensioned by scenario, you can introduce a great deal of flexibility into your scenario model.

Similarly, you might want to use a different constant factor for each division. You can define a variable dimensioned by division to hold the values for each division. For example, when labor costs vary from division to division, then you might dimension cogsval by division and by scenario.

When you run your model, you specify plan as the solution variable. For example, when your model is called scenario.calc, then you solve the model with this statement.

scenario.calc plan

A loop is performed automatically over the current status list of each of the dimensions of plan. Therefore, when the scenario dimension is limited to ALL when you run the scenario.calc model, then the model is solved for all three scenarios: optimistic, pessimistic, and bestguess.

10.17.1 DIMENSION (in models)

The DIMENSION statement at the beginning of a model tells Oracle OLAP the names of one or more dimensions to which the model assigns data or to which it refers in dimension-based equations. A dimension-based equation assigns the results of a calculation to a target that is represented by one or more values of a dimension.

Syntax

DIMENSION dimension1 [, dimensionN]

Parameters

dimension

One or more dimensions, including base dimensions of composites, on which model equations are based. You can specify the name of a dimension surrogate instead of the dimension for which is a surrogate. You can then use the values of the surrogate instead of the values of the dimension.

Usage Notes

Dimension-Based Equations in Models

When an equation (SET) assigns data to a dimension value or refers to dimension values in its calculations, it is called a dimension-based equation. Note that a dimension-based equation does not have to refer to the dimension itself, but only to the values of the dimension. Therefore, when the model contains any dimension-based equations, you must specify the name of each of these dimensions in a DIMENSION statement at the beginning of the model s that Oracle OLAP can determine the dimension to which each dimension value belongs. You can specify the name of a dimension surrogate instead of the dimension for which it is a surrogate. You can then use the values of the surrogate instead of the values of the dimension.

In addition, when a model contains any dimension-based equations, you must supply the name of a solution variable when you run the model. The solution variable is both the source and the target of data for the model. It holds the input data used in dimension-based calculations, and Oracle OLAP stores the calculation results in designated values of the solution variable. The solution variable is generally dimensioned by all the dimensions on which the model equations are based. For example, in a financial application, the model might be based on the line dimension, and the solution variable might be actual, which has line as one of its dimensions.

Dimension-based equations provide flexibility in modeling. Because you do not have to specify the modeling variable until you solve a model, you can run the same model with different solution variables. For example, you might run the same model with the actual variable, with a "best case" budget variable, and with a "worst case" budget variable.

A dimension must be specified in a DIMENSION statement when a dimension-based equation refers to a value of the dimension either as a source of the data used in the calculation or as the target to which the results are assigned. In the following example, Gross.Margin, Revenue, and Cogs are values of the line dimension, so line is specified in a DIMENSION statement.

DIMENSION line
Gross.Margin = Revenue - Cogs

Dimension is a Function Argument

A dimension must be specified in a DIMENSION statement when the dimension is an argument to a function that uses a dimension value as its data source. In the following example, month must be specified in a DIMENSION statement.

DIMENSION line, month
Revenue = lag(Revenue, 1, month) * 1.05

The writer of the preceding model expects to use a solution variable that is dimensioned by line and month. Therefore, when the model is run, the LAG function operates on a solution variable that has the specified time dimension (month) as one of its dimensions. However, because the model compiler cannot anticipate the time dimension of the solution variable, you must specify it in a DIMENSION statement. When you fail to include month in a DIMENSION statement, an error occurs when you attempt to compile the model.

In a function that operates on time-series data (such as MOVINGTOTAL or LAG), the dimension argument is optional when the dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR. For example, you can omit month from the LAG function in the preceding example. However, you must still specify the appropriate time dimension in a DIMENSION statement.

Solution Variable

When you run a model that contains dimension-based equations, you specify a solution variable, which is both the source and the target of data for the model. The solution variable is generally dimensioned by all the dimensions that are listed in the DIMENSION commands used in the model. Or, when a solution variable is dimensioned by a composite, the DIMENSION commands can list base dimensions of the composite. The DIMENSION commands can be explicit in the model or inherited through an included model. See "Incompatibility with INCLUDE".

Working with Composites

When you expect to run a model with a solution variable that has a composite in its dimension list, you can specify a base dimension of the composite in a DIMENSION statement. Your model equations assign results to values of the base dimension. Oracle OLAP automatically creates any new values that are needed in the composite.

Multiple DIMENSION Commands

You can include a separate DIMENSION statement for every dimension referred to or used in dimension-based equations, or you can specify all the dimensions in a single DIMENSION statement.

Location of Commands

You must place all the DIMENSION commands at the beginning of the model, before any equations.

Incompatibility with INCLUDE

When a model contains an INCLUDE statement, it cannot contain any DIMENSION commands. The INCLUDE statement specifies another model to include in the current model. In this case, the current model inherits its DIMENSION commands, if any, from the included model. For more information in including models, see the INCLUDE statement under the MODEL command.

Inherited DIMENSION commands must satisfy all the requirements specified for explicit DIMENSION commands. See "Guidelines for Writing DIMENSION Statements in a Model".

Dimension Order

When multiple dimensions are specified by the DIMENSION commands in a model, the order in which the dimensions are listed is important:

  • When a model equation contains a name that might be a dimension value, Oracle OLAP searches through the dimensions that appear in the model's explicit or inherited DIMENSION commands, in the order you list the dimensions, 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, Oracle OLAP assumes that the value belongs to the dimension specified earliest in a DIMENSION statement. When the name does not match a value of a listed dimension, Oracle OLAP then searches through the variables in the attached workspaces to find a match.

  • When model equations assign results to values of a target dimension, Oracle OLAP constructs code that loops over the values of the other, non-target, dimensions listed in the DIMENSION commands. The non-target dimension listed first in the DIMENSION commands is treated as the slowest-varying dimension. For example, when MONTH is the first non-target dimension listed in a DIMENSION statement and DIVISION is the second, Oracle OLAP loops through all the divisions for the first month, then all the divisions for the second month, and so on.

Guidelines for Writing DIMENSION Statements in a Model

When you write DIMENSION statements, keep these points in mind:

  • In the DIMENSION statements, you must list the names of all the dimensions on which model equations are based. In the following example, gross.margin, revenue, and cogs are values of the line dimension, so line is specified in a DIMENSION statement.

    DIMENSION line
    gross.margin = revenue - cogs
    
  • DIMENSION statements must also list any dimension that is an argument to a function that refers to a dimension value. In the following example, month must be specified in a DIMENSION statement.

    DIMENSION line, month
    revenue = LAG(revenue, 1, month) * 1.05
    
  • When a model equation assigns results to a dimension value, then code is constructed that loops over the values of any of the other nontarget dimensions listed in the DIMENSION statements. The nontarget dimension listed first in the DIMENSION statements is treated as the slowest-varying dimension.

  • A model executes most efficiently when you observe the following guidelines for coordinating the dimensions in DIMENSION statements and the dimensions of the solution variable:

    • List the target dimension of the model as the first dimension in the DIMENSION statements and as the last dimension in the definition of the solution variable.

    • In DIMENSION statements, list the nontarget dimensions in the reverse order of their appearance in the definition of the solution variable. Consequently, the fastest-varying and slowest-varying nontarget dimensions are in the same order in the model and in the solution variable.

  • When the solution variable has dimensions that are not used or referred to in model equations, then do not include them in DIMENSION statements.

  • When your analytic workspace contains a variable whose name is the same as a dimension value, or when the same dimension value exists in two different dimensions, then there could be ambiguities in your model equations. Because you can use a variable and a dimension value in the same way in a model equation, a name might be the name of a variable, or it might be a value of any dimension in your analytic workspace.

  • Your DIMENSION statements are used to determine whether each name reference in an assignment statement is a variable or a dimension value. "Compiling Models" explains how the name references are resolved.

    See Also:

    "OLAP DML Model Objects", SET, and MODEL for information on:

    • Entering statements in a model

    • How to refer to values of dimensions

    • Explanation of how Oracle OLAP constructs code from the statements

    • Explanation of how Oracle OLAP handles the situation in which the solution variable has more dimensions or fewer dimensions than are listed in DIMENSION commands

Examples

Example 10-59 Simplified Model for Budget Estimates

The following statements define a simplified model that estimates budget values for the items on an income statement.

DEFINE income.budget MODEL
LD Model for estimating budget line items
MODEL
dimension line, month
Revenue = 1.05 * LAG(Revenue 1 month)
Gross.Margin = Revenue - Cogs
Opr.Income = Gross.Margin - (Marketing + Selling + R.D)
Net.Income = Opr.Income - Taxes
END

The model equations are based on the line dimension, so line is specified in the DIMENSION statement. The dimension month is the time dimension in the LAG function that operates on REVENUE values, so month is also specified in the DIMENSION statement.

When you run the model, Oracle OLAP loops over the values in the current status of the month dimension.

10.17.2 INCLUDE

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

model

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 10-61.

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

Example 10-60 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

Example 10-61 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

10.18 MODEL.COMPRPT

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.

Syntax

MODEL.COMPRPT

Examples

Example 10-62 A Compilation Report for the income.budget Model

The MODEL.COMPRPT program produces a compilation report that shows the block structure of the model that you specify as the program argument and the order of equations within each block. Each equation is identified with the name of the model and its statement number within that model.

The following statements compile the model and invoke MODEL.COMPRPT.

COMPILE income.budget
MODEL.COMPRPT income.budget

The MODEL.COMPRPT statement produces the following compilation report.

MODEL INCOME.BUDGET <LINE MONTH>
                   BLOCK 1 (SIMPLE)
INCOME.BUDGET  4:  revenue = lag(revenue, 1, month) * 1.02
INCOME.BUDGET  5:  cogs = lag(cogs, 1, month) * 1.01
INCOME.BUDGET  3:  gross.margin = revenue - cogs
                    BLOCK 2 (STEP-FORWARD <MONTH>)
INCOME.BUDGET  6:   marketing = lag(opr.income, 1, month) * 0.20
INCOME.BUDGET  2:   opr.income = gross.margin - marketing
                    END BLOCK 2
                   END BLOCK 1

Example 10-63 A Compilation Report for the income.est Model

The following statement runs the MODEL.COMPRPT program, which produces a compilation report for a model named income.est.

MODEL.COMPRPT income.est

The compilation report contains the following output.

MODEL INCOME.EST <LINE MONTH>
              BLOCK 1 (STEP-FORWARD <MONTH>)
INCOME.EST 5: revenue = lag(revenue,1,month)+2*lag(marketing,1,month)
INCOME.EST 4: gross.margin = revenue - cogs
               BLOCK 2 (SIMULTANEOUS)
INCOME.EST 2:  net.income = opr.income - taxes
INCOME.EST 3:  opr.income = gross.margin - marketing - selling - r.d
INCOME.EST 6:  marketing = .15 * net.income
INCOME.EST 7:  taxes = .3 * opr.income
               END BLOCK 2
              END BLOCK 1

10.19 MODEL.DEPRT

The MODEL.DEPRPT 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.

Syntax

MODEL.DEPRT

Examples

Example 10-64 Producing a Dependency Report

The MODEL.DEPRPT program produces a dependency report that lists the variables and dimension values that are the assignment target and data sources for each model equation. For each equation, the assignment target and each data source is listed on a separate line. When a target or data source is a dimension value, its line is marked by an asterisk enclosed in square brackets ([*]).

When a target or data source depends on a qualifier, the report specifies the dimension of the qualifier and indicates the type of dependence. The type of dependence can be any of the following:

  • LAG -- One-way dependence on previous dimension values

  • LEAD -- One-way dependence on later dimension values

  • BOTH -- Two-way dependence on both previous and later values

  • VARIABLE -- Dependence on either previous or later values, depending on the value of a variable when the model is run

  • QDR -- Qualified data reference

Assume that you want to produce a dependency report for the income.budget model. The following statement and report illustrate this process.

MODEL.DEPRPT income.budget

MODEL INCOME.BUDGET <LINE MONTH>
2    [*](LINE OPR.INCOME):
       [*](LINE GROSS.MARGIN)
       [*](LINE MARKETING)
3    [*](LINE GROSS.MARGIN):
       [*](LINE REVENUE)
       [*](LINE COGS)
4    [*](LINE REVENUE):
       [*](LINE REVENUE)(LAG <MONTH>)
5    [*](LINE COGS):
       [*](LINE COGS)(LAG <MONTH>)
6    [*](LINE MARKETING):
       [*](LINE OPR.INCOME)(LAG <MONTH>)

The data sources in statements 4, 5, and 6 have a LAG dependence on the month dimension.

10.20 MODEL.XEQRPT

The MODEL.XEQRPT program produces a report about the execution of the model. The report specifies the block where the solution failed and shows the values of the model options that were used in solving simultaneous blocks.

Syntax

MODEL.XEQRPT

Usage Notes

Running MODEL.XEQRPT

Before you can run the MODEL.XEQRPT program, you must

  1. Set the MODERROR option to STOP or CONTINUE.

  2. Execute the model.

When the model halts because of an error, run the MODEL.XEQRPT program.

Effect of MODERROR on MODEL.XEQRPT

The results returned by MODEL.XEQRPT vary depending on the setting of the MODERROR option:

  • When MODERROR is set to STOP and execution of the model halts because of an error, you can run the MODEL.XEQRPT program to produce a report about the execution of the model. The report specifies the block where the solution failed and shows the values of the model options that were used in solving simultaneous blocks.

  • When MODERROR is set to CONTINUE and one block in the model is a simultaneous block that either diverges or fails to converge, Oracle OLAP executes any remaining blocks in the model.

    Moreover, Oracle OLAP executes the model for the remaining values in the status of any additional dimensions of the solution variable that are not dimensions of the model. In this case, when you run the MODEL.XEQRPT program when Oracle OLAP finishes executing the model, a report on the solution for the final values of the additional dimensions is produced.

    When the simultaneous blocks in the model converged when the model was executed for the final values of the additional dimensions, then MODEL.XEQRPT reports that the blocks were solved, even though an earlier execution of the model for another dimension value might have failed. When you want to see the MODEL.XEQRPT for the dimension values where the failure occurred, you can set MODERROR to STOP and rerun the model.

Examples

Example 10-65 Producing an Execution Report for the income.est Model

After running the income.est model, you can use the MODEL.XEQRPT program to produce a report on the execution of the model.

The following statement runs the MODEL.XEQRPT program, which produces an execution report for the model.

MODEL.XEQRPT income.est

The execution report contains the following output.

MODEL INCOME.EST <LINE MONTH>
Solution status:     SOLVED
Model options in use: 
   MODSIMULTYPE:     AITKENS
   MODMAXITERS:      50
   MODTOLERANCE:     3
   MODOVERFLOW:      3
   MODGAMMA:         1
BLOCK 1 (STEP-FORWARD <MONTH>)
  Solution status:   SOLVED
BLOCK 2 (SIMULTANEOUS)
  Solution status:   SOLVED
  Iterations:        15

The report shows the values of the model options that were used in solving the simultaneous blocks and indicates whether each block was solved.

10.21 MONITOR

The MONITOR command records data on the performance cost of each line in a specified program. To get meaningful information from MONITOR, your session must be the only one running in Oracle OLAP. Furthermore, the accuracy of the results of MONITOR decreases as more processes are started on the host computer.

You first use a MONITOR statement to specify a program for monitoring; then you run the program and use MONITOR again to obtain the results. When the program executes a given line repeatedly, MONITOR records the cumulative cost of all the executions on the single line of its monitor list that is devoted to that program line.

A line of code is considered to have a high performance cost when it takes a long time to execute. Use a TRACKPRG statement to identify programs that have relatively high costs and then use MONITOR to identify the time-consuming lines within those programs. When you want, you can use both TRACKPRG and MONITOR simultaneously.

Syntax

MONITOR ON [programs]  | OFF | INIT | FILE [[APPEND] file-name] | RESET

where programs is one of the following:

  • ALL [awlist]
  • program-name

Parameters

ON

Starts looking for the specified programs to be run so that Oracle OLAP can gather line-by-line timing data in a monitor list. (It continues the current monitoring process without interruption when monitoring is already on, or resumes with a gap when monitoring was off.)

When you do not specify a value for programs, the default is the program or programs specified in the last executed MONITOR ON statement. When there was no such statement in your current session, no data is collected and no error is produced.

ALL

Specifies that all of the programs in one or more analytic workspaces are monitored.

awlist

The name of one or more analytic workspaces (optionally separated by commas) whose programs you want monitored. When you omit this argument, Oracle OLAP monitors all of the programs in all of the attached analytic workspaces

program-name

The name of a specific program that you want monitored.

OFF

Stops monitoring programs and freezes any timing data currently in the monitor list which allows you send the list to the current outfile or to a text file either immediately, or later in your session.

RESET

(Useful only when monitoring is on.) Retains information about the programs that ares currently specified for monitoring and the Oracle OLAP memory that is allocated for the current monitor list, but discards any timing data currently in the list. In addition, RESET causes MONITOR to again begin waiting for you to run the same programs. When you do, MONITOR automatically gathers new timing data into a new monitor list for the same programs in the same memory allocation as before.

INIT

(Useful only when monitoring is on.) Initializes the monitoring environment. Initialization consists of discarding the program names and the timing data associated with the current monitor list, and releasing the Oracle OLAP memory previously used for that list so it can be used for other purposes or for collecting new data in a new monitor list.

FILE

Specifies that the timing data that is currently in the monitor list is sent to a file.

APPEND

Specifies that the timing data is appended to an existing file. When you omit this argument, the new output replaces the current contents of the file.

file-name

A text expression that is the name of the file to receive the output. Unless the file is in the current directory, you must include the name of the directory object in the name of the file. When file-name is specified, the data is sent to the named text file. FILE has no effect on the monitor list, so you can send the same list repeatedly to different destinations. When file-name is omitted, Oracle OLAP sends the timing data that is currently in the monitor list to the current outfile.

Note:

Directory objects are defined in the database, and they control access to directories and file in those directories. You can use a CDA statement to identify and specify a current directory object. Contact your Oracle DBA for access rights to a directory object where your database user name can read and write files.

Usage Notes

Monitor List

Each entry (that is, line) in the monitor list focuses on the execution of a single program line, regardless of how many times it is executed. Each entry is divided into the following four sections:

  • Cumulative total time of all executions in milliseconds rounded to the nearest 10 millisecond, in columns 1 through 11

  • Number of times executed, in columns 12 through 18

  • Line number, in columns 19 through 23

  • Text of the line, in column 24 and subsequent columns

Here is a sample of MONITOR output with column numbers included for reference.

12345678901234567890123456789012345678901234567890
 
60              1    1 push name 
30              1    2 trap on GETOUT noprint 
51              1    3 limit name to obj(type) eq 'DIMENSION'
0               1    4 for name 
0               0    5    do 
450             6    6    limit &name to ALL ifnone BYPASS 
0               0    7 BYPASS: 
0               0    8    doend 
0               0    9 GETOUT: 
0               1   10 pop name 

The following is the full description of the program used for the preceding output. Note that in the output, the line with the LIMIT command is truncated because it is too long to fit.

DEFINE allstat PROGRAM
LD Program to set the status of all dimensions in the analytic workspace to ALL
PROGRAM
PUSH NAME
TRAP ON getout NOPRINT
LIMIT NAME TO OBJ(TYPE) EQ 'Dimension' IFNONE getout
FOR NAME
   DO
   LIMIT &NAME TO ALL IFNONE bypass
bypass:
   DOEND
getout:
POP NAME
END

Attaching, Detaching, and Reattaching Analytic Workspaces

When Oracle OLAP executes a program in an analytic workspace that has been attached, detached, a new block of data is collected.

Truncated Statement Lines

When a program line is too long, the MONITOR output truncates it. Continuation lines do not appear in the output.

Producing a Report

When you want to produce an Oracle OLAP report from the timing data in the MONITOR file, you can write a program that uses a FILEREAD statement to read the data into an Oracle OLAP variable, and then use Oracle OLAP reporting capabilities to produce a report. You can use the TRACKREPORT program as a model. However, keep in mind that the TRACKREPORT program was written to produce a report on TRACKPRG output, not MONITOR output.

Bracketing Lines

When you just want to time a particular line or group of lines in a program, you can insert MONITOR ON and MONITOR OFF statements in the program to bracket just the line or lines in which you are interested.

Using MONITOR for a Nested Programs

When you do not want to run a nested program by itself, you can specify its name in a MONITOR ON statement and then run the program that calls it. MONITOR gathers timing data only for the specified (nested) program. When the specified program is called more than once, for each program line, MONITOR accumulates the total seconds taken by all the times the line was run and provide the number of times it was run.

When you just want to time a particular execution of a nested program that is called more than once, you can insert MONITOR ON and MONITOR OFF statements in the calling program to bracket the single call in which you are interested.

Using MONITOR with Very Small Programs

You might not be able to reproduce the results exactly for very small programs. When the CPU interrupts processing to do other tasks, that time is a greater percentage of the total execution time.

Unit of Measure for MONITOR

The MONITOR and TRACKPRG commands use milliseconds as the unit for recording execution time. The execution time does not include time spent on I/O and time spent waiting for the next statement.

Examples

Example 10-66 Collecting Timing Data Using MONITOR

In this example, MONITOR is used to collect timing data on the execution of the individual lines of code in prog1 and then to send the data to a text file. The MONITOR ON statement is then used to discard the prog1 timing data and start collecting data on prog2. After the data for prog2 is sent to a second file, MONITORINIT is used to discard the current monitor list and release the memory used for it.

MONITOR ON prog1
prog1
MONITOR FILE prog1.mon
MONITOR ON prog2
prog2
MONITOR OFF
MONITOR FILE prog2.mon
MONITOR INIT

10.22 MOVE

The MOVE command moves an object name to a new position in the NAME dimension of an analytic workspace. The reorganizing effect of the MOVE command on the workspace is cosmetic. That is, no physical changes take place in workspace storage. Users often reorganize workspace objects so the output from DESCRIBE is easier to read.

Syntax

MOVE name... {FIRST|LAST|{BEFORE|AFTER} name2} [AW workspace]

Parameters

name...

The names of one or more objects to move. You can specify the names individually, or use one of the following forms to specify a group of names:

  • name TO name
  • FIRST 
  • LAST n
  • boolean-expression (dimensioned by NAME)

You can specify a qualified object name to indicate the attached workspace in which the object resides. As an alternative, you can use the AW argument to specify the workspace. Do not use both.

When you do not use a qualified object name or the AW argument to specify an analytic workspace, Oracle OLAP looks for the object in the current workspace.

FIRST
LAST

The logical position in the NAME dimension to which Oracle OLAP moves the objects specified by the name argument. Specifying FIRST moves the objects to the beginning of the NAME dimension. Specifying LAST (the default) moves the names to the end of the NAME dimension.

BEFORE name2
AFTER name2

The position before or after a particular object (name2) to which Oracle OLAP moves the objects specified by the name argument.

AW workspace

The name of an attached workspace in which you want to move the object. When you do not use a qualified object name or the AW argument to specify an analytic workspace, objects are moved in the current workspace.

Usage Notes

Alphabetizing Your Objects

You can arrange your workspace objects alphabetically with the following statements, which work on the NAME dimension.

SORT NAME A NAME
MOVE CHARLIST(NAME) FIRST

Examples

Example 10-67 Moving a Relation

This example shows how to move the relation desc.product after product. The OLAP DML statement

SHOW CHARLIST(NAME)

produces the following list (annotation has been added).

product           <--- Position of product
district
division
line
region
marketlevel
market
month
year
quarter
desc.product      <--- Old position of desc.product
region.district
division.product
...

The following statements

MOVE desc.product AFTER product
SHOW CHARLIST(NAME)

change the workspace order and produce the following list (annotation has been added).

product           <--- Position of product
desc.product      <--- New position of desc.product
district
division
line
region
marketlevel
market
month
year
quarter
region.district
division.product
...

10.23 OUTFILE

The OUTFILE command lets you redirect the text output of statements to a file.

Syntax

OUTFILE {EOF | TRACEFILE | [APPEND] file-name [NOCACHE] [NLS_CHARSET charset-exp]}

Parameters

EOF

The current outfile is closed and output is redirected to the default outfile.

TRACEFILE

Specifies that the output should be directed to the Oracle trace file, which is identified by the TRACEFILEUNIT option.

APPEND

Specifies that the output should be added to the end of an existing disk file. When you omit this argument, the new output replaces the current contents of the file.

file-name

A text expression that is the name of the file to which output should be written. Unless the file is in the current directory, you must include the name of the directory object in the name of the file.

Note:

Directory objects are defined in the database, and they control access to directories and file in those directories. You can use a CDA statement to identify and specify a current directory object. Contact your Oracle DBA for access rights to a directory object where your database user name can read and write files.

NOCACHE

Specifies that Oracle OLAP should write lines to the outfile as they are generated. Without this keyword, Oracle OLAP reduces file I/O activity by saving text and writing it periodically to the file. The NOCACHE keyword slows performance significantly, but it ensures that every line is immediately recorded in the outfile. This argument must be specified after file-name

NLS_CHARSET charset-exp

Specifies the character set that Oracle OLAP uses when writing data to the file specified by file-name which allows Oracle OLAP to convert the data accurately into that character set. This argument must be specified after file-name. When this argument is omitted, then Oracle OLAP writes the data to the file in the database character set, which is recorded in the NLS_LANG option.

Usage Notes

Outfiling a PERMIT_READ or PERMIT_WRITE Program

The contents of a PERMIT_READ or a PERMIT_WRITE program is emptied when outfiled. To successfully copy the contents of these programs to and from analytic workspaces, rename them before using OUTFILE; and then, after using INFILE to copy them into an analytic workspace, name them back to PERMIT_READ or PERMIT_WRITE.

Current Outfile Identifier

As a first step, every OUTFILE statement closes the current outfile. When OUTFILE opens a new outfile on disk, it automatically assigns to it an arbitrary INTEGER as its file unit number. The current file unit number is held in the OUTFILEUNIT option.

Appending to an Outfile

When you send output to a file and then send output to a second file, the first file does not remain open. To resume sending output to the first file, you must execute another OUTFILE statement and include the APPEND file-name phrase.

Automatic Closing of Outfile

When you use OUTFILE file-name to direct output to a disk file, OUTFILE closes any outfile currently open. OUTFILE issues a close even when the new file is not actually opened (as when you specify an invalid file-name in an OUTFILE statement).

Paging Options and Redirected Output

The paging options control the organization of text output in pages. Examples are: BMARGIN, LINENUM, LINELEFT, PAGESIZE, PAGENUM, PAGEPRG, PAGING, TMARGIN, and LSIZE. The paging options have a separate value for each separate outfile. When you set a paging option to control output to a disk file, the new value remains in effect until you use an OUTFILE statement again to redirect output. At this point, the paging option returns to its default value. Therefore, when you want a paging option to have a particular value for a disk file, you generally have set it after you execute an OUTFILE statement.

Current and Default Outfiles

The current outfile is the destination for the output of statements, such as REPORT and DESCRIBE, that produce text. When you have not used an OUTFILE statement to send output to a file, Oracle OLAP uses your default outfile.

Examples

Example 10-68 Sending a Report to an Output File

In this example, you want to send the output of a REPORT statement to an output file.

OUTFILE 'budget.rpt'
REPORT budget
OUTFILE EOF 

Example 10-69 Directing Output to a File

Suppose you have a program called year.end.sales, and you want to save the report it creates in a file. Type the following commands to write a file of the report. In this example, userfiles is a directory object and yearend.txt is the name of the file.

OUTFILE 'userfiles/yearend.txt'
year.end.sales
OUTFILE EOF

Now the file contains the year.end.sales report. You can add more reports to the same file with the APPEND keyword for OUTFILE. Suppose you have another program called year.end.expenses. Add its report to the file with the following commands. Remember that without APPEND, an OUTFILE statement overwrites the expense report.

OUTFILE APPEND 'userfiles/yearend.txt'
year.end.expenses
OUTFILE EOF

10.24 PAGE

The PAGE program forces a page break in output when PAGING is set to YES. An optional argument to PAGE specifies a conditional page break based on how many lines are left on the page.

The PAGE program is commonly used in report programs. It is meaningful only when PAGING is set to YES and only for output from statements such as REPORT and LISTNAMES.

Syntax

PAGE [n]

Parameters

n

A positive INTEGER expression that indicates that a page break should occur only when there are fewer than n lines left on the current page. When the number of lines left equals or exceeds n, no page break occurs. See Example 10-70.

Usage Notes

Top of Page

No page break occurs when you are already at the top of a page when a PAGE statement is executed.

Producing the Header

The PAGE program signals that further output should be produced on a new page, but it does not produce a header on the new page unless there is further output. When there is further output, Oracle OLAP produces the heading that is defined by the current PAGEPRG program and then starts producing the output.

Examples

Example 10-70 Keeping Lines Together

Suppose you have 12 lines of data that would be hard to read when interrupted by a page break, so you want to prevent such an interruption. Use the PAGE 12 statement immediately before the statements that produce the 12 lines of data. A page break occurs before the 12 lines of data only when there are less than 12 lines left on the page. When there are 12 lines or more left at that point, output continues on the same page.

Example 10-71 Forcing a Page Break

The following lines from a report program force a page break at the start of each loop for district which makes the report for each district start at the top of a page. (The report program uses a heading program called report.head to create a customized heading. See the PAGEPRG option for information on customized heading programs.)

PUSH PAGING PAGEPRG
PAGING = YES
PAGEPRG = 'report.head'
FOR district
   DO
   PAGE
   ROW district
   BLANK
   FOR month
      ROW WIDTH 8 month sales sales.plan
   DOEND
PAGE
POP PAGING PAGEPRG

10.25 PARSE

Use the PARSE command to parse a specified group of expressions. When the argument can be parsed, PARSE determines the number of expressions in it and their text, object type, data type, and the number and names of their dimensions. This information is stored internally by Oracle OLAP, but can be obtained with the INFO function.

A PARSE statement is especially useful when you want to accept expressions as arguments to a program.

Syntax

PARSE text-expression

Parameters

text-expression

A text expression that contains one or more smaller expressions to be parsed. When you are processing program arguments, you can specify an ARGS function as the text expression that contains all the arguments for the program.

Usage Notes

Obtaining Information Produced by a PARSE Statement

See the INFO (PARSE) function for an explanation of how to obtain the information produced by a PARSE statement.

Examples

Example 10-72 Parsing the Arguments to a Program

In a simple report program, you want to specify the data to be reported as an argument to the program. You want to be able to specify an expression and the name of a data variable.

Suppose you want to display each of the arguments with a different column width, which means you must process the arguments individually. The ARGS function can only process them together. So you use PARSE and INFO to parse the arguments and produce individual columns for each of them. Here is a sample program.

DEFINE report1 PROGRAM
PROGRAM
PUSH month product district DECIMALS
DECIMALS = 0
LIMIT month TO FIRST 2
LIMIT product TO ALL
LIMIT district TO 'Chicago'
PARSE ARGS
REPORT ACROSS month WIDTH 8 <&INFO(PARSE FORMULA 1) -
   WIDTH 13 &INFO(PARSE FORMULA 2)>
POP month product district DECIMALS
END

When you run the program, you can supply either the names of variables (such as sales) or expressions (such as sales-expense) or one of each as arguments. The following REPORT statement produces the illustrated report.

report1 sales sales-expense
 
DISTRICT: CHICAGO
             --------------------MONTH--------------------
             --------JAN95--------- --------FEB95---------
PRODUCT       SALES   SALES-EXPENSE  SALES   SALES-EXPENSE
------------ -------- ------------- -------- -------------
Tents          29,099         1,595   29,010         1,505
Canoes         45,278           292   50,596           477
Racquets       54,270         1,400   58,158         1,863
Sportswear     72,123         7,719   80,072         9,333
Footwear       90,288         8,117   96,539        13,847

10.26 PERMIT

The PERMIT command lets you grant or deny read-only and read/write access permission for workspace objects and for specific values of dimensions and dimensioned objects. You can also use PERMIT to grant or deny permission to maintain dimensions and to change permission for workspace objects.

In general, access permissions that you set for a dimension are meaningful not only for that dimension, but also for the objects dimensioned by that dimension as explained more fully in "How Dimension Permission Interacts with Permissions for Other Objects". Access permissions that you set for other objects are limited in scope to that particular object. Various conditions determine when permission changes take effect as discussed in "When Permission Changes Take Effect"

Tip:

The PERMIT command assigns permission to the object most recently defined or considered. When the definition of the object is not the current one, first use a CONSIDER statement before issuing PERMIT commands for the object

Syntax

PERMIT {READ|WRITE|MNT|PERMIT} [WHEN permission-condition...]

Parameters

READ

Depending on the permission conditions, grants or restricts permission to read all of the values of an object or only certain values in a dimension or dimensioned object.

Note that restricting read permission for a dimension also restricts maintain permission for that dimension. Also, when you grant read permission for an object, write permission is also allowed for the values you can read, unless you deny it with an explicit PERMIT WRITE statement.

WRITE

Depending on the permission conditions, grants or restricts permission to modify any of the values of an object or only certain values of a dimensioned object.

Restricting write permission for an object does not necessarily mean that the object is totally unavailable. For example, when you have restricted write access to a calculation specification (that is, an aggmap object, program, model, or formula, you can still execute the object— you just cannot edit the contents of the calculation specification.

Oracle OLAP does not prevent you from granting write permission for values that you cannot read within a dimensioned object. When you have both a PERMIT READ and a PERMIT WRITE statement for a dimensioned object, and some values which satisfy the permission conditions for write do not fall within the subset of values which satisfy the permission conditions for read, then those values may be modified but not seen.

Tip:

Write permission is not meaningful for dimensions— except to provide write access to objects dimensioned by the dimension. To grant or restrict the ability to add values to a dimension, issue PERMIT MNT statements for the dimension instead.

MNT

Depending on the permission conditions, grants or restricts permission to maintain a dimension.

Note that you cannot grant maintain permission to a dimension for which you have restricted read permission. Oracle OLAP automatically denies maintain permission for a dimension when there is restricted read permission for that dimension.

PERMIT

Depending on the permission conditions, grants or restricts permission to use the PERMIT command to change the read, write, maintain, or permit permission for the object.

Note that unless explicitly you explicitly deny permit permission for an object, permit permission is allowed for an object no matter what other permissions are set for that object.

WHEN permission-condition...

When you omit the WHEN clause and execute a PERMIT READ, PERMIT WRITE, or PERMIT MNT statement, Oracle OLAP restores full read, write, or maintain permission to the object.

When you include the WHEN clause, the conditions for granting read, write, maintain, or permit permission consist of one or more Boolean expressions depending on whether or not the object has dimensionality, the type of permission you are setting and, for read and write permissions, whether or not the object has dimensionality:

  • When you are specifying permit permission, maintain permission, or read or write permission that applies to an object without dimensionality or when you want the read or write permissions to apply to all the values of a dimensioned object, specify the permission condition as a Boolean expression that evaluates to a single value. (Not that if you do specify a dimensioned Boolean expression to specify permissions for an object without dimensionality or when you are specifying permit or maintain permission, then PERMIT uses the first value in status.)

    Tip:

    Avoid specifying a Boolean value as a permission condition (for example, YES or NO) for a PERMIT PERMIT statement. Instead specify the permission condition as a Boolean variable, a function that returns a Boolean result, or a Boolean value calculated by comparison operators. In this way, when permit permission has been denied, you can restore it by setting the value of the Boolean and executing a PERMITRESET statement. If you ever do lock up an object and are unable to modify its permission, you can specify permit permission for it in the workspace permission program for that workspace, then detach and reattach the workspace.

  • If you are specifying read or write permission that applies to individual dimension values or to slices of a dimensioned object, specify one permission condition for each dimension of interest. In this case, the WHEN clause has the following syntax and each dimensioned permission condition consists of a Boolean expression dimensioned by a dimension of the object.

    • WHEN dimensioned_permission_condition1
    •    [BY dimensioned_permission_condition2
    • [UNION dimensioned_permission_condition2A]...

    Use the UNION phrase to efficiently access the union of several symmetric subcubes of a multidimensional variable.

    Note that if a Boolean expression for a dimensioned permission condition has any extra dimensions in addition to an object dimension, PERMIT takes the first value in status to determine which column of Boolean values to use. The intersection of the YES values for each dimension (a logical AND of the conditions) is the subset of values within the object to which the permission applies. When any of the object dimensions are not represented by a dimensioned permission condition, then Oracle OLAP assumes YES for all those dimension values.

Usage Notes

Important Considerations Before You Change the Permissions of an Object

Keep the following important considerations in mind before you change the permissions of an object:

  • You must have permit permission for an object to issue PERMIT commands against it.

  • Do not lock out the DBA user, who must always have access to everything in the workspace.

  • Issuing PERMIT statements against an INTEGER dimension may result in undesired behavior. Dimensions with an INTEGER data type have values identified by their numeric position. PERMIT renumbers INTEGER dimensions to keep the normal sequence of INTEGER values (1, 2, 3, ...). When you must use PERMIT to change the default access rights for an INTEGER dimension and this behavior is not desirable, redefine the dimension with a different, non-integer data type.

When Permission Changes Take Effect

Within PERMIT_READ and PERMIT_WRITE programs, permissions ares only evaluated when you issue an explicit PERMIT or PERMITRESET statement and then reference the targeted object.

Note:

AW ATTACH automatically executes a PERMITRESET immediately after executing an analytic workspace permission program. Executing PERMITRESET causes the workspace to be attached with all permission implemented

Once an analytic workspace is attached and any PERMIT_READ and PERMIT_WRITE programs have executed, permission changes specified by a PERMIT statement take effect:

  • When a PERMITRESET statement executes.

  • When you are targeting any object (except a dimension), and the permission condition consists of a single Boolean variable, any changes to that Boolean variable affect the permission immediately. (You never have to execute a PERMITRESET in this case.)

  • In other situations, if you do not issue a PERMITRESET statement, permission are evaluated upon next reference to the object.

    Note:

    The OBJ function is an exception to this rule. Because OBJ does not load the object into memory, it does not reflect any changes to the object's permission since the last time it was loaded. When you want OBJ to provide information based on new permission criteria, execute a LOAD statement before the OBJ statement.

When the only PERMIT Statement for an Object is a PERMIT WRITE Statement

When the only PERMIT statement for an object is a PERMIT WRITE, then read permission is provided by default for the object. The default read permission is provided independent of the value of the permission condition(s) for the PERMIT WRITE statement. Consequently, a PERMIT WRITE with a single-cell permission condition which evaluates to NO provides read-only access to an nondimensional object or to all the values of a dimensioned object.

When the only PERMIT statement for an object is a PERMIT WRITE with dimensioned permission conditions, it designates some values for read/write access and the remaining values for read-only access. See Example 10-73.

How Dimension Permission Interacts with Permissions for Other Objects

All dimensioned data is affected by the read permission on its dimensions. The dimension values that satisfy the read permission condition determine the default status for the dimension. The values of dimensioned objects that correspond to dimension values without read permission are inaccessible.

However, in order for write permission associated with a dimension to apply to other objects dimensioned by it, there must be at least one PERMIT statement associated with the dimensioned object.

  • When you want a dimensioned object to inherit write permission from its dimensions, but you do not want it to have permission of its own, which could interact with the dimension permission, you can simply use a PERMIT READ with a single-cell permission condition that evaluates to YES.

  • When you want a dimensioned object to inherit write permission from its dimensions, and you also want it to have permissions of its own, understand how dimension permission interacts with individual object permissions before setting them.

Dimension permission interacts with permission for most of the objects dimensioned by it in the following ways:

  • The access permissions of a dimension apply to all dimension surrogates defined for that dimension. You cannot use a PERMIT statement on a dimension surrogate.

  • When there is read or write permission associated with a dimension, but no permission restriction associated with an object dimensioned by that dimension, then the permission for the dimensioned object is the same as the dimension permission.

  • When there is read permission associated with both the dimension and the dimensioned object, Oracle OLAP determines the values with read permission in the object by taking the intersection of the values with read permission in the dimension and the values with read permission in the object.

  • When there is write permission associated with both the dimension and the dimensioned object, Oracle OLAP determines the values with write permission in the object by taking the intersection of the values with read permission in the dimension, the values with write permission in the dimension, and the values with write permission in the object.

However, this is not the case for relations and valuesets. When there is restricted write permission for a dimension of a relation or a valueset, it does not affect relations and valuesets dimensioned by that dimension.

Determining Permission

The permission associated with an object is provided, like an LD, when you describe it using a DESCRIBE statement. The only exception is when you are denied permit permission for the object. In this case, no permission is provided when you describe it.

Advantages of PERMIT Over LIMIT as a Tool for Scoping

As a tool for scoping within application programs, PERMIT has several advantages over the LIMIT command. To restrict the scope of a dimensioned object according to a Boolean expression, you have to use two LIMIT statements, a LIMIT and a LIMITKEEP. You only need one PERMIT statement to do the same thing. Moreover, application users cannot change the restricted scope set by PERMIT commands in application programs. Application users can easily change the scope set by LIMIT commands in application programs simply by executing more LIMIT commands.

Handling Permission Violations

You can use the PERMITERROR option to control the way Oracle OLAP handles attempted violations of the permission established by PERMIT commands for variables. The default value of PERMITERROR is YES, meaning that Oracle OLAP signals an error when a user attempts to access a value for which permission is denied. When you set PERMITERROR to NO, Oracle OLAP simply denies access without signaling an error condition which is useful when you want to do a report of a dimensioned variable for which you have partial permission without limiting the dimensions to the permitted values up front. With PERMITERROR set to NO, values for which you do not have read permission appear as NA values in the report.

Examples

Example 10-73 Variable Permission

For a variable sales dimensioned by month, product, and district, you might have three dimensioned permission conditions in the form of three variables as illustrated in the following report.

MONTH.BOOL<MONTH>  PROD.BOOL<PRODUCT>  DISTRICT.BOOL<DISTRICT>
-----------------  ------------------  -----------------------
Jan95    NO        Tents     YES       Boston     NO
Feb95    YES       Canoes    YES       Atlanta    NO
Mar95    NO        Racquets   NO       Chicago    YES
...      ...       ...        ...      ...        ...

When the YES values shown in the preceding example are the only YES values in the permission conditions, the following PERMIT statement provides read/write access to sales data for tents and canoes sold in Chicago in Feb95. In the absence of a PERMITREAD statement for sales, Oracle OLAP provides read-only permission for all the other values of sales.

PERMIT WRITE WHEN district.bool BY prod.bool BY month.bool

You can restore full write permission with the following PERMIT statement.

PERMIT WRITE

When there is no restricted write permission for sales, the following PERMIT statement provides read/write access to sales data for tents and canoes sold in Chicago in Feb95, and it causes all other values of sales to be invisible.

PERMIT READ WHEN district.bool BY prod.bool BY month.bool

Example 10-74 Dimensioned Permission Condition

To restrict access to the product dimension you need a permission condition dimensioned by product. However, when the permission condition has a second dimension, say authority, PERMIT selects the BOOLEAN values that pertain to product based on the first value in status of authority. When you restrict read permission on the authority dimension to one value, PERMIT uses that value to determine the BOOLEAN values of the permission condition for product. The REPORT commands produce the output that follows them.

DEFINE authority DIMENSION TEXT
MAINTAIN authority ADD OTHER DBA
DEFINE prod_authority VARIABLE BOOLEAN <product authority>
...
" Assign values to the variable
...
REPORT prod_authority
 
              -----------------PROD_AUTHORITY------------------
              --------------------PRODUCT----------------------
AUTHORITY     Tents   Canoes   Racquets   Sportswear   Footwear
---------     -----   ------   --------   ----------   --------
Other            NO       NO        YES          YES        YES
Dba             YES      YES        YES          YES        YES

CONSIDER product
PERMIT READ WHEN prod_authority
PERMITERROR = NO
RPEPORT product
 
PRODUCT
-------------
Racquets
Sportswear
Footwear

CONSIDER authority
PERMIT READ WHEN AUTHORITY EQ 'dba'
PERMITRESET
Report product
 
PRODUCT
-------------
Tents
Canoes
Racquets
Sportswear
Footwear

Example 10-75 User-Defined Boolean Function

In the following example, usercheck is a user-defined Boolean function that checks the current value of the variable thisuser against a list of user IDs. usercheck returns NO when the current value of thisuser is not in the list. The following PERMIT statement applied to the sales variable provides read-only access to all values of sales when usercheck returns NO. It provides read/write access to all values of sales when usercheck returns YES.

PERMIT WRITE WHEN usercheck(thisuser)

The following PERMIT statement, applied to the variable price, provides full access to all values of price when usercheck returns YES. When it returns NO, it denies all access to the price variable.

PERMIT READ WHEN usercheck(thisuser)

Example 10-76 Individual Cells

When you want to prevent access to one particular sales figure, say for racquets in Boston in March of 1997, you can create a Boolean variable and use it in a PERMIT statement as illustrated in the following statements.

DEFINE sales.bool VARIABLE BOOLEAN <month product district>
sales.bool = yes
LIMIT month TO 'Mar97'
LIMIT product TO 'Racquets'
LIMIT district TO 'Boston'
sales.bool = no
CONSIDER sales
PERMIT READ WHEN sales.bool

Example 10-77 Individual Dimension Values

The following PERMIT commands applied to the district dimension prevent access to all dimension values except Boston and Atlanta. They provide read/write access for all data related to Boston and read-only access for all data related to Atlanta. They also prevent anyone with a user ID not allowed by the function usercheck (see Example 10-75) from modifying the permission for district.

PERMIT READ WHEN district EQ 'Boston' OR district EQ 'Atlanta'
PERMIT WRITE WHEN district EQ 'Boston'
PERMIT PERMIT WHEN usercheck(thisuser) 

10.27 PERMITRESET

The PERMITRESET command causes the values of permission conditions to be reevaluated. Permission conditions consist of one or more Boolean expressions that designate the criteria used by PERMIT commands associated with an object.

When permission conditions are dimensioned, they indicate which values of a dimensioned object PERMIT targets for permission. A single-cell permission condition can indicate any Boolean criterion, such as whether or not a particular user may access the object.

When you want to keep the existing PERMIT commands for an object, but you want the permission conditions associated with them to be recalculated, issue a PERMITRESET statement. The permission for that object is based on the new values of the permission conditions the next time you use the object in an OLAP DML statement.

See Also:

"Startup Programs", PERMIT command, and PERMITERROR option

Syntax

PERMITRESET  [object_name]  [READ|WRITE]

Parameters

object_name

Specifies the name of an object for which permission conditions should be reevaluated. When you do not specify an object name, the permission conditions for all objects are reevaluated.

READ

Causes reevaluation of the permission conditions for PERMITREAD commands only, or for a PERMITREAD statement for the specified object.

WRITE

Causes reevaluation of the permission conditions for PERMIT WRITE commands only, or for a PERMIT WRITE statement for the specified object.

Examples

Example 10-78 Resetting Permission

In the following example, the user-defined Boolean function usercheck checks the current value of the variable thisuser and returns YES only when it is greater than 100. Access to the variable uservar is only allowed when thisuser is greater than 100. However, when you change the value of thisuser to a value less than or equal to 100 without resetting the permission for uservar, access is still permitted.

The statement

DESCRIBE uservar

produces the following output.

DEFINE USERVAR VARIABLE INTEGER
PERMIT READ WHEN usercheck(thisuser)

The statement

SHOW uservar

produces the following output.

5

The statement

DESCRIBE usercheck

produces the following output.

DEFINE USERCHECK PROGRAM BOOLEAN
PROGRAM
  ARG thisuser INT
  TRAP ON errorexit NOPRINT
  IF thisuser GT 100
          THEN RETURN YES
  ELSE RETURN NO
  errorexit:
       RETURN NO
END

The statement

DESCRIBE thisuser

produces the following output.

DEFINE THISUSER VARIABLE INTEGER

The statement

SHOW thisuser

produces the following output.

101

The statements

thisuser = 100
SHOW uservar

produces the following output.

5

The statements

PERMITRESET luservar READ
SHOW uservar 

produce the following error.

ERROR: You do not have permission to read this value of USERVAR

10.28 POP

The POP command restores the status of a dimension (including the NAME dimension), the status of a valueset, or the value of an option or single-cell variable that was saved with a previous PUSH statement.

PUSH and POP are commonly used within a program to make changes to options and dimension status that apply only during the program's execution. Afterward, the options and status are the same as they were before the execution of the program.

Syntax

POP name1 [nameN]

Parameters

name

The name of a dimension, valueset, variable, or option that was specified in a previous PUSH statement, whose saved value you want to restore.

Examples

For an example of using POP, see Example 10-84.

10.29 POPLEVEL

The POPLEVEL command (abbreviated PPL) restores all values saved with PUSH commands that were executed since the last POPLEVEL statement specifying the same marker.

You must use PUSHLEVEL to mark a starting point for a series of PUSH commands before you can use POPLEVEL to restore the saved values. POPLEVEL itself marks the end of the series. You can use POPLEVEL only within programs.

Syntax

POPLEVEL marker-expression [DISCARD]

Parameters

marker-expression

A text value used as a marker. This value must be the same as the value used in the corresponding PUSHLEVEL statement to mark the start of a series of saved values being popped.

DISCARD

Specifies that the pushed values for that level are discarded when you issue a POPLEVEL statement. When you do not specify DISCARD, the values that were pushed are used to reset the pushed objects.

Usage Notes

Possible Uses for POP LEVEL Statement

Two possible uses for POPLEVEL statements are:

  • After a series of increasingly broadening or narrowing LIMIT commands, each with a corresponding PUSH.

  • After a single extremely long and complicated PUSH statement, or a series of short ones given throughout a program, that may need a lot of editing. PUSHLEVEL and POPLEVEL allow you to edit the arguments for a long and complicated PUSH statement without also having to edit a corresponding long and complicated POP statement.

Examples

To see a sample program using POPLEVEL, see the example for the PUSHLEVEL command.

10.30 PROGRAM

The PROGRAM command enters completely new contents into a new or existing program. When the program already has lines of code, Oracle OLAP overwrites them.

To use PROGRAM to enter the contents of a program object, the program object definition must be the one most recently defined or considered during the current session. When it is not, you must first use a CONSIDER statement to make it the current definition.

An alternative to a PROGRAM statement is an EDIT PROGRAM statement, which is available only in OLAP Worksheet. An EDIT PROGRAM statement opens an Edit window in which you can add, delete, or change the specification for a program object.

See Also:

For a discussion of writing, compiling, and debugging OLAP DML programs, see OLAP DML Programs

Syntax

PROGRAM [contents]

Parameters

contents

A text expression that is the OLAP DML statements that are the lines of the program. You can use most OLAP DML statements within a program. For a discussion of writing, compiling, and debugging OLAP DML programs, see OLAP DML Programs.

The maximum number of lines you can have in a program is 32,000.When coding a PROGRAM statement at the command line level, separate program lines with newline delimiters (\n), or use the JOINLINES function as shown in "Example 10-80".

Examples

Example 10-79 User-Defined Function with Arguments

Suppose your analytic workspace contains a variable called units.plan, which is dimensioned by the product, district, and month dimensions. The variable holds INTEGER data that indicates the number of product units that are expected to be sold.

Suppose also that you define a program namedunits_goals_met. This program is a user-defined function. It accepts three dimension-value arguments that specify a given cell of the units.plan variable, and it accepts a fourth argument that specifies the number of units that were actually sold for that cell. The program returns a Boolean value to the calling program. It returns YES when the actual figure comes up to within 10 percent of the planned figure; it returns NO when the actual figure does not.

The definition of the units_goals_met program is follows.

DEFINE units_goal_met PROGRAM BOOLEAN
LD Tests whether actual units met the planned estimate
"Program Initialization
ARGUMENT userprod  TEXT
ARGUMENT userdist  TEXT
ARGUMENT usermonth TEXT
ARGUMENT userunits INTEGER
VARIABLE answer boolean
TRAP ON errorlabel
PUSH product district month
"Program Body
LIMIT product TO userprod
LIMIT district TO userdist
LIMIT month TO usermonth
IF (units.plan - userunits) / units.plan GT .10
   THEN answer = NO
   ELSE answer = YES
"Normal Exit
POP product district month
RETURN answer
"Abnormal Exit
errorlabel:
POP product district month
SIGNAL ERRORNAME ERRORTEXT
END

To execute the units_goal_met program and store the return value in a variable called success, you can use an assignment statement (SET).

success = units_goal_met('TENTS' 'BOSTON' 'JUN96' 2000)

Example 10-80 Program On the Fly

This example creates a flexible report program "on the fly" to avoid the inefficiencies of a more conventional program using ampersand substitution. The conventional program would contain the following loop.

FOR &dimname
   ROW &dimname &varname

To avoid ampersand substitution, define a program, for example, STANDARDREP, and leave it without any code in it, or with code that can be discarded. Then in your report program, insert lines such as the following.

DEFINE myreport PROGRAM
LD Program to produce my report
PROGRAM
ARGUMENT dimname TEXT
ARGUMENT varname TEXT
...
CONSIDER standardrep
PROGRAM JOINLINES(JOINCHARS('FOR ', dimname) - 
   JOINCHARS('   ROW ', dimname, ' ', varname) )
COMPILE standardrep
standardrep
...

Example 10-81 Program from an Input File

This example presents the text of a simple program that is in an ASCII disk file called salesrep.inf. The first line in the file defines the program, the second line contains a PROGRAM statement, and the subsequent lines provide the lines of the program.

DEFINE salesrep PROGRAM
PROGRAM
PUSH month product district
TRAP ON haderror
LIMIT month TO FIRST 3
LIMIT product TO FIRST 3
LIMIT district TO ALL
REPORT grandtotals sales
haderror:
POP month product district
END

To include the salesrep program in your analytic workspace, you can execute the following statement.

INFILE 'salesrep.inf'

You can create an input file from an existing program using an OUTFILE statement

Example 10-82 Using OLAP Worksheet Instead of a PROGRAM Statement

When you use OLAP Worksheet to create a program, you can use an EDIT statement to display an Edit window where you can enter the contents. For example, use the following statements to define a new program named salesrep and display it in an Edit window.

DEFINE salesrep PROGRAM
EDIT salesrep

10.31 PROPERTY

The PROPERTY command adds or deletes properties to the most recently defined or considered object (see the DEFINE PROGRAM and CONSIDER commands). A property is a named value that is associated with a given definition. You can assign one or more properties to any type of definition. For example, you can assign a property to an object so you know how many decimal places to use when preparing a report on the object.

Syntax

PROPERTY { name value | DELETE {ALL | name} }

Parameters

name

A text expression that contains the name of the property. The property name can be from 1 to 256 bytes long.

Note:

Do not create your own properties with names that begin with a $ (dollar sign). Properties with names beginning with a $ (dollar sign) are reserved for Oracle OLAP to use as "system" properties that Oracle OLAP interprets in predetermined ways.

Property names have the TEXT data type, unless you include a Unicode escape sequence in the value you specify for the name, or unless you explicitly convert the value you specify to NTEXT (using the CONVERT or TO_NCHAR functions).

value

An expression that contains the value of the property. The property value can have one of the following data types: NUMBER, INTEGER, LONGINTEGER, DECIMAL, SHORTDECIMAL, TEXT, NTEXT, ID, BOOLEAN, DATE, or DATETIME. Oracle OLAP determines the data type based on the value that you specify. For example, when you specify YES, then Oracle OLAP assumes a type of BOOLEAN. When you specify a date value that is stored in a variable of type DATE, then Oracle OLAP assumes a type of DATE for the property.

DELETE ALL
DELETE name

Deletes either all of the properties of the object or only the property you specify for name. You can specify only one name at a time.

Usage Notes

Triggering Program Execution When PROPERTY Executes

Using the TRIGGER command, you can make a PROPERTY statement an event that automatically executes an OLAP DML program. See "Trigger Programs" for more information

Changing a Property Value

When you execute a PROPERTY statement that assigns a new value to an existing property name, then the new value overwrites the previous one.

Determining Property Values with OBJ

To use properties with OLAP DML statements, you must obtain the values by using the property-related keywords of the OBJ function. For example, suppose a property called decplace stores the number of decimal places to use when reporting an object. When you execute a REPORT statement, you can use the OBJ function with the PROPERTY keyword to obtain the value of the decplace property and use that value with the REPORT statement's DECIMAL attribute.

Listing Property Values with FULLDSC

You can list the properties of an object by using a FULLDSC statement. You can use the output from FULLDSC to create new objects. See the FULLDSC program for more information.

Examples

Example 10-83 Adding Properties to a Variable

The following statements add the properties decplace and prgname to the actual variable and assign the decimal 4 as the value for the decplace property and the text repprg as the value for the prgname property.

CONSIDER actual
PROPERTY 'decplace' 4
PROPERTY 'prgname' 'repprg'

10.32 PUSH

The PUSH command saves the current status of a dimension (including the NAME dimension), the status of a valueset, or the value of an option or single-cell variable. You can then restore these saved values and status at a later time with a POP statement.

PUSH and POP are commonly used within a program to make changes to options and dimension status that apply only during the program's execution. Afterward, the options and status are the same as they were before the execution of the program.

See Also:

PPOP, POPLEVEL, PUSHLEVEL, and CONTEXT commands

Syntax

PUSH name1 [name]

Parameters

name

The name of a dimension, valueset, option, or variable whose status or value you want to save.

Usage Notes

Effect of a MAINTAIN Statement on a Dimension's Pushed Status

Using a MAINTAIN statement with a dimension clears that dimension's pushed status lists. For example, suppose you have pushed the dimension month several times, with different limits each time. When you then use a MAINTAIN statement to perform any maintenance activity on the month dimension, Oracle OLAP resets the status of month to ALL (the default), and popping that dimension has no effect.

Examples

Example 10-84 Saving and Restoring Values

The following program uses PUSH and POP to produce sales figures without decimal places for a specific selection of products, districts, and months, and then restores the status settings and the value of DECIMALS to what they were before the program was run.

DEFINE report1 PROGRAM
PROGRAM
TRAP ON cleanup
PUSH DECIMALS product district month
 
DECIMALS = 0
LIMIT product TO 'Sportswear' 'Footwear'
LIMIT district TO 'Atlanta' 'Dallas'
LIMIT month TO 'Jan96' TO 'Jun96'
REPORT sales
 
cleanup:
POP DECIMALS product district month
END

10.33 PUSHLEVEL

The PUSHLEVEL command marks the start of a series of PUSH commands. You can then use a corresponding POPLEVEL statement to restore all the values saved by PUSH commands that are executed after PUSHLEVEL. POPLEVEL must specify the same marker as the PUSHLEVEL statement that starts the series. You can use PUSHLEVEL only within programs.

Syntax

PUSHLEVEL marker-expression

Parameters

marker-expression

A text value to mark the start of a series of PUSH commands all of whose saved values are to be popped at once. A POPLEVEL statement that specifies the exact same marker-expression restores the whole series of saved values.

Usage Notes

Considerations When Designing PUSHLEVEL and POPLEVEL Statements

Keep the following points in mind when coding pushlevel statements:

  • You can nest PUSHLEVEL/POPLEVEL pairs, if you specify a different marker for each pair, as illustrated in the following code.

    PUSHLEVEL 'firstlevel'
    PUSH PAGESIZE DECIMALS       < saves values in FIRSTLEVEL
    ...
    PUSHLEVEL 'secondlevel'
    PUSH month product           < Saves values in SECONDLEVEL
    ...
    POPLEVEL 'secondlevel'       < Restores values in SECONDLEVEL
    ...
    POPLEVEL 'firstlevel'        < Restores values in FIRSTLEVEL
    

    You do not normally need multiple levels in a single program. However, Oracle OLAP automatically creates nested levels when one program calls another program and each program contains a set of PUSHLEVEL and POPLEVEL commands.

  • When you specify the same marker for two or more PUSHLEVEL commands, a POPLEVEL statement specifying that same marker restores values that were saved only since the most recent PUSHLEVEL statement.

  • When you specify a different marker for two or more PUSHLEVEL commands, a POPLEVEL statement that specifies the marker of any PUSHLEVEL statement restores all the values that were saved since that statement, including values that were saved after later PUSHLEVEL commands.

Examples

Example 10-85 Creating Level Markers

You can use a PUSHLEVEL statement to establish a level marker called firstlevel, and then use PUSH to save the current values.

PUSHLEVEL 'firstlevel'
PUSH month DECIMALS ZSPELL

The level marker can be any text that is enclosed in single quotation marks. It can also be the name of a single-cell ID or TEXT variable, whose value becomes the name of the level marker. In the exit sections of the program, you can then use a POPLEVEL statement to restore all the values you saved since establishing the firstlevel marker.

POPLEVEL 'firstlevel'

Example 10-86 Nesting PUSHLEVEL and POPLEVEL Commands

You can nest PUSHLEVEL and POP LEVEL commands to save certain groups of values in one place in a program and other groups of values in another place in a program. The next example shows two sets of nested PUSHLEVEL and POPLEVEL commands.

PUSHLEVEL 'firstlevel'
PUSH PAGESIZE DECIMALS "Saves values in FIRSTLEVEL
        ...
PUSHLEVEL 'secondlevel'
PUSH month product     "Saves values in SECONDLEVEL
      ...
POPLEVEL 'secondlevel' "Restores values in SECONDLEVEL
       ...
POPLEVEL 'firstlevel'  "Restores values in FIRSTLEVEL

Normally, you do not use multiple sets of PUSHLEVEL and POPLEVEL commands in a single program. However, the nesting feature comes into play automatically when one program calls another program, and each program contains a set of PUSHLEVEL and POPLEVEL commands.

Example 10-87 One-Step Restoration and Nested Levels

The following program uses PUSHLEVEL 'rpt1' to mark for one-step restoration the original value of DECIMALS and the original status of month, product, and district, even though these are pushed separately in the program.

To demonstrate nesting, the program includes a nested PUSHLEVEL-POPLEVEL pair with 'rpt2' as its marker and some STATUS commands at various points. You can compare the program's output with the program to see how the status is affected.

DEFINE sales.RPT PROGRAM
PROGRAM
STATUS month product district
 
PUSHLEVEL 'rpt1'
PUSH DECIMALS month
DECIMALS = 0
LIMIT month TO 'Jan96'
REPORT WIDTH 8 DOWN district WIDTH 9 ACROSS product: expense
PUSH product
LIMIT product TO 'Racquets' 'Sportswear'
REPORT DOWN district ACROSS product: advertising
 
PUSHLEVEL 'rpt2'
PUSH district
LIMIT district TO 'Atlanta' 'Dallas' 'Chicago'
REPORT DOWN district ACROSS product: sales
BLANK
STATUS month product district
BLANK
 
POPLEVEL 'rpt2'
STATUS month product district
BLANK
POPLEVEL 'rpt1'
 
STATUS month product district
END

The sales.rpt program produces the following output.

The current status of MONTH is:
ALL
The current status of PRODUCT is:
ALL
The current status of DISTRICT is:
ALL
MONTH: JAN96
         ---------------------EXPENSE---------------------
         ---------------------PRODUCT---------------------
DISTRICT   Tents    Canoes   Racquets  Sportswear  Footwear
-------- --------- --------- --------- ---------- ----------
Boston      31,299    67,527    52,942     49,668    80,565
Atlanta     41,139    53,186    57,159    108,047    99,758
Chicago     27,768    45,621    53,756     65,055    81,639
Dallas      47,063    34,072   118,807    113,629    19,785
Denver      33,177    42,975    89,144     63,380    36,960
Seattle     41,043    64,009    26,719     38,970    46,900
Month: JAN96
               -----ADVERTISING-----
               -------PRODUCT-------
DISTRICT        RAcquets  Sportswear
-------------- ---------- ----------
Boston              3,784      3,352
Atlanta             4,384      9,509
Chicago             3,351      5,283
Dallas              8,700      8,340
Denver              6,215      4,654
Seattle             2,344      3,726
MONTH: Jan96
               --------SALES--------
               -------PRODUCT-------
DISTRICT        Racquets  Sportswear
-------------- ---------- ----------
Atlanta            61,895    129,616
Dallas            125,880    128,115
Chicago            58,649     77,490
The current status of MONTH is:
JAN96
The current status of PRODUCT is:
RACQUETS, SPORTSWEAR
The current status of DISTRICT is:
ATLANTA, DALLAS, CHICAGO
 
The current status of MONTH is:
JAN96
The current status of PRODUCT is:
RACQUETS, SPORTSWEAR
The current status of DISTRICT is:
ALL
 
The current status of MONTH is:
ALL
The current status of PRODUCT is:
ALL
The current status of DISTRICT is:
ALL

10.34 RECAP

The RECAP command sends statements that were previously entered during the current session to the current outfile or to a file that you specify. The statements are copied from the command log, which is a list of up to 256 statements that you have entered most recently during the current session.

Note:

RECAP statements are not included in the command log.

Syntax

RECAP [number|ALL] [ 'search-text' ] [ FILE file-name ]

Parameters

number

A positive INTEGER that indicates the number of statements to be provided. When you specify search-text, RECAP provides this number of statements from the subset that contains the search-text string. When you do not specify search-text, RECAP provides this number of statements from the most recently executed portion of the command log. The default number is 10.

ALL

When you specify search-text, ALL requests every statement that meets the search requirements. When you do not specify search-text, ALL requests every statement in the command log.

search-text

A quoted text literal. When you specify this argument, RECAP searches the statements in the command log for the ones that contain search-text. The search is not case-sensitive. These statements then compose the subset from which RECAP provides number or ALL statements.

FILE file-name

Writes the output of a RECAP statement to the specified file For file-name specify a text expression that is the name of the file to which output should be written. Unless the file is in the current directory, you must include the name of the directory object in the name of the file.

Note:

Directory objects are defined in the database, and they control access to directories and file in those directories. You can use a CDA statement to identify and specify a current directory object. Contact your Oracle DBA for access rights to a directory object where your database user name can read and write files.

Usage Notes

Order of search-text Parameter

When you use both the search-text and the ALL or number arguments, you must specify search-text second.

RECAP with No Parameter

When you specify RECAP without an argument, the ten most recent statements are provided.

Re-Executing Statements

You can use the output of RECAP to edit a previously executed statement with REEDIT, or reexecute a previously executed statement with REDO.

Identifying Files and Directories

When specifying files and directories in OLAP DML statements, it is good practice to always enclose them in single quotes.

Examples

Example 10-88 Obtaining the Last Three Statements Containing "actual"

The following RECAP statement requests the three most recent statements that included the text literal "actual."

RECAP 3 'actual'

This statement could produce the following output.

       COMMAND LOG
    3: dsc actual
    5: report total(actual)
    8: report average(actual) 

10.35 REDO

The REDO command re-executes a statement that you entered earlier in your session. The statement is retrieved from the command log, which is a list of up to 256 statements that you have entered most recently during the current session. REDO enables you to changes in the statement before it is re-executed.

Note:

REDO statements themselves are not included in the command log; however, the statements re-executed by REDO are included.

Syntax

REDO [number|index] 'original' 'replacement' [specifier

Parameters

number

A positive INTEGER that indicates the number of the statement to be re-executed. You can display the statements, with their numbers, using a RECAP statement.

index

A negative INTEGER or 0 (zero) that indicates the position of the statement to be re-executed relative to the end of the command log. The most recent statement is 0, the one before that is -1, and so on. The default is 0.

original

A text literal that is part of the statement to be re-executed.

replacement

A text literal that should replace original when the statement is re-executed.

specifier

A specifier listed in the following table. Each specifier indicates where text replacement should occur in the re-executed statement.

Table 10-2 Valid Values for REDO specifier

Specifier Meaning

FIRST

Indicates that only the first occurrence of original should be changed to replacement.

LAST

Indicates that only the last occurrence of original should be changed to replacement.

n

A number indicating which occurrence of original should be changed to replacement. For example, 3 indicates the third occurrence.

ALL

Indicates that all occurrences of original should be changed to replacement

*

Indicates that all occurrences of original should be changed to replacement.

The default is ALL. When you do not provide a specifier, all occurrences of original are changed to replacement.

Usage Notes

REDO with No Argument

When you type REDO without an argument, the most recent statement are re-executed.

Case-Sensitivity

When matching original with the text of the statement to be re-executed, REDO ignores case differences. For example, assume you specify AT as original, REDO matches it with at, At, aT, or AT in the statement.

When replacing original with replacement, REDO retains the case of all characters in replacement. For example, assume you specify ShOw as replacement, that is exactly how it appears in the re-executed statement.

Examples

Example 10-89 Redoing a Report

The following output is the result of recap 2 statement.

   COMMAND LOG
6: fetch w 20 down division total(actual)
7: listnames

The following REDO statement re-executes the FETCH statement with a different variable.

REDO 6 'actual' 'budget'

10.36 REEDIT

The REEDIT command edits a statement that you entered earlier in your session. The statement is retrieved from the command log, which is a list of up to 256 statements that you have entered most recently during the current session. REEDIT enables you to change the statement without executing it, so you can edit it sequentially.

The REDO command is similar to REEDIT, except that the statement is executed after you edit it.

Note:

REEDIT statements themselves are not included in the command log; however the statements re-executed by REEDIT are included.

Syntax

REEDIT [number|index] 'original' 'replacement' [specifier

Parameters

number

A positive INTEGER that indicates the number of the statement to be edited. You can display the statements, with their numbers, using a RECAP statement.

index

A negative INTEGER or 0 (zero) that indicates the position of the statement to be edited relative to the end of the command log. The most recent statement is 0, the one before that is -1, and so on. The default is 0.

original

A text literal that is part of the statement to be edited.

replacement

A text literal that should replace original when the statement is edited.

specifier

A specifier listed in the following table. Each specifier indicates where text replacement should occur in the edited statement.

Table 10-3 Valid Values for REEDIT specifier

Specifier Meaning

FIRST

Indicates that only the first occurrence of original should be changed to replacement.

LAST

Indicates that only the last occurrence of original should be changed to replacement.

n

A number indicating which occurrence of original should be changed to replacement. For example, 3 indicates the third occurrence.

ALL

Indicates that all occurrences of original should be changed to replacement

*

Indicates that all occurrences of original should be changed to replacement.

The default is ALL. When you do not provide a specifier, all occurrences of original are changed to replacement.

Usage Notes

REEDIT with No number or index Argument

When you type REEDIT without number or index, the most recent statement is edited.

Case-Sensitivity

When matching original with the text of the statement to be edited, REEDIT ignores case differences. For example, assume you specify AT as original, REEDIT matches it with at, At, aT, or AT in the statement.

When replacing original with replacement, REEDIT retains the case of all characters in replacement. For example, assume you specify ShOw as replacement, that is exactly how it appears in the edited statement.

Examples

Example 10-90 Editing Multiple Values in a LIMIT Command

The following example illustrates why it could be helpful to use a REEDIT statement to edit a statement several times before executing it. With REEDIT commands, you can edit multiple values in a LIMIT command before executing it. When you enter a REDO statement, the LIMIT command is executed.

The following output is the result of a recap 1 statement.

   COMMAND LOG
6: limit mydim to 1 to 10, 15 to 20, 24 to 28, 33 to 40

The statement

REEDIT 6 '1' '2' FIRST

produces the following output.

7: limit mydim to 2 to 10 , 15 to 20, 24 to 28, 33 to 40

The statement

REEDIT 7 '15' '18'

produces the following output.

8: limit mydim to 2 to 10 , 18 to 20, 24 to 28, 33 to 40
 

The statement

REDO 8 '40' '41'

makes one more change and re-executes the LIMIT command with the new values. It also produces the following output.

9: limit mydim to 2 to 10 , 18 to 20, 24 to 28, 33 to 41

10.37 REGRESS

The REGRESS command calculates a simple multiple linear regression. The optional WEIGHTBY keyword lets you calculate a weighted regression when some data points are more reliable than others.

You can then execute REGRESS.REPORT to produce a standard report of the regression. You can also use the INFO function to obtain portions of the results for use in your own customized reports or for further analysis.

Tip:

To performing more complex regression analysis use a forecasting context as discussed in "Forecasting Programs".

Syntax

REGRESS [NOINTERCEPT] dependent independent... [WEIGHTBY weight]

Parameters

NOINTERCEPT

Directs Oracle OLAP to suppress the constant term (intercept) in the regression equation. The default is to calculate a constant term.

dependent

An expression to be used as the dependent variable in the regression.

In calculating the results, REGRESS loops over all the dimensions of the dependent and independent variables.

independent

One or more expressions to be used as the independent variables (regressors) in the regression.

WEIGHTBY weight

Specifies a weighted regression. The numeric expression weight supplies the weights for each data point (observation). Giving higher weights to more reliable observations results in a higher quality regression. WEIGHTBY must come last in the REGRESS command.

When weight is less than zero for any observation, an error occurs. When weight is equal to zero for any observation, that observation is ignored in the calculation. When WEIGHTBY is omitted, an unweighted regression is calculated.

Usage Notes

Ignoring NA Values

In performing its calculations, the REGRESS command ignores any observation that has an NA value.

Producing a Standard Report

The standard report for a regression shows the coefficient, standard error, and T-ratio for each independent variable; and the R-square, F-Statistic, number of observations, and standard error of estimate for the regression. To produce this report, type the following.

REGRESS.REPORT

Obtaining Results

For information on how to obtain portions of the results of REGRESS for your own reports or further analysis, use an INFO statement.

Examples

Example 10-91 Simple Regression

The following statements limit the product dimension to Canoes, then use regression to investigate the influence of advertising, price, and expense on the sales of canoes.

LIMIT product TO 'Canoes'
REGRESS NOINTERCEPT sales advertising price expense

You can now execute REGRESS.REPORT as illustrated in Example 10-93 to see the results of the regression.

Example 10-92 Weighted Regression

The following statements use a weighted regression, in which districts are weighted using a variable called reliability that has the following definition and values.

DEFINE reliability VARIABLE DECIMAL <district>

DISTRICT       RELIABILITY
-------------- -----------
Boston                1.00
Atlanta               0.90
Chicago               1.00
Dallas                0.80
Denver                0.90
Seattle               0.60

The following statements perform the regression.

REGRESS NOINTERCEPT sales advertising price expense -
WEIGHTBY reliability

You can now execute REGRESS.REPORT as illustrated in Example 10-93 to see the results of the regression.

10.38 REGRESS.REPORT

The REGRESS.REPORT program produces a standard report of a regression performed using the REGRESS command.

Syntax

REGRESS.REPORT

Examples

Example 10-93 Report for a Simple Regression

Assume that you have performed the simple regression illustrated in Example 10-91 . You can now execute REGRESS.REPORT to see the results of the regression.

                              Regression Analysis
                              ===================
 
       Dependent Variable: SALES
        WEIGHTBY Variable: NONE
 
Regressor                Coefficient      Std. Error     T-ratio
--------------------    ------------    ------------    --------
ADVERTISING                     0.36            0.16        2.24
PRICE                          -8.66            1.80       -4.82
EXPENSE                         1.05            0.01       79.69
 
      Corrected R-square                   1.00
      F-Statistic (2, 141)                   NA
      Number of observations                144
      Standard error of estimate       1,477.16

Example 10-94 Report for a Weighted Regression

Assume that you have performed the simple regression illustrated in Example 10-92 . You can now execute REGRESS.REPORT to see the results of the regression.

                              Regression Analysis
                              ===================
 
       Dependent Variable: SALES
        WEIGHTBY Variable: RELIABILITY
 
Regressor                Coefficient      Std. Error     T-ratio
--------------------    ------------    ------------    --------
ADVERTISING                     0.44            0.17        2.64
PRICE                          -8.03            1.92       -4.19
EXPENSE                         1.04            0.01       76.45
 
      Corrected R-square                   1.00
      F-Statistic (2, 141)                   NA
      Number of observations                144
      Standard error of estimate       1,373.15

10.39 RELATION command

The RELATION command identifies a relation as the default relation for a specified dimension of the current object; or removes the default relation information from the current object. For more information on default relations, see "Using Related Dimensions in Expressions".

Note:

Do not confuse the RELATION command with the RELATION statements in AGGMAP or ALLOCMAP.

Syntax

RELATION {dimension-name relation-name }| DELETE { ALL | dimension-name}

Parameters

dimension-name

The name of a previously-defined dimension. The dimension specified by the dimension-name argument must be a dimension of the currently considered object for which you want to specify or delete a default relation.

Note:

The dimension specified by the dimension-name argument must be a dimension of the currently considered object. The current object is the object that has been most recently defined or considered during the current session. To make an object definition the current definition, use a CONSIDER statement.

relation-name

The name of a previously-defined relation that Oracle OLAP uses as the default relation for the dimension specified by dimension-name.

DELETE

Specifies removal of previously-specified default relation information.

ALL

Removes all previously-defined default relation information.

Usage Notes

How Oracle OLAP Chooses Between Multiple Relations

When there are multiple relations between the two dimensions and you attempt to perform calculation on one of those dimension based on related dimensions, Oracle OLAP chooses the relation to use when executing the statement as follows:

  1. Uses the relation specified in the statement, if any.

  2. Uses the default relation for the dimension. Oracle OLAP determines the default relation as follows:

    1. When you have specified a default relation using the RELATION command, Oracle OLAP recognizes that relation as the default relation.

    2. When you have not specified a default relation using the RELATION command, Oracle OLAP recognizes the first relation that you defined as the default relation.

Identifying Default Relations

Use the OBJ function with the RELATION keyword to identify the default relation information for an object.

Multiple RELATION Commands Against the Same Object

Unlike other statements that operate against the most recently considered object (for example, an LD statement), a new RELATION command does not replace previously-issued RELATION commands. Instead, issuing multiple RELATION commands against the same object has a cumulative effect.

Examples

Example 10-95 Specifying a Default Relation Using the Relation Command

Assume that you defined the following analytic workspace objects (in the following order).

DEFINE CITY DIMENSION TEXT
DEFINE DISTRICT DIMENSION TEXT
DEFINE CITY_DISTRICT RELATION DISTRICT <CITY>
DEFINE CITY_REDISTRICT_1 RELATION DISTRICT <CITY>

REPORT city_district
CITY                    CITY_DISTRICT
-------------------- --------------------
Annapolis            Southern
Bethesda             Southern
Charlotte            Southern
Gettysburg           Southern
Greensboro           Southern
Raleigh              Southern
Reston               Southern
Rochester            Southern
Virginia Beach       Southern
Washington           Capital
 
 
REPORT city_redistrict_1
CITY                  CITY_REDISTRICT_1
-------------------- --------------------
Annapolis            Capital
Bethesda             Capital
Charlotte            Southern
Gettysburg           Southern
Greensboro           Southern
Raleigh              Southern
Reston               Southern
Rochester            Southern
Virginia Beach       Capital
Washington           Capital

As the following OBJ statements illustrate, the city_district relation is the default relation between city and district because the city_district relation was the first relation defined between city and districtt and a default relation has not been specified using a RELATION statement.

SHOW OBJ (RELATION ACTUAL 'city' 'district')
CITY_DISTRICT
 
SHOW OBJ (RELATION SPECIFIED 'city' 'district')
NA
 

Assume that you now issue the following statements to limit district to Washington and make the city_redistrict_1 relation the default relation.

 
LIMIT city TO district
CONSIDER city
RELATION city city_redistrict_1
 

As the following OBJ statements illustrate, now the city_redistrict_1 relation that you specified with the RELATION statement is the default relation between city and district.

SHOW OBJ (RELATION ACTUAL 'city' 'district')
CITY_REDISTRICT_1
SHOW OBJ (RELATION SPECIFIED 'city' 'district')
CITY_REDISTRICT_1
 

Also, as the following statements illustrate, when you limit city to district, you get the same results as limiting city to the city_redistrict_1 relation

LIMIT city TO district
 
REPORT city
CITY
--------------------
Annapolis
Bethesda
Virginia Beach
Washington
 
 
LIMIT city to ALL
LIMIT city to city_redistrict_1
 
REPORT city
CITY
--------------------
Annapolis
Bethesda
Virginia Beach
Washington

10.40 RELEASE

When an analytic workspace is attached in multiwriter mode, the RELEASE command changes the access mode of the specified variables, relations, valuesets, dimensions, or one or more partitions in a variable from read/write (acquired) access to read-only access.

Syntax

RELEASE  objects

Parameters

objects

One or more variables, relations, valuesets, dimension names, or analytic workspace names, separated by commas, that you want to release. To specify individual partitions of a partitioned variable, use the following syntax.

     variable_name (PARTITION partition_name [, PARTITION partition_name ]...)

Precede each analytic workspace name with AW using the following syntax:

AW analytic workspace name

When you specify an analytic workspace in this list, all acquired objects in that analytic workspace are released after all pending changes are made to them. All changes made to the variables, relations, valuesets, or dimensions before a RELEASE statement executes are preserved as private changes after the release statement.

Usage Notes

Releasing Non-Updated or Uncommitted Objects

Similarly to using an AW DETACH statement for analytic workspaces that has been updated. Using RELEASE for objects that have been updated does not allow others to acquire the object until you commit or roll back the transaction. It may still be useful to release an object that has been updated before a commit when one wants to make further what-if changes and later needs to use UPDATE to update all acquired variables.

Releasing a Dimension Causes the Dimension to Revert

When you release an acquired dimension, the dimension is automatically reverted (see the REVERT command for an explanation of what it means to revert a dimension).

As the following code illustrates, releasing an acquired dimension causes an automatic revert.

User A issues the following OLAP DML statements.

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC time WAIT
MAINTAIN time ADD 'Y2002'
actuals (time 'Y2002', ...) = 37
REPORT time --> ..., 'Y2002'
... report
SHOW actuals (time 'Y2002', ...) --> 37
RELEASE time
REPORT time --> ... (no 'Y2002')
AW ATTACH myworkspace MULTI
... report
ACQUIRE RESYNC actuals, time WAIT
MAINTAIN time ADD 'Y2002'
actuals (time 'Y2002', ...) = 37
REPORT time --> ..., 'Y2002'
SHOW actuals (time 'Y2002', ...) --> 37
... report
REVERT time
REPORT time --> ... (no 'Y2002')
MAINTAIN time ADD 'Y2002'
... report
REPORT time --> ..., 'Y2002'
SHOW actuals (time 'Y2002', ...) --> NA
... report

Examples

Example 10-96 Two Users Modifying Different Objects in the Same Analytic Workspace

A classic use of multiwriter attachment mode is to allow two users to modify two different objects in the same analytic workspace. For example, assume that an analytic workspace has two variables: actuals and budget. Assume also that one user (user A) wants to modify actuals, while another user (user B) wants to modify budget. In this case, after attaching the analytic workspace in the multiwriter mode, each user acquires the desired variable, performs the desired modification, updates, commits the changes, and then, either detaches the workspace or releases the acquired variable.

User A executes the following statements.

AW ATTACH myworkspace MULTI
ACQUIRE actuals
... make modifications
UPDATE MULTI actuals
COMMIT
RELEASE actuals
AW DETACH myworkspace

While, at the same time, User B executes the following statements.

AW ATTACH myworkspace MULTI
ACQUIRE budget
... make modifications
UPDATE MULTI budget
COMMIT
RELEASE budget
AW DETACH myworkspace

Example 10-97 Using RELEASE After UPDATE But Before COMMIT

Using a RELEASE statement does not always allow other users to acquire the released variable. For example, when you have updated a variable but have not committed the changes, the execution of a RELEASE statement has no effect on other users until a commit occurs. However, when you use a simple UPDATE to update all acquired variables, it can be useful to release a variable after updating it but before committing it. When a variable is released after the first update, it is not be included in the list of updated variables for the second update. The following code illustrates situations where user B1 releases budget at different times.

Assume that User B1 issues the following statements

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT
make changes C1
RELEASE budget
UPDATE
make changes C2
UPDATE
COMMIT

User B2 could issue the following statements

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT

User B2 gets budget and sees no changes and issues the following statements.

...
AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT
make changes C1
UPDATE
RELEASE budget
make changes C2
UPDATE
COMMIT
...
AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT

Alternatively, User B2 gets budget and sees changes C1 and issues the following statements.

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT
make changes C1
UPDATE
make changes C2
RELEASE budget
UPDATE
COMMIT
...
AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT

Or, as another alternative, User B2 gets budget and sees changes C1 and issues the following statements.

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT
make changes C1
UPDATE
make changes C2
UPDATE
COMMIT
RELEASE budget
...
AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget WAIT

At this point, User B2 gets budget and sees changes C2

10.41 REMOVE_CUBE_MODEL

Removes a MODEL (in an aggregation) statement for a specified model that is a sub-object of the cube dimension from the aggregation map of that cube dimension. The changes made when this program executes are not transactional; an automatic COMMIT is executed as part of the program.

Note:

You cannot use this program to modify a cube dimension if a materialized view exists for that cube dimension or any cube in which it participates.

Syntax

CALL REMOVE_CUBE_MODEL(logical_cube, logical_dim, model_name, is_static_model)

Parameters

CALL

Because REMOVE_CUBE_MODEL is an OLAP DML program with arguments, you invoke it using the OLAP DML CALL statement.

logical_cube

A text expression that is the name of the cube as defined in the Oracle data dictionary.

logical_dim

A text expression that is the Oracle data dictionary name of the cube dimension being modified.

model_name

A text expression that is the name of the logical model that is associated with logical_dim.

is_static_model

A Boolean expression that specifies whether the MODEL statement to be removed is before or after the RELATION (for aggregation) statements in the aggmap for logical_cube.

The default value is TRUE which means that MODEL statement to be removed is before the RELATION statements (that is, model_name is a static model).

Specify FALSE if the MODEL statement you want to remove is after the RELATION statements (that is, model_name is a dynamic model).

10.42 REMOVE_DIMENSION_MEMBER

The REMOVE_DIMENSION_MEMBER program removes an OLAP cube dimension member from one or more hierarchies, or entirely removes an OLAP cube dimension member from a cube dimension.

Note:

You cannot use this program to modify a cube dimension if a materialized view exists for that cube dimension or any cube in which it participates.

Syntax

CALL REMOVE_DIMENSION_MEMBER(member_id, logical_dim, hier_list, [ auto_compile ])

Parameters

CALL

Because REMOVE_DIMENSION_MEMBER is an OLAP DML program with arguments, you invoke it using the OLAP DML CALL statement.

member_id

A text expression that is the member that you want to remove from the cube dimension hierarchies.

logical_dim

A text expression that is the Oracle data dictionary name of the cube dimension being modified.

hier_list

A multi-line text expression consisting of the Oracle data dictionary names of all of the hierarchies from which you want to remove the cube dimension member. Specify one hierarchy name per line.

To entirely remove a member from the dimension, specify NA.

auto_compile

A Boolean expression that specifies whether or not you want related analytic workspace objects (for example, changes to the parent relation) to be updated immediately.

The default value is TRUE in which case all of the changes to the analytic workspace that are needed to remove the cube dimension member happen now.

Specify FALSE only when, for performance reasons, you want to make a bulk set of changes before issuing a compile. In this case, you need to explicitly compile the cube dimension before the values of the analytic workspace objects take effect as described in "Explicitly Compiling a Cube Dimension".

Note:

Regardless of the value that you specify for this argument, the new member is always immediately removed from the dimension -- even when an error is signaled during compilation.

Examples

Example 10-98 Removing OLAP Cube Dimension Members From a Hierarchy

  1. Execute the following SQL statement that reports on the values of the my_time cube dimension.

    select dim_key||'  '||level_name||'  '||parent 
       from my_time_lvl_hier_view 
       order by dim_key asc;
    

    The values this statement returns are shown below.

    DIM_KEY||''||LEVEL_NAME||''||PARENT
    -------------------------------------------------------------------------------
    L1_0  L1
    L1_1  L1
    L1_2  L1
    L2_1  L2  L1_1
    L2_2  L2  L1_1
    L2_3  L2  L1_2
    L3_1  L3  L2_1
    L3_2  L3  L2_1
    L3_3  L3  L2_2
    L3_4  L3  L2_2
    L3_5  L3  L2_2
    L3_6  L3  L2_3
    
    12 rows selected.
     
  2. Execute the following SQL statement that calls a user-written program named remove_12_1 OLAP DML program.

    exec dbms_aw.execute('call my_util_aw!remove_l2_1');
    

    The contents of the user-written remove_12_1 program are shown below.

    Note:

    The program uses:

    • The OBJORG function to specify the OLAP DML objects that physically implement the my_time cube dimension.

    • The REMOVE_DIMENSION_MEMBER program provided with the OLAP DML to remove L2_1 and its descendants from the my_time cube dimension.

    DEFINE REMOVE_L2_1 PROGRAM
    PROGRAM
     
      VARIABLE _aw_dim       text
      VARIABLE _parentrel    text
      VARIABLE _members      text
      VARIABLE _member       text
      VARIABLE _i            integer
     
      " Removes L2_1 and descendants
      _aw_dim = OBJORG(DIM 'my_time')
      _parentrel = OBJORG(PARENTREL 'my_time')
     
      LIMIT &_aw_dim TO 'L2_1'
      LIMIT &_aw_dim ADD DESCENDANTS USING &_parentrel
      _members = VALUES(&_aw_dim)
      _i = 1
      WHILE _i LE NUMLINES(_members)
      DO
        _member = EXTLINES(_members, _i, 1)
        _i = _i + 1
        CALL REMOVE_DIMENSION_MEMBER(_member, 'my_time', NA, NO)
      DOEND
     
      UPDATE
      COMMIT
    END
     
  3. Execute the following SQL statement (the same statement as in Step 1) that shows the values of the my_time cube dimension after removal.

    select dim_key||'  '||level_name||'  '||parent 
        from my_time_lvl_hier_view 
        order by dim_key asc;
    

    The values after removal are shown below.

    DIM_KEY||''||LEVEL_NAME||''||PARENT
    --------------------------------------------------------------------------------
    L1_0  L1
    L1_1  L1
    L1_2  L1
    L2_2  L2  L1_1
    L2_3  L2  L1_2
    L3_3  L3  L2_2
    L3_4  L3  L2_2
    L3_5  L3  L2_2
    L3_6  L3  L2_3
     
    9 rows selected.

10.43 REMOVE_MODEL_DIMENSION

The REMOVE_MODEL_DIMENSION program removes aDIMENSION (in models) statement from a cube dimension's model. The changes made when this program executes are not transactional; an automatic COMMIT is executed as part of the program.

Syntax

CALL REMOVE_MODEL_DIMENSION(logical_dim, model_name, explicit_dim)

Parameters

CALL

Because REMOVE_MODEL_DIMENSION is an OLAP DML program with arguments, you invoke it using the OLAP DML CALL statement.

logical_dim

A text expression that is the Oracle data dictionary name of the cube dimension being modified.

model_name

A text expression that is the name of the logical model that is associated with logical_dim.

explicit_dim

A text expression that is the identifier of the dimension that you want to remove from the cube dimension's model.

10.44 RENAME

The RENAME command changes the name of an object in an analytical workspace.

Syntax

RENAME oldname newname [AW workspace]

Parameters

oldname

The name of an existing object in an analytic workspace. You can specify a qualified object name to indicate the attached workspace in which the object resides. As an alternative, you can use the AW keyword to specify the workspace. Do not use both.

When you do not use a qualified object name or the AW keyword to specify an analytic workspace, the object is renamed in the current workspace.

For an unnamed composite, use the same syntax that was used to create it. See "Naming an Unnamed Composite".

newname

The new name. The new name of an analytic workspace object cannot duplicate any other name in the workspace in which the object exists. Choose a name according to the rules for naming analytic workspace objects (see the main entry for the DEFINE command. To change a named composite to an unnamed composite, use the SPARSE keyword as the newname argument. See "Unnaming a Named Composite".

AW workspace

The name of an attached workspace in which you want to rename the object. When you do not use a qualified object name or the AW keyword to specify an analytic workspace, the object is renamed in the current workspace.

Usage Notes

Updating Associated Objects

When you change the name of a variable, objects that use that variable, such as formulas, are not automatically updated.

When you change the name of a dimension, the definitions of any objects that are dimensioned by that dimension are automatically updated. Additionally, any valuesets for the renamed dimension are automatically updated for the new name.

RENAME and PERMIT

You may not rename an object when a PERMIT statement denies you the right to change its permission. Renaming an object does not affect permission associated with it.

Naming an Unnamed Composite

You can name an unnamed composite with a RENAME statement. The following example assigns the name m.prod to an unnamed composite that is dimensioned by market and product.

RENAME SPARSE <market product> m.prod

Unnaming a Named Composite

You can change a named composite to an unnamed composite when the composite has no properties or permission restrictions and when there is at least one object dimensioned by it. In addition, there cannot be an unnamed composite with the same dimensions in the same order as the named composite, and the named composite cannot be used in the dimension list of any unnamed composite. To change a named composite to an unnamed composite, use the SPARSE keyword as the newname argument. The following example changes the named composite m.prod to an unnamed composite.

RENAME m.prod SPARSE

Restrictions on Renaming Composites

You cannot rename a composite when it is a base dimension of an unnamed composite, or when one of its base dimensions is an unnamed composite.

Examples

Example 10-99 Renaming a Program

This statement changes the name of the program testreport to sales.report.

RENAME testreport sales.report 

10.45 REPORT

The REPORT command produces a formatted report for one or more data expressions. REPORT automatically loops over the dimensions of the expression. REPORT sends the output to the current outfile.

Syntax

REPORT [NOHEAD] [GRANDTOTALS] [[SUBTOTALS] {GROUP group-dimension}...] -       [[SUBTOTALS] [attributes] DOWN down-dimension] -      [[ROWTOTALS] { ACROSS across-dimension [limit-clause]: }... ] -      [SUBTOTALS] [attributesexpression(s)

Parameters

When you specify only the expression argument, REPORT produces a report with the layout described in "Default Layout". When you specify some but not all of the dimensions of an expression in GROUP, DOWN, or ACROSS phrases, REPORT follows the default layout as closely as possible with the unspecified dimensions.

NOHEAD

Specifies that the report should contain no initial blank line and no headings. NOHEAD overrides any HEADING arguments you specify for the attributes argument and suppresses all headings that the REPORT command normally generates automatically.

GRANDTOTALS

Includes a grand total for each numeric column at the end of your report.

SUBTOTALS

Includes subtotals for numeric columns. A row of dashes precedes each row of subtotals. When you specify SUBTOTALS for an expression or DOWN phrase, you get subtotals for each GROUP dimension (or composite). When you specify SUBTOTALS for a GROUP phrase, you get subtotals for the specified dimension and for any slower-varying GROUP dimensions. The subtotals for a group appear at the bottom of the last slice in the group.

GROUP

Produces a separate group, or two-dimensional slice, of the data for each value of group-dimension. You can use the GROUP phrase more than once to specify multiple GROUP dimensions (or composites). In this case, you produce a separate slice for each combination of the values of the GROUP dimensions.

group-dimension

The name of a dimension or composite from which to retrieve the values to use as group labels, or one or more TEXT expressions that are the actual values you want to use as group labels:

  • When group-dimension is the name of a composite or a conjoint dimension, Oracle OLAP creates a separate group for each base dimension.

  • When group-dimension is a TEXT expression, the expression must be dimensioned only by the desired GROUP dimension, and each value of the expression should be descriptive text that corresponds to its associated dimension value.

The dimensions that you specify in a GROUP phrase are not required to be relevant to the data they loop over. See "Default Layout".

DOWN

Specifies that the report includes row labels (that is, one or more columns on the left side of your report that label the other values). You can have only one DOWN phrase.

down-dimension

The name of a dimension or composite from which to retrieve the values to use as row labels, or one or more TEXT expressions that are the actual values you want to use as row labels.

  • When down-dimension is the name of a non-conjoint dimension, REPORT produces only one column of row labels.

  • When down-dimension is the name of a composite or a conjoint dimension, Oracle OLAP creates a separate column for each base dimension.

  • When down-dimension is a TEXT expression, the expression must be dimensioned only by the desired DOWN dimension, and each value of the expression must be descriptive text that corresponds to its associated dimension value.

The dimensions that you specify in a DOWN phrase are not required to be relevant to the data they loop over. See "Specifying Extra Dimensions".

ROWTOTALS

Includes a column headed "TOTAL" at the right side of the report with a total for each numeric row. Including a row total in your report does not imply either column subtotals or a grand total.

ACROSS

Produces a row of column headings across the top of your report, one for each value in dimension. Under each heading, REPORT produces a column of data for the data expression you specify. You can have multiple ACROSS phrases (or composites) in the report.

across-dimension

The name of a dimension or composite from which to retrieve the values to use as column headings, or one or more TEXT expressions that are the actual values you want to use as column headings.

  • When across-dimension is the name of a composite or a conjoint dimension, Oracle OLAP creates a separate heading column for each base dimension.

  • When across-dimension is a TEXT expression, the expression must be dimensioned only by the desired across-dimension, and each value of the expression should be descriptive text that corresponds to its associated dimension value. For information on providing formatted labels for a dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR, see "Formatting DAY, WEEK, MONTH, QUARTER, and YEAR Dimension Values".

The dimensions that you specify in an ACROSS phrase are not required to be relevant to the data they loop over. See "Specifying Extra Dimensions".

limit-clause

When you specify a dimension in the ACROSS phrase, the temporary status of that dimension during the execution of the execution of the REPORT statement. (You cannot include a limit-clause argument when you specify a composite in the ACROSS phrase.)

The syntax of limit-clause is the same syntax as any of the limit-clause arguments in the various forms of the LIMIT command (that is, the syntax of the LIMIT command after the limit-type argument such as "TO"). For the syntax of these arguments, see LIMIT (using values) command, LIMIT using LEVELREL command, LIMIT (using parent relation), LIMIT (using related dimension) command, LIMIT NOCONVERT command, and LIMIT command (using POSLIST).

When the limits you specify result in an empty status for the dimension, an error occurs (regardless of the setting of the OKNULLSTATUS option). However, when you include the phrase IFNONE label, the error is suppressed and execution of your program branches to the specified label, where you can handle the error.

attributes

One or more format attributes from Table 10-4 that specify how to format the data. For information on providing formatted labels for a dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR, see "Formatting DAY, WEEK, MONTH, QUARTER, and YEAR Dimension Values".

Tip:

When a variable has a formatting property attached to its definition, you can use the OBJ function to obtain the value of that property and use it as the value of an attribute in a REPORT statement.

When you do not specify any attributes, Oracle OLAP formats the data values using the default format described in "Default Layout". In this case, Oracle OLAP automatically determines the width of the columns, the number of decimal places, whether commas are used to mark thousands in numeric values, and so on.

Table 10-4 Formal Attributes for Data Values in a Report

Attribute Meaning

HEADING 'text'

Specifies text to use instead of default column headings. When you use the HEADING attribute, the position of the heading you specify varies depending on how many expressions it must span in your report. Consequently, your heading may or may not replace a default heading. Also, when you use the HEADING attribute to specify a column title that is wider than the column width, the text of the title wraps within the width of its column.

WIDTH n

(Abbreviated: W.) Makes the column n spaces wide. The maximum width is 4,000 characters. Columns with a width of 0 (zero) are suppressed.(See also "Default Values for the Width Attribute".)

TRUNCATE

(Abbreviated: TRUNC.) Truncates a character value to the column width when it does not fit in the column.

NOTRUNCATE

(Abbreviated: NOTRUNC) Creates additional lines when the character value does not fit in the column. (Default.)

CENTER

(Abbreviated: C.) Centers the value within its column.

LEFT

(Abbreviated: L.) Left-justifies the value within its column. (Default for text data.)

RIGHT

(Abbreviated: R.) Right-justifies the value within its column. (Default for numeric and Boolean data.)

SPACE n

(Abbreviated: SP.) Precedes the column with the specified number of spaces.

(By default, REPORT precedes the first column by 0 spaces, and other columns by 1 space.)

FILL 'char'

Puts char into unused positions in the column. (The default fill character is a space.)

COMMA

Marks thousands and millions with commas or the character currently recorded in the THOUSANDSCHAR option. Overrides the setting of the COMMAS option.

NOCOMMA

Does not marks thousands and millions. Overrides the setting of the COMMAS option.

PAREN

Uses parentheses to indicate negative numbers. Overrides the setting of the PARENS option

NOPAREN

Uses the minus sign to indicate negative numbers. Overrides the setting of the PARENS option.

DECIMAL n

(Abbreviated: D.) Shows n decimal places. Decimal places are separated using the character currently recorded in the DECIMALCHAR option. Overrides the value of the DECIMALS option.

Note: REPORT suppresses decimal places in row and column totals of integer data unless you specify the DECIMAL attribute for the totaled expression. Additionally, when you set the DECIMAL attribute to 0 and you use the NOLEADINGZERO keyword, any decimal values between -1 and 1 that are rounded to 0 are not shown.

MDECIMAL n

Shows n decimal places in numbers formatted with M-notation; n can be any number from 0 to 16, or 255.

NODECIMAL

Shows the number of decimal places specified by the setting of the DECIMALS option. (Default.)

EDECIMAL n

Shows n decimal places in numbers formatted with E-notation; n can be any number from 0 to 16, or 255.

ENOTATION

Always uses scientific notation, also called exponential notation or E-notation (appends "E", and includes a sign before the exponent, for example, .230E+2 or .230E-2).

NOENOTATION

Does not use E-notation; instead, uses to conditional M-notation.

CENOTATION

Conditionally uses E-notation, when needed to make a value fit in a column.

MNOTATION

Always uses M-notation (divides values by one million and appends "M").

NOMNOTATION

Does not use M-notation; instead, uses asterisks for oversize values.

CMNOTATION

Conditionally uses M-notation, when needed to make a value fit in a column. (Default.)

FOLDDOWN

For a multiline character value, places the first line on the row with the other values, and places additional lines below the rest of the row; also strips any leading or trailing spaces. (Default.)

FOLDUP

For a multiline character value, places all but the last line above the rest of the row, and the last line on the row with the other values; also strips any leading or trailing spaces.

INDENT n

Indents the value n spaces within its column. The default is 0.

LEADINGZERO

Puts a leading zero before decimal numbers between -1 and 1.

NOLEADINGZERO

Suppresses leading zeros before decimal numbers between -1 and 1.

CNLEADINGZERO

Puts a leading zero before decimal numbers between -1 and 1 when it does not cut off any significant digits. (Default.)

LSET 'text'

Adds text to the left of the value. When you use LSET with an expression that contains NA values, the text you specify with LSET is not included to left of any NA value

NOLSET

Does not add anything to the left of the value. (Default.)

RSET 'text'

Adds text to the right of the value. When you use RSET with an expression that contains NA values, the text you specify with RSET is not included to right of any NA value.

NORSET

Does not add anything to the right of the value. (Default.)

NASPELL 'text'

Uses text instead of NA values. Overrides the setting of the NASPELL option.

NONASPELL

Spells NA values as indicated by the NASPELL option. (Default.)

YESSPELL 'text'

Uses text for TRUE Boolean values. The default is recorded in the YESSPELL option.

NOSPELL 'text'

Uses text for FALSE Boolean values. Overrides the setting of the NOSPELL option.

ZSPELL 'text'

Uses text instead of zero numeric values. Overrides the setting of the ZSPELL option.

NOZSPELL

Spells zero numeric values as specified by the ZSPELL option. (Default.)

OVER textexp

Overlines the value with the value of a character expression (textexp). When textexp is a literal value, it must be enclosed in single quotes. Useful literal values include: '-' to overline value or column, '=' to double overline value or column, and '' to indicate that a value or column is does not have an overline.

To overline only when a condition is met, for textexp use:

IF boolean-expression THEN '-' ELSE ''

UNDER textexp

Underlines the value with the value of a character expression (textexp). When textexp is a literal value, it must be enclosed in single quotes. Useful literal values include: '-' to underline value or column, '=' to double underline value or column, and '' to indicate that a value or column is not underlined.

To underline only when a condition is met, for textexp use: IF boolean-expression THEN '-' ELSE ''

VALONLY

Used with the UNDER and OVER attributes, underline or overline the value only.

NOVALONLY

Used with the UNDER and OVER attributes, underlines or overlines the entire width of the column. (Default.)

expression . . .

The data to be shown in the report. The way the data looks depends on its data type and the attributes you specify.

Note:

The REPORT command is not equipped to deal with NTEXT values. Do not include them in any part of a report.

You can specify multiple expressions and these expressions do not have to have the same dimensions:

  • When you have several data expressions in your REPORT statement, you can specify different format attributes before each. When you want attributes to apply to two or more data expressions, enclose the expressions in angle brackets (< >).

    attributes <expression1expression2>

  • Attributes outside the brackets apply to all the expressions within the brackets. However, you can also specify attributes for only one expression (even an attribute that contradicts one that applies to the group) within the brackets by including them immediately before the expression.

    attributes0 <attributes1 expression1expression2>

    In this case, attributes0 applies to both expression1 and expression2; while attributes1 only applies to expression1.

Tip:

To create running totals, use the RUNTOTAL function.

Usage Notes

Report Options

Several options effect reports created using the OLAP DML. These options are listed in "Report Options".

Default Layout

When you do not specify any of the layout phrases (GROUP, DOWN, or ACROSS), REPORT tries to format its output compactly (typically, a two-dimensional report of the data with one dimension down the side and the others across the top, much like a spreadsheet). Any additional dimensions of the data form "slices" or separate two-dimensional segments, like a series of spreadsheets. By default, REPORT uses the following rules to determine the layout:

  • The fastest-varying dimension in an expression (the one that appears first in the definition of that expression) goes across, the next fastest goes down, and any remaining dimensions become GROUP slices.

  • The order of dimensions in a list of two or more expressions is a simple combination of the dimensions that appear in the definitions of the component expressions. The original order is preserved as far as possible, subject to the rule that repeated mentions of the same dimension are dropped. For example, the dimensions of the combined variables price and industry.sales, where price has the dimensions <month product> and industry.sales has the dimensions <quarter product region>, are <month product quarter region>.

When you produce a report of data for a variable dimensioned by a composite, REPORT automatically breaks out the data by the base dimensions of the composite that is used in the definition of the variable. When a particular combination of base dimension values does not exist in the composite, the report shows NA for the corresponding data cell. See Example 10-104.

Default Values for the Width Attribute

When you omit the WIDTH attribute for an ACROSS phrase, the default width is the value of the COLWIDTH option (default is 10).

When you omit the WIDTH attribute for a DOWN phrase or when you specify a simple dimension in the DOWN phrase, the default width is the value of the LCOLWIDTH option (default is 14).

When you omit the WIDTH attribute for a DOWN phrase that specifies a conjoint dimension or a composite, the default label width is the width of the COLWIDTH option and there is a separate column for each base dimension. You can provide a different width for each base dimension column by using the KEY function. You can produce a label column for each base dimension with the KEY function and use a separate WIDTH attribute for each column. For example, assume that proddist is a composite with the base dimensions product and district. In this case, you can use a statement similar to the following one.

REPORT DOWN < W 8 KEY(proddist, product) -
   W 12 KEY(proddist, district) > . . .

When you use the default line width of 80 characters (determined by the LSIZE option) and the default column width settings (with a single label column of 14 characters) a line of output can accommodate the labels column and six data columns.

The combined width of all the columns of a report cannot be greater than 4,000 characters.

When a numeric value is too large to fit into a data column, REPORT rounds it off to the nearest million with the symbol M at the right side of the cell. When a value is still too large, REPORT replaces the value with a series of asterisks.

Formatting DAY, WEEK, MONTH, QUARTER, and YEAR Dimension Values

When you use a dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR as the dimension in an ACROSS, DOWN, or GROUP phrase, you can use the CONVERT function to override the dimension's VNF (or the default VNF) and provide your own format for the dimension value names. To override the VNF, use the CONVERT function with a vnf argument instead of the dimension argument to the ACROSS, DOWN, or GROUP keyword. For example, in a report of units data, you can format the labels for the month dimension by using the following statement.

REPORT HEADING 'Month' DOWN -
   CONVERT(month TEXT '<mtextl> <yyyy>') units

Specifying Extra Dimensions

The REPORT command uses whatever dimensions you specify in laying out the report, regardless of whether the expressions to be shown are dimensioned by these dimensions. When an expression is not dimensioned by one or more of the dimensions specified, the values of that expression are repeated for each value of the extra dimension. This fact is sometimes useful for comparisons. See Example 10-103.

Examples

Example 10-100 Creating a Default Report

This example shows how to look at product prices for the first three months of 1996. You can use REPORT in its simplest form, without changing the default layout

LIMIT month TO 'Jan96' TO 'Mar96'
REPORT price

These statements produce the following output.

                --------------PRICE-------------
                --------------MONTH-------------
PRODUCT           Jan96       Feb96      Mar96
--------------- ---------- ---------- ----------
Tents               165.50     165.75     165.13
Canoes              200.25     200.09     200.05
Racquets             55.02      55.03      55.00
Sportswear           50.03      50.02      50.00
Footwear             38.01      38.01      38.01

Example 10-101 Including Column Totals

This example looks at unit sales for three districts for the first half of 1996, with district across the report and a subtotal for each column. (By default, months would be arranged across the report, because month is the fastest-varying dimension of units.) To make the report more compact, specify a smaller column width of 8 characters.

LIMIT month TO 'Jan96' TO 'Jun96'
LIMIT district TO 'Boston' 'Chicago' 'Dallas'
REPORT SUBTOTALS W 8 DOWN month -
   ACROSS district: W 8 units

These statements produce the following output.

PRODUCT: TENTS
         ----------UNITS-----------
         ---------DISTRICT---------
MONTH    Boston   Chicago  Dallas
-------- -------- -------- --------
Jan96         307      189      308
Feb96         209      190      324
Mar96         277      257      436
Apr96         372      318      560
May96         525      433      744
Jun96         576      466      838
-------- -------- -------- --------
TOTAL       2,266    1,853    3,210
   ...

REPORT produces a similar slice for each product.

Example 10-102 Comparing Two Variables

This example compares actual sportswear sales with the projected sales plan, looking only at whole-dollar figures. It reports the actual and planned values side-by-side for May and June, 1996, and provides a grand total of sales and planned sales for all districts.

LIMIT product TO 'Sportswear'
LIMIT month TO 'May96' 'Jun96'
LIMIT district TO ALL
REPORT GRANDTOTALS W 12 DOWN district ACROSS month: -
   DECIMAL 0 <sales sales.plan>

These statements produce the following output.

PRODUCT: SPORTSWEAR
             -------------------MONTH-------------------
             --------May96-------- --------Jun96--------
DISTRICT       SALES    SALES.PLAN   SALES    SALES.PLAN
------------ ---------- ---------- ---------- ----------
Boston           72,617     69,623     79,630     73,569
Atlanta         161,537    148,823    177,967    157,939
Chicago         101,873     94,545    112,793     97,427
Dallas          170,939    165,449    175,066    164,192
Denver           89,971     91,880     97,237     94,729
Seattle          57,713     55,905     60,323     56,808
             ---------- ---------- ---------- ----------
                654,651    626,224    703,017    644,664
             ========== ========== ========== ==========

Example 10-103 Repeating Price Data

This example compares sales across three districts, and it includes the unit price beside each sales figure for close comparison within each district. The REPORT statement specifies two expressions, sales and price. Because sales has three dimensions, month, product, and district, the report shows these three dimensions. However, price is not dimensioned by district. Therefore, the report repeats the values of price for each district. The report for January 1995 shown.

LIMIT district TO FIRST 3
LIMIT product TO ALL
LIMIT month TO 'Jan95'
REPORT GROUP month W 10 DOWN product ACROSS district: -
   <W 9 sales W 6 price>

These statements produce the following output.

MONTH: Jan95
           -------------------DISTRICT------------------------
           -----Boston-----  ----Atlanta----- -----Chicago----
PRODUCT      SALES    PRICE   SALES    PRICE   SALES    PRICE 
---------- --------- ------  --------- ------ --------- ------
Tents      32,153.52 160.77  40,674.20 160.77 29,098.94 160.77
Canoes     66,013.92 190.24  49,462.88 190.24 45,277.56 190.24
Racquets   52,420.86  52.84  54,798.82  52.84 54,270.39  52.84
Sportswear 53,194.70  48.54 114,446.26  48.54 72,123.47  48.54
Footwear   91,406.82  36.10 100,540.28  36.10 90,287.70  36.10

Example 10-104 Reporting Data Dimensioned by Composites

In this example, d.sales is a variable whose dimension list includes the dimension month and the unnamed composite SPARSE<productdistrict>. The unnamed composite contains no values for the base dimension combinations for the Boston and Chicago districts and the Tents, Racquets, And Footwear products. When you use the default form of the REPORT command to produce a report of d.sales data, REPORT breaks out the report by month and by the base dimensions of the unnamed composite (product and district). For the combinations of base dimension values that do not exist in the composite, the report shows NA for the corresponding data cells.

LIMIT month TO 'Jan96' TO 'Mar96'
LIMIT district TO 'Boston' 'Chicago'
REPORT d.sales

These statements produce the following output.

DISTRICT: Boston
               ------------D.SALES-------------
               -------------MONTH--------------
PRODUCT          Jan96      Feb96      Mar96
-------------- ---------- ---------- ----------
Tents                  NA         NA         NA
Canoes             70,489     82,238     97,622
Racquets               NA         NA         NA
Sportswear         57,079     63,122     67,006
Footwear               NA         NA         NA
 
DISTRICT: Chicago
               ------------D.SALES-------------
               -------------MONTH--------------
PRODUCT          Jan96      Feb96      Mar96
-------------- ---------- ---------- ----------
Tents                  NA         NA         NA
Canoes             48,662     54,425     68,816
Racquets               NA         NA         NA
Sportswear         77,490     85,879     85,308
Footwear               NA         NA         NA

By specifying the composite in an ACROSS, DOWN, or GROUP phrase, you can override the default format of REPORT and break out the d.sales data by its composite. In this case, the report only includes the data cells for which the composite contains values.

REPORT DOWN SPARSE <product district> d.sales

This statement produces the following report.

                      ------------D.SALES-------------
                      -------------MONTH--------------
 PRODUCT    DISTRICT    Jan96      Feb96      Mar96
---------- ---------- ---------- ---------- ----------
Canoes     Boston         70,489     82,238     97,622
Sportswear Boston         57,079     63,122     67,006
Canoes     Chicago        48,662     54,425     68,816
Sportswear Chicago        77,490     85,879     85,308

10.46 RESYNC

When an analytic workspace is attached in multiwriter mode, the RESYNC command drops private changes for the specified read-only objects and retrieves the data from the latest visible generations.

RESYNC resynthesized read-only objects. Use ACQUIRE to resynchronize acquired objects

Syntax

RESYNC objects

Parameters

objects

A list of one or more variables, relations, valuesets, or dimension names, separated by commas, that you want to resynchronize. Oracle OLAP ignores any acquired objects in this list.

Use Name as a value in objects to specify that you want to resynchronize the newest objects defined by other users.

Usage Notes

Keeping Logical Relationship of Objects

When using RESYNC keep in mind the logical relationship of different objects to avoid losing the logical consistency of the data by promoting some objects, but not others to a new generation.

Resynchronizing Objects that Share a Composite Dimension

Objects that share a composite dimension can be resynchronized separately when all such objects that are not being resynchronized are either unchanged or acquired.

Examples

Example 10-105 Resynchronizing Objects

In this example, user A is periodically updating actuals, while user R needs to periodically check the latest view of the data. They could execute the following OLAP DML statements.

User A could execute the following OLAP DML statements.

AW ATTACH myworkspace MULTI
ACQUIRE actuals
...make modifications
UPDATE MULTI actuals
COMMIT
...make modification
UPDATE MULTI actuals
COMMIT

At the same time, user R could execute the following OLAP DML statements.

AW ATTACH myworkspace MULTI
...
RESYNC actuals
...
RESYNC actuals
...
RESYNC actuals
...

10.47 RETURN

Within an OLAP DML program, the RETURN command terminates execution of a program before its last line. You can optionally specify a value that the program returns when the program is called as a function. The value should have the same data type or dimension that you specified when you defined the program.

Syntax

RETURN [expression]

Parameters

expression

The expression to be returned to the calling program when the called program terminates.

Usage Notes

Return Value Dimensionality

The value returned by a program is a single value, without any dimensions. However, within the context of the statement that calls a user-defined function, the function expression has the dimensions of its arguments. In this case, the program is called once for every combination of the dimension values of the function expression.

Return Value Data Type

When you specify a data type when you define a program, the return value has that data type. When you specify a dimension when you define a program, the return value is a single value in that dimension. When the expression in a RETURN statement does not match the declared data type or dimension, Oracle OLAP converts it to the declared data type.

When you do not specify a data type or dimension in the definition of a program, its return value is treated as worksheet data and Oracle OLAP converts any return value to the data type that is required by the calling context which may lead to unexpected results.

Dimension Location

When the program returns values of a dimension, the dimension must be declared in the same analytic workspace as the program. The program is in the output of the LISTBY program, and OBJ(ISBY) is TRUE for the dimension.

No Return Value

When a program has been invoked as a function, but it does not provide a return value, the value that is returned to the calling program is NA.

Examples

Example 10-106 Terminating a Program Early

In this example, suppose you want a report program that produces a report only when a variable called newfigures is present in the current analytic workspace. In your program, you can use an IF statement to check whether newfigures exists and a RETURN to stop execution when it does not.

DEFINE sales.report PROGRAM
PROGRAM
IF NOT EXISTS('newfigures')
   THEN DO
          SHOW 'The new data is not yet available.'
          RETURN
        DOEND
PUSH month
TRAP ON cleanup
LIMIT month TO LAST 3
REPORT ACROSS month: newfigures
 
cleanup:
POP month
END

Now when you run the program without newfigures in the analytic workspace, the program produces a message and the RETURN statement terminates execution of the program at that point.

Example 10-107 Returning a Value

The following program derives next year's budget figures from the actual variable. It is a temporary calculation. You could call this program in a REPORT statement, thus calculating and reporting the budget figures without storing them in an analytic workspace.

DEFINE budget.growth PROGRAM DECIMAL
PROGRAM
VARIABLE growth DECIMAL
VARIABLE factor DECIMAL
growth = TOTAL(actual(year 'Yr97') year) - TOTAL(actual(year -
   'Yr96') year)
factor = ( 1 + growth ) / TOTAL(actual(year 'Yr96') year)
RETURN TOTAL(actual(year 'Yr97') year) * (factor * factor/2)
END

10.48 REVERT

The REVERT command drops all changes made to the specified objects since they were last updated, resynchronized (using a RESYNC statement), acquired using ACQUIRE with the RESYNC phrase, or since the analytic workspace was attached.

Syntax

REVERT objects

Parameters

objects

A list of the names, separated by commas, of acquired variables, valuesets, relations, or dimensions in an analytic workspace attached in multiwriter mode or a list of variables, valuesets, relations, or dimensions in an analytic workspace attached in read-only mode.

Usage Notes

Reverting a Dimension After Adding Dimension Values

Reverting a dimension after adding dimension values is not recommended because it can result in suboptimal space allocation for variables dimensioned by that dimension.

Examples

Example 10-108 Using REVERT to Undo Modifications

Assume that you have a variable named budget in an analytic workspace named myworkspace. Assume, also, that you must modify budget in several steps but do not want to update the analytic workspace data until all steps are completed. For each step, you want to run several models to find the one that produces desired results. To perform this task, take the following steps:

  1. Attach the analytic workspace in multiwriter mode.

  2. Acquire budget.

  3. For each step:

    1. Run the appropriate models, performing revert operations between them until you finds the desired model

    2. Update budget.

  4. Commit and release budget.

The following code accomplishes these tasks.

AW ATTACH myworkspace MULTI
ACQUIRE RESYNC budget
...try model 1a --> not acceptable
REVERT budget
...try model 1b --> ok. Done with Step 1
UPDATE MULTI budget
...try model 2a --> not acceptable
REVERT budget
...try model 2b --> not acceptable
REVERT budget
...try model 2c --> ok. Done with Step 2
UPDATE MULTI budget
...try model 3a --> ok. Done with Step 3. Done with all steps.
UPDATE MULTI budget
COMMIT
RELEASE budget
AW DETACH myworkspace

10.49 ROW command

The ROW command produces a single line of data in cells, one after another in a single row. A series of ROW commands that produce corresponding cells are often used to build up columns of data. For this reason, we normally speak of the ROW command as producing a line of columns. Output from the ROW command is sent to the current outfile.

The ROW command is typically used with other commands, functions, and options that you can think of collectively as report-writing statements

The ROW command itself consists of a series of column descriptions that specify the data to be produced and, optionally, the output format of the data.

In addition, ROW has a versatile capability for doing row and column arithmetic. It can perform calculations and include the calculation results in the output. It can use any kind of calculated expression in the column descriptions; and it can take advantage of row and column totaling functions (see Table 10-6).

ROW is primarily used in report programs to produce the lines of the report. The maximum width of any row in a report is 4,000 characters.

Tip:

When you know ahead of time that you do not need the subtotaling capability of the ROW command, using a HEADING statement instead of ROW to produce the lines of your report can provide a time savings, because, in this case, Oracle OLAP does not keep track of subtotals.

See Also:

ROW function

Syntax

ROW [attributes] [ACROSS dimension [limit-clause]:] {exp1|SKIP } -      [[attributes] [ACROSS dimension [limit-clause]:] {expn|SKIP }]

Parameters

ROW with no arguments produces a blank line.

attributes

One or more attributes for a column. Attributes are format specifications that determine how the data value is formatted within the column. There is no limit to the number of attributes that you can use to describe a column format. (See the SKIP parameter for an explanation of each of the available attributes.) The default for some format attributes is determined by the current setting of Oracle OLAP options (see Table 10-7 for a list of these options).

ACROSS

An ACROSS phrase lets you include multiple values of a dimensioned expression in a single row by looping over one dimension (or composite) of the expression. Typically, ROW shows only the value that corresponds to the first dimension value within the current limits. With an ACROSS phrase, ROW produces one data column for each dimension value currently in the status.

You can apply a single ACROSS phrase to multiple data expressions, or you can use separate ACROSS phrases for different data expressions. See "Multiple Expressions" and "Separate ACROSS Phrases".

dimension

The name of a dimension or composite over which the statement loops.

When you show data for a variable dimensioned by a composite and you do not include an ACROSS phrase, ROW shows output for all data cells that correspond to the base dimension values of the composite. When a particular combination of base dimension values does not exist in the composite, ROW shows NA for the corresponding data cell. Likewise, when you specify one composite's base dimension in an ACROSS phrase, ROW shows NA for a data cell for which the composite contains no value. However, when you specify a composite in the ACROSS phrase, ROW shows output only for data cells for which combinations of base dimension values exist in the composite which provides a more concise report that better reflects your data.

When the dimension specified in an ACROSS phrase has null status, ROW does not produce any data columns for that ACROSS phrase.

limit-clause

When you specify a dimension in the ACROSS phrase, a clause that enables you to temporarily change the status of that dimension during the execution of the ROW statement.

The syntax of limit-clause is the same syntax as any of the limit-clause arguments in the various forms of the LIMIT command (that is, the syntax of the LIMIT command after the limit-type argument such as "TO"). For the syntax of these arguments, see LIMIT (using values) command, LIMIT using LEVELREL command, LIMIT (using parent relation), LIMIT (using related dimension) command, LIMIT NOCONVERT command, and LIMIT command (using POSLIST).

The following example temporarily limits month to the last six values, no matter what the current status of month is.

      ACROSS month LAST 6: units

When the limits you specify result in empty status for the dimension, an error occurs. However, when you include the phrase IFNONE label, the error is suppressed and execution of your program branches to the specified label where you can handle the error.

Note:

When you specify a composite in the ACROSS phrase, you cannot include a limit-clause argument. You must limit the base dimensions of a composite to the desired values using a LIMIT command before you execute a ROW statement

SKIP

Used instead of an expression to indicate that the column is to be left blank.

Table 10-5 Column Attributes for ROW

Attribute Meaning

WIDTH n

(W n)

Makes the column n spaces wide. The default width for the first column is the value of the LCOLWIDTH option. For other columns, it is the value of the COLWIDTH option. The maximum width is 4,000 characters. Columns with a width of 0 are suppressed.

SPACE n

(SP n)

Precedes the column with n spaces. The default for the first column is 0; for other columns, 1.

INDENT n

Indents the value n spaces within its column. The default is 0.

LEFT

(L)

Left-justifies the value within its column. (The default for TEXT data.)

RIGHT

(R)

Right-justifies the value within its column. (The default for numeric and Boolean data.)

CENTER

(C)

Centers the value within its column.

LSET 'text'

Adds text to the left of the value. When used with an expression that contains NA values, Oracle OLAP does not include the text you specify at the left of any NA values.

NOLSET

Does not add anything to the left of the value.

RSET 'text'

Adds text to the right of the value. When used with an expression that contains NA values, Oracle OLAP does not include the text you specify at the right of any NA values

NORSET

Does not add anything to the right of the value.

FILL 'char'

Puts char into unused positions in the column. The default fill character is a space.

DECIMAL n

(D n)

Shows n decimal places. Decimal places are separated by the character currently specified by the DECIMALCHAR option. The default number of decimal places is controlled by the DECIMALS option.

NODECIMAL

Shows the number of decimal places indicated by the DECIMALS option.

COMMA

Marks thousands and millions with commas or the character currently recorded in the THOUSANDSCHAR option. The default is controlled by the COMMAS option.

NOCOMMA

Does not mark thousands and millions.

PAREN

Uses parentheses to indicate negative numbers. The default is controlled by the PARENS option.

NOPAREN

Uses the minus sign to indicate negative numbers. The default is controlled by the PARENS option.

LEADINGZERO

Puts a leading zero before decimal numbers between -1 and 1.

NOLEADINGZERO

Suppresses leading zeros before decimal numbers between -1 and 1. (Note that when you set the DECIMAL attribute to 0 and you use the NOLEADINGZERO keyword, Oracle OLAP does not show any decimal values between -1 and 1 that are rounded to 0.)

CNLEADINGZERO

Puts a leading zero before decimal numbers between -1 and 1 when it does not cut off any significant digits.

MNOTATION

Always uses M-notation (divides values by one million and appends M).

CMNOTATION

Conditionally uses M-notation, when needed to make a value fit in a column.

NOMNOTATION

Does not use M-notation (uses asterisks for oversize values).

MDECIMAL n

Shows n decimal places in numbers formatted with M-notation; n can be any number from 0 to 16, or 255.

ENOTATION

Always uses scientific notation, also called exponential notation or E-notation (appends E, and includes a sign before the exponent, for example, .230E+2 or .230E-2).

CENOTATION

Conditionally uses E-notation, when needed to make a value fit in a column.

NOENOTATION

Does not use E-notation (defaults to conditional M-notation).

EDECIMAL n

Shows n decimal places in numbers formatted with E-notation; n can be any number from 0 to 16, or 255.

NASPELL 'text'

Uses text instead of NA values. The default is controlled by the NASPELL option.

NONASPELL

Spells NA values as indicated by the NASPELL option.

ZSPELL 'text'

Uses text instead of zero numeric values. The default is controlled by the ZSPELL option.

NOZSPELL

Spells zero values as indicated by the ZSPELL option.

YESSPELL 'text'

Text used for TRUE Boolean values. The default is recorded in the YESSPELL option.

NOSPELL 'text'

Text used for FALSE Boolean values. The default is recorded in the NOSPELL option.

TRUNCATE

(TRUNC)

Truncates a character value to the column width when it does not fit in the column.

NOTRUNCATE

(NOTRUNC)

Creates additional lines when the character value does not fit in the column.

FOLDUP

For a multiline character value, places all but the last line above the rest of the row, and the last line on the row with the other values; also strips any leading or trailing spaces.

FOLDDOWN

For a multiline character value, places the first line on the row with the other values, and places additional lines below the rest of the row; also strips any leading or trailing spaces.

VALONLY

Underlines or overlines the value only. (Used with UNDER and OVER.)

NOVALONLY

Underlines or overlines the entire width of the column. (Used with UNDER and OVER.)

UNDER textexp

Underlines the value or column with the value of a character expression (textexp). When textexp is a literal value, it must be enclosed in single quotes. Useful literal values include: '-' to underline value or column, '=' to double underline value or column, and '' to indicate that a value or column is not underlined.

To underline only when a condition is met, for textexp use

IF boolean-expression THEN '-' ELSE ''

OVER textexp

Overlines the value or column with the value of a character expression (textexp). When textexp is a literal value, it must be enclosed in single quotes. Useful literal values include: '-' to overline value or column, '=' to double overline value or column, and '' to indicate that a value or column is does not have an overline

To overline only when a condition is met, for textexp use

IF boolean-expression THEN '-' ELSE ''

Use the functions that are listed in the following table to perform calculations on the values generated so far in a report.

Table 10-6 Row and Column Arithmetic

Function Data Type Value Returned

COLVAL(n)

DECIMAL

Value in the nth column of the current row. When n > 0, an absolute column number (from the left margin, moving to the right). When n < 0, a relative column number (from the current column, moving left).

 

RUNTOTAL(n)

where:

n = 1,2, ...32

DECIMAL

Total of all numbers generated in the current column since the last SUBTOTAL or ZEROTOTAL for n. Does not reset total for n to 0.

SUBTOTAL(n)

where:

n = 1,2, ...32

DECIMAL

Total of all numbers generated in the current column since the last SUBTOTAL or ZEROTOTAL for n. Resets total for n to 0.

 

The options that are listed in the following table affect the default format for a ROW command.

Table 10-7 Report-Related Options

Option Meaning

COLWIDTH

Column width for all but the first column when the WIDTH attribute is not used. The default is 10.

COMMAS

Specifies whether a thousands group separator is used when neither the COMMA attribute nor the NOCOMMA attribute is used. The default is YES (uses a separator).

DECIMALS

Number of decimal places when the DECIMAL attribute is not used. The default is 2.

LCOLWIDTH

Column width for the first column when the WIDTH attribute is not used. The default is 14.

LSIZE

Defines the line size within which the STDHDR program centers the standard header. The default is 80 characters.

NASPELL

Text used for NA values when the NASPELL attribute is not used. The default text is NA.

NLS_LANGUAGE

Specifies the text used for TRUE and FALSE Boolean values. These values are reflected in the YESSPELL and NOSPELL options.

NLS_TERRITORY

Specifies the character used for the decimal marker and the thousands group separator. These values are reflected in the DECIMALCHAR and THOUSANDSCHAR options.

PARENS

Parentheses usage for negative numbers when neither the PAREN attribute nor the NOPAREN attribute is used. The default is NO (does not use parentheses; uses a minus sign).

ZEROROW

Controls generation or suppression of rows in which all numeric values are zero. The default is NO (generates zero rows).

ZSPELL

Text used for zero values when the ZSPELL attribute is not used. The default text is OFF, which shows a zero (0). 

Use the statements that are listed in the following table with the ROW command.

Table 10-8 OLAP DML Statements That Are Compatible with the ROW Command

Command Action

BLANK n

Produces n blank lines. The default is one line.

HEADING column-

description(s)

Produces titles and column headings for a report. Numeric values in headings are not added to column totals.

PAGE

Forces a page break in output when PAGING is set to YES.

ZEROTOTAL

Resets all 32 totals to 0 for all columns.

ZEROTOTAL ALL col(s)

Resets all 32 totals to 0 for the specified columns, or for all columns when there are no column arguments.

ZEROTOTAL n col(s)

Resets the indicated total (n) to 0 for the specified columns, or for all columns when there are no column arguments. 

Usage Notes

Report-Writing Commands

The ROW command and its associated options and commands are referred to collectively as report-writing statements. Table 10-6 lists functions you can use for performing row and column arithmetic in reports. Table 10-7 lists report-related options that determine the default format for ROW output. Table 10-8 lists additional statements that are used in combination with ROW to create reports.You can use the PAGING option and associated paging-related options to produce your report program in a page-oriented format.

Labels for Composites and Conjoint Dimensions

When you produce a report of data that has a composite or a conjoint dimension in its dimension list, you can produce a label column for each base dimension by using the KEY function. You can also provide a separate WIDTH attribute for each label column. For example, when proddist is a composite with the base dimensions product and district, you can use statements similar to the following ones.

FOR proddist
   ROW W 12 KEY(proddist district) W 8 KEY(proddist product) ...

Multiple Expressions

When you want the same format attribute or ACROSS phrase to apply to multiple data expressions, you can enclose the expressions in angle brackets (< >) and place the common attributes or ACROSS phrase immediately before the bracketed expressions.

attributes <expression1expression2, ...> 

or

ACROSS dimension: <expression1expression2, ...>

When you have attributes that apply to only one expression within the brackets, place the specific attributes immediately before the expression.

attributes1 <expression1attributes2 expression2>

When an attribute inside angle brackets (specific to a column) conflicts with an attribute outside the brackets (common to several columns), the specific attribute overrides the common attribute.

You can nest brackets to any depth, if you have an equal number of right and left brackets.

Separate ACROSS Phrases

For data generated with an ACROSS phrase, you can produce all the columns for one expression and then all the columns for additional expressions by using separate ACROSS phrases.

ACROSS dimexpression1, ACROSS dimexpression2

You also can nest ACROSS phrases to show data columns for two or more dimensions of an expression across a row.

ACROSS dim1: ACROSS dim2expression

Row and Column Arithmetic

See Table 10-6 for a list of the functions available for row and column arithmetic. You can use these functions to perform calculations on the values already generated in a report. Oracle OLAP maintains 32 running totals for each column, so you can include up to 32 levels of subtotals in a report. Note that when a numeric value is too large to fit into a data cell, ROW rounds it off to the nearest million with the symbol M at the right side of the cell. When a value is still too large, ROW replaces the value with asterisks.

Examples

Example 10-109 Labeling Data Values

In this example, ROW produces a line of output that contains a value of sales, along with the corresponding dimension values for district, month, and product that identify it.

ROW W 8 district month product sales

The preceding statement produces the following row of output.

Boston        Jan95      Tents  32,153.52

Example 10-110 Reporting Two Variables

The line of output produced by this ROW statement contains the current dimension value of district, followed by the values of sales and sales.plan for Sportswear for each of the first two months of 1996. 

LIMIT month TO 'Jan96' 'Feb96'
LIMIT product TO 'Sportswear'
ROW W 8 district ACROSS month: <sales sales.plan>

These statements produce the following row of output.

Boston    57,079.10  61,434.20  63,121.50  64,006.91

Example 10-111 Formatting and Labeling the Output

In this ROW statement, you want to see the actual and planned sales of tents for June 1996. You want to limit the status of month only for this one ROW statement, so you include the value Jun96 in the ACROSS phrase. You format the values as whole dollar amounts, and you also add a dollar sign to the values, along with individual labels that identify the actual and planned figures.

LIMIT product TO 'Tents'
ROW WIDTH 15 name.product ACROSS month 'Jun96': -
   DECIMAL 0 LSET '$' W 18 -
   <RSET ' (actual)' sales -
   RSET ' (plan)' sales.plan>

These statements produce the following row of output.

3-Person Tents    $95,121 (actual)     $80,138 (plan)

Example 10-112 Reporting on a Variable Dimensioned by a Composite

In this example, D.SALES is a variable whose dimension list includes the dimension month and the unnamed composite SPARSE <product district>. By specifying the composite in an ACROSS phrase of a ROW statement, you can produce a report that includes only the data cells for which the composite contains values.

LIMIT product TO ALL
LIMIT district TO 'Atlanta'
LIMIT month TO 'Jan96'
ROW ACROSS SPARSE <product district>: d.sales

10.50 SET

The SET command, also called an assignment statement or the = command, assigns one or more values to a variable, option, relation, or dimension surrogate. When an object has one or more dimensions, the SET command loops over the values in status for each dimension of the target object and assigns a data value to the corresponding cell of the target object.

When the target is an object defined with a composite in its dimension list, Oracle OLAP automatically creates any missing target cells that are being assigned non-NA values. This step also adds to the composite all the dimension value combinations that correspond to those new cells. Thus, both the target object and the composite might be larger after an assignment. When you want to assign values only to cells that already exist in the target, use the ACROSS keyword.

Note:

You can use UNRAVEL with SET to assign values of an expression into the cells of a variable when the dimensions of the expression are different from the dimensions of the variable

Syntax

[SET] target-name [=] expression [ACROSS composite]

Parameters

SET

SET is optional. It is an older command form of this functionality, and is included for compatibility.

target-name

The name of the target object where the data is assigned and stored. For a list of analytic workspace objects that can be a target object, see Table 10-9.

=

The = (assignment or equal) operator assigns one or more values to a variable, option, or relation. See also "Assignment Operator".

expression

The source of the data values to be assigned to the object, see Table 10-9

ACROSS composite

When you are assigning data to a variable dimensioned by a composite the default behavior is to loop over all the values in status for each of the base dimensions of the object. Oracle OLAP automatically creates any missing target cells that are being assigned non-NA values, and it automatically adds the required dimension value combinations to the composite.

When you want to assign values only to existing cells of a variable defined with a composite, use the ACROSS keyword, which causes = to change the way it loops for those dimensions of the target that are part of the composite. Instead of looping over all possible combinations of the values in the status of those dimensions, = loops only over those combinations of the values in the status that already exist in the composite.

The ACROSS keyword is intended for specifying a composite. However, when you specify a base dimension of the composite instead, be aware that the assignment statement could add many values to your composite.

Usage Notes

Triggering Program Execution When an Assignment Statement Executes

Using the TRIGGER command, you can make a SET statement an event that automatically executes an OLAP DML program. See "Trigger Programs" for more information

Dimensionality and Performance

When the target has multiple dimensions, the = statement loops over the dimension values in the order in which they were added, regardless of their logical order as reflected by the default status. In a multidimensional case, the looping is over the compound dimension. The first dimension listed in the definition varies the fastest. When you are setting the target to the values of an expression, Oracle OLAP performs much more efficiently when the source expression has the same dimensions, in the same order, as the target.

Differently Dimensioned Variables in an Expression

When an assignment statement involves several differently-dimensioned objects, the calculation can appear complicated. The following list outlines the process followed by a complicated assignment statement. When the statement is A = B, where A is the object being set to the expression B, Oracle OLAP first determines the dimensions of A. Then it determines the status of those dimensions. For each combination of dimension values in the status of those dimensions:

  1. Oracle OLAP determines which single value of A (sometimes called a cell) is going to be set.

  2. For each component of the expression B (each variable, formula, function, qualified data reference, or literal), Oracle OLAP determines the single value that corresponds to the cell of A that is being set. When a component of the expression is not dimensioned or is a literal, Oracle OLAP simply uses its value. When a component of the expression has dimensions different from A, Oracle OLAP uses the first value in the status of these dimensions.

  3. Oracle OLAP performs the specified calculation on the single values obtained in Step 2 and stores the result in the cell of A chosen in Step 1.

Using Objects in Assignment Statements

The following table outlines the objects that you can use in assignment statements and indicates whether you can use them as a target or source expression:

Table 10-9 Using Objects in Assignment Statements

Object Target Source

Composite

No

Yes

Dimension

Only in models

Yes

Formula

Yes

Yes

Function (including OLAP DML program as function)

No

Yes

Relation

Yes

Yes

Surrogate

Yes

Yes

Valueset

No

Yes

Variable

Yes

Yes

Worksheet

Yes

Yes

Assigning Values to Variables

When you use an = (SET) statement to assign the value of a single-cell expression to a single cell, a single value is stored. However, when you use an = statement to assign the value of a single-cell expression to a target variable that has one or more dimensions, then the assignment loops over the values in status for each dimension of the target variable and assigns a data value to the corresponding cells of the variable.

When you assign a multiline value to a fixed-width text variable, then the variable is set to the first line only. To assign a multiline value to a fixed-width text variable, you use the JOINCHARS function to make the multiline value one line long. For example, suppose you have a non-fixed-width text variable called textvar. The statement

SHOW textvar

produces the following output, in which each line of the value in textvar is shown as a separate line.

This is a variable
that has a multiline
text value.

To assign this value to a variable called fixedtext with a fixed width of 60 bytes and show the value, you would use the following statements.

fixedtext = JOINCHARS(textvar)
SHOW fixedtext

These statements produce the following output, in which the value of textvar is shown as a single line.

This is a variable that has a multiline text value.

When the actual number of bytes in the textvar variable's value exceeds the width of the fixedtext variable, then the value of textvar is truncated when it is stored in fixedtext.

Assigning Values to Relations

You can assign values to a relation using a SET statement as illustrated in Example 10-114. When executing the assignment statement, a loop is performed over the values in status for each dimension of the target relation and assigns a data value to the corresponding cell of the target relation.

You can assign values to a relation with a text dimension by assigning one of the following:

  • A text value of the dimension.

  • An INTEGER that represents the position of the dimension value in the default status list of the dimension.

Assigning Values to Dimensions

The only time you use an = statement to assign a value to a dimension is when the result of a calculation in a model equation is numeric. In this situation, you can use the = operator to assign the results to a dimension value. However, equations (that is, expressions) in models differ in several ways from expressions used in other contexts. See "Rules for Equations in Models" for information on using the assignment statement within models. See the MAINTAIN command for information on how to add values to dimensions in all other cases.

Assigning Values to Dimension Surrogates

You assign values to a dimension surrogate with an = (SET) statement. For example, the following statements define the dimension surrogate storename, which is a TEXT type surrogate for the NUMBER type dimension store_id, assign a value to the fourth position of storename, and then report the value of the surrogate for the fourth value of store_id, which is 100.

DEFINE storename SURROGATE store_id TEXT
storename(storename 4) = 'Molly\'s Emporium'
REPORT W 25 storename(store_id 100)
 
STORENAME(STORE_ID 100)
-------------------------
Molly's Emporium

For example, when you define the INTEGER dimension surrogate intsurr for a NUMBER dimension numdim that has five values, then a report of intsurr produces the following.

INTSURR
-------
      1
      2
      3
      4
      5

Like a dimension, the values of a dimension surrogate must be unique. However, unlike a dimension, a dimension surrogate can have NA values, unless it is an INTEGER type. The same value can be a value of the dimension and of any of its surrogates.

Using QDRs with the Target of an Assignment Statement

You can use a QDR with the target of an = (SET) statement which lets you assign a value to specific cells in a variable or relation.

The following example assigns the value 10200 to the data cell of the sales variable that is specified in the qualified data reference. When the variable named sales does not already have a value in the cell associated with Boston, Tents, and Jan99, then the value is assigned to the cell and thus it is added to the variable. When a value already exists in the cell, the value 10200 overwrites the previous value.

sales(market 'Boston' product 'Tents' month 'Jan99')= 1020

Expressions Dimensioned Conjoint Dimensions

When an expression is dimensioned by a conjoint dimension, Oracle OLAP uses the dimension's relationship to its base dimension values to assign data to the correct cells. You can set the values of a variable dimensioned by a conjoint dimension to an expression dimensioned by one of its base dimensions. The converse is also true. See "Example 10-117".

Rules for Equations in Models

The equations in a model use an OLAP DML assignment statement to assign values to variables or dimension values. Equations in models differ in several ways from equations used in other contexts in Oracle OLAP:

  • In a model equation, you can use the name of a dimension value anywhere you would normally use the name of a variable. You can base calculations on a dimension value, and you can assign the results of a calculation to a dimension value. When an equation refers directly to one or more dimension values, it is called a dimension-based equation.

  • You cannot use ampersand substitution in model equations.

  • You can include a program as a component in a calculation only when it is used as a function.

  • Within a single dimension-based equation, all the dimension values must belong to the same dimension.

  • When you assign the results of a calculation to a dimension value, the results must be numeric.

  • Each dimension on which the model equations are based must be listed in a DIMENSION statement. When the model contains an INCLUDE statement, the appropriate DIMENSION statements must be inherited from the included model. When the model does not contain an INCLUDE statement, it must contain the appropriate DIMENSION statements. When you compile or run the model, Oracle OLAP searches through the dimensions listed in explicit or inherited DIMENSION statement to identify the dimension to which each dimension value belongs.

Dimension Status and Model Equations

When a model contains an assignment statement to assigns data to a dimension value, then the dimension is limited temporarily to that value, performs the calculation, and then restores the initial status of the dimension.

Formatting Conjoint Dimension Values

A special format is required when dimension-based equations refer to values of a conjoint dimension:

  • Enclose the entire dimension value specification in angle brackets and then enclose this entire specification in single quotes; do not enclose the individual values in single quotes.

  • Use the exact upper- and lowercase spellings for the base dimension values.

  • When the specification includes a text value with an embedded blank, you must separate the dimension values with commas.

For example, assume that item.org is a conjoint dimension with base dimensions item and org. In this case, you use the following format to refer to values of item.org.

'<Expenses, Direct Sales>'

Formatting Text Dimension Values

When dimension-based equations refer to text dimension values with embedded blanks or mixed upper- and lowercase letters, enclose the dimension value in single quotes. Use the exact upper- and lowercase spelling for the value.

For example, assume that a text dimension named lineitem contains a value with an embedded blank. In this case, you use the following format.

'Software Revenue'

Specifying DAY, WEEK, MONTH, QUARTER, YEAR Values for a Model Equation

When a model equation is based on a dimension of type DAY, WEEK, MONTH, QUARTER, or YEAR, you must use the dimension's VNF (value name format), rather than a date format, to specify the dimension's values. In addition, the VNF must format dimension values as follows:

  • The value must start with a letter.

  • The value can only contain letters, digits, underscores, and periods.

When the WEEK, MONTH, QUARTER, YEAR dimension of type does not have a VNF assigned to it, you can use the default VNF for the dimension. The entry for the VNF command lists the default VNF for each of these dimension types, and it explains how to assign a VNF to a dimension.

The default VNF for DAY dimensions is not acceptable because it specifies a digit as the first character of each dimension value. For a DAY dimension, specify the dimension name and enclose the value in parentheses and single quotes.

For example, for a DAY dimension named daydim, you can use the following format.

daydim('01jul97')

Formatting INTEGER Dimension Values

When dimension-based equations refer to values of an INTEGER dimension, enclose the dimension value in single quotes.

For example, for an INTEGER dimension named intdim, use the following format to refer to the first dimension value.

'1'

When the model is based on multiple dimensions, the model compiler might not be able to correctly identify the dimension to which a literal INTEGER value belongs. In this case, specify the name of the dimension and enclose the value in parentheses and single quotes as described in "Formatting Ambiguous Dimension Values".

Formatting Ambiguous Dimension Values

In some cases the model compiler might be unable to correctly identify the dimension to which a dimension value belongs. For instance, this can happen under the following circumstances:

  • Two or more dimensions have a dimension value with the same name.

  • A DAY dimension uses the default VNF (which starts with a digit).

  • An INTEGER value could be interpreted either as a position within a dimension or as a literal INTEGER value of a dimension.

In cases such as these, you can avoid ambiguity in model-based equations by following these rules:

  • Enclose the dimension value in single quotes.

  • Enclose the quoted value in parentheses.

  • Precede the parentheses with the name of the dimension.

For example, for an INTEGER dimension named intdim, use the following format to refer to the first dimension value.

intdim('1')

Examples

Example 10-113 Assigning Values to a Variable

For the first example, suppose you have defined two variables, units and price, that are both dimensioned by product. The following example calculates dollar sales (units times price) for each value in the product dimension. Using an assignment statement, it stores the result in the variable sales, which is also dimensioned by product.

sales = units*price

For another example, assume the choicedesc variable is dimensioned by choice. Before you enter data for the variable, the cells of the variable contain only NA values.

CHOICE           CHOICEDESC
-------------- --------------------
Report         NA
Graph          NA
Analyze        NA
Data           NA
Quit           NA

Suppose you initialize the choicedesc variable using the following statement.

choicedesc =  JOINCHARS ('Description for ' choice)

Now all of the choicedesc cells of the variable contain the appropriate values.

CHOICE             CHOICEDESC
-------------- -------------------------
Report         Description for Report
Graph          Description for Graph
Analyze        Description for Analyze
Data           Description for Data
Quit           Description for Quit

The next example shows an expression that is dimensioned by time, product, and district and is assigned to a new variable. The expression calculates a 2002 sales plan based on unit sales in 2001.

DEFINE units.plan INTEGER <month product district>
LIMIT month TO 'DEC02'
units.plan = LAG(units 12 month) * 1.15

Example 10-114 Assigning Values to a Relation

Assume that your analytic workspace contains the following definitions for a hierarchical dimension for Geography named geog and a relation named geog_parentrel that contains values that represent the child-parent relationships in the Geography hierarchy.

DEFINE geog DIMENSION TEXT
DEFINE geog_parentrel RELATION geog <geog>
 

You can use the following MAINTAIN ADD statements to populate the hierarchical dimension.

" Populate the geog dimension with values for all levels
MAINTAIN geog ADD 'North America' 'Europe' 'United States' 'Canada' 'France' 'Germany'
MAINTAIN geog ADD 'Massachusetts' 'California' 'Quebec' 'Ontario' 
MAINTAIN geog ADD 'Boston''Springfield' 'San Francisco''Los Angeles' 'Toronto' 'Ottawa' 
MAINTAIN geog ADD 'Montreal''Quebec City' 'Paris' 'Marseilles' 'Bonn' 'Berlin'
 

You can use the following assignments statements to populate geog_parentrel. Note that you must limit geog to the appropriate values before you assign values to geog_parentrel.

"  Limit geog (and therefore geog_parentrel) to countries and assign 
"   parent value (continent name) to those countries in geog_parentrel
LIMIT geog to 'United States' 'Canada'
geog_parentrel = 'North America'
LIMIT geog to ALL
LIMIT geog to 'France' 'Germany'
geog_parentrel = 'Europe'
 
"  Limit geog (and therefore geog_parentrel) to states or provinces and assign 
"   parent value (country name) to those states or provinces in geog_parentrel
LIMIT geog to ALL
LIMIT geog to 'Massachusetts' 'California'
geog_parentrel = 'United States'
LIMIT geog to ALL
LIMIT geog to 'Quebec' 'Ontario'
geog_OLAP DML Commands: A-G = 'Canada'
 
"  Limit geog (and therefore geog_parentrel) to cities and assign
"   parent value (state, province, or country) to those cities in geog_parentrel
LIMIT geog to ALL
LIMIT geog to 'Boston' 'Springfield' 
geog_parentrel = 'Massachusetts'
LIMIT geog to ALL
LIMIT geog to 'San Francisco' 'Los Angeles' 
geog_parentrel = 'California'
LIMIT geog to ALL
LIMIT geog to 'Montreal' 'Quebec City'
geog_parentrel = 'Quebec'
LIMIT geog to ALL
LIMIT geog to 'Toronto' 'Ottawa' 
geog_parentrel = 'Ontario'
LIMIT geog to ALL
LIMIT geog to 'Paris' 'Marseilles' 
geog_parentrel = 'France'
LIMIT geog to ALL
LIMIT geog to 'Bonn' 'Berlin'
geog_parentrel = 'Germany'
LIMIT geog to ALL
 

A report of geog_parentrel shows the values have been assigned.

COLWIDTH = 20
REPORT geog_parentrel
REPORT geog_parentrel
 
GEOG                GEOG_PARENTREL
---------------- --------------------
North America    NA
Europe           NA
United States    North America
Canada           North America
France           Europe
Germany          Europe
Massachusetts    United States
California       United States
Quebec           Canada
Ontario          Canada
Boston           Massachusetts
Springfield      Massachusetts
San Francisco    California
Los Angeles      California
Toronto          Ontario
Ottawa           Ontario
Montreal         Quebec
Quebec City      Quebec
Paris            France
Marseilles       France
Bonn             Germany
Berlin           Germany

Example 10-115 Using a Qualified Data Reference

This example uses an assignment statement with a qualified data reference to assign values to the variable budget. The values assigned to one budget line item (Net.Income) are calculated as the difference between two other line items (Opr.Income and Taxes), so you have to use a qualified data reference to obtain the correct data values.

budget(line Net.Income)= budget(line Opr.Income) - budget(line Taxes)

Example 10-116 Assigning Values to Variables with Composites

To have data assigned from sales only into existing data cells of sparse_sales, whose associated dimension values are in status, use the following statement.

sparse_sales = sales ACROSS SPARSE<product market>

The ACROSS keyword is particularly helpful when the source expression is a single value. When there are no limits on the dimensions of sparse_sales, then an assignment statement like the following creates cells for every combination of dimension values because there are no cases where the source expression is NA.

sparse_sales = 0

This defeats the purpose of a dimensioning a variable with a composite.

In contrast, the following statement sets only existing cells of sparse_sales to 0 (zero).

sparse_sales = 0 ACROSS SPARSE<product market>

Example 10-117 Compacting Your Data

Suppose you only sell some of your products in each district. You currently have a variable sales that has data for certain combinations of districts and products and NA values for the rest. You can create a dense array of sales data by defining a composite or a conjoint dimension and using it as a dimension of a new variable. Use an assignment statement to assign the data directly to the new variable. When the values of the composite or conjoint dimension include all the combinations with data, you can then delete the original variable and save space in the analytic workspace.

DEFINE proddist DIMENSION <product district>
MAINTAIN proddist ADD <'Tents' 'Boston'> <'Canoes' 'Seattle'> -
   <'Sportswear' 'Atlanta'>
DEFINE sales.dense DECIMAL <month proddist>
sales.dense = sales
LIMIT month TO FIRST 4

Issuing a REPORT sales.dense statement produces the following output.

                    ----------------SALES.DENSE----------------
-----PRODDIST------ -------------------MONTH-------------------
PRODUCT    DISTRICT   Jan95      Feb95      Mar95      Apr95
-------- ---------- ---------- ---------- ---------- ----------
Tents      Boston    32,153.52  32,536.30  43,062.75  57,608.39
Canoes     Seattle   64,111.50  71,899.23  83,943.86  14,383.90
Sportswear Atlanta  114,446.26 123,164.92 138,601.64 141,365.66

An alternative method would be to use a composite instead of a conjoint dimension. In this case, you could use the following statements.

DEFINE sales.compact DECIMAL <month SPARSE <product district>>
sales.compact = sales

Oracle OLAP automatically creates the unnamed composite when you define sales.compact, and it automatically adds dimension value combinations to the composite when you use an assignment statement. Oracle OLAP creates dimension value combinations only for the non-NA values of sales.

10.51 SET1

The SET1 command assigns a single value to a variable, option, relation, or dimension surrogate. When an object has one or more dimensions, the SET1 command assigns the value to the object cell that is in current status.

Because the SET1 command does not loop through a dimensioned object, you can use it in Assign trigger programs to assign a value to an object.

Syntax

SET1 target-name expression 

Parameters

target-name

The name of the target object where the data is assigned and stored. For a list of analytic workspace objects that can be a target object, see Table 10-9.

expression

The source of the data values to be assigned to the object, see Table 10-9

Examples

For an example of using SET1, see Example 10-164.

10.52 SET_INCLUDED_MODEL

The SET_INCLUDED_MODEL program adds an INCLUDE model statement to a previously-defined cube dimension's model, or deletes an INCLUDE model statement from a previously-defined cube dimension's model. The changes made when this program executes are not transactional; an automatic COMMIT is executed as part of the program.

Syntax

CALL SET_INCLUDED_MODEL(logical_dim, model_name, custom_model)

Parameters

CALL

Because SET_INCLUDED_MODEL is an OLAP DML program with arguments, you invoke it using the OLAP DML CALL statement.

logical_dim

A text expression that is the Oracle data dictionary name of the cube dimension being modified.

model_name

A text expression that is the name of the logical model that is associated with the cube dimension.

custom_model

A text expression that is the OLAP DML-created model for which you want to add an INCLUDE statement.

To remove an INCLUDE statement, specify NA.

Examples

Example 10-118 Creating Static and Dynamic Models for an OLAP Cube

Assume that you have created an OLAP cube dimension named my_time that dimensions an OLAP cube named my_cube. Within my_cube there are two measures: sales and moving_sales. Now you want to create static and dynamic models for my_cube.

  1. To create a static model, execute the following PL/SQL statement that executes a user-written OLAP DML program named setup_pre_model.

    exec dbms_aw.execute('call my_util_aw!setup_pre_model');
    

    As you can see from the following definition of the setup_pre_model program, the model is actually defined using the SET_INCLUDED_MODEL program and added using the ADD_CUBE_MODEL program, both of which are provided with the OLAP DML.

    DEFINE SETUP_PRE_MODEL PROGRAM
    PROGRAM
     
      VARIABLE _pre_model    text
      VARIABLE _aw_dim       text
     
      _pre_model = 'my_aw!my_pre_model'
      _aw_dim = OBJORG(DIM 'my_time')
     
      DEFINE &_pre_model model
      CONSIDER &_pre_model
      MODEL JOINLINES(JOINCHARS('dimension ' _aw_dim) -
                      JOINCHARS(_aw_dim '(\'L3_3\')=10') -
                      'end')
     
      CALL SET_INCLUDED_MODEL('my_time', 'pre_model', _pre_model)
      CALL ADD_CUBE_MODEL('my_cube', 'my_time', 'pre_model', YES)
    END
    
  2. Load the my_time dimension and load and solve my_cube by executing the following the PL/SQL statement.

    exec dbms_cube.build('MY_CUBE');
    
  3. You can now report on the initial values of sales and moving sales with the static model by issuing the following statement.

    select my_time||'  '||lpad(sales, 2)||'  '||lpad(moving_sales, 2)
    from my_cube_view
    order by my_time asc;
     
    MY_TIME||''||LPAD(SALES,2)||''||LPAD(MOVING_SALES,2)
    --------------------------------------------------------------------
    L1_1  14  14
    L2_1  12  12
    L2_2   2  14
    L3_1   1   1
    L3_2   1   2
    L3_3  10  11
    L3_4   1  11
    L3_5   1   2
     
    8 rows selected.
     
  4. To create a dynamic model where L1_2 = (L2_2' * 2) execute the following PL/SQL statement that calls a user-written OLAP DML program named SETUP_POST_MODEL.

    exec dbms_aw.execute('call my_util_aw!setup_post_model');
     

    As you can see from the definition of the user-written setup_post_model program shown below, the model is actually defined using the SET_INCLUDED_MODEL program and added using the ADD_CUBE_MODEL program, both of which are provided with the OLAP DML.

    DEFINE SETUP_POST_MODEL PROGRAM
    PROGRAM
     
      VARIABLE _post_model   text
      VARIABLE _aw_dim       text
      VARIABLE _start_date   text
      VARIABLE _timespan     text
      VARIABLE _member       text
     
      _post_model = 'my_aw!my_post_model'
      _aw_dim = OBJORG(DIM 'my_time')
      _start_date = OBJORG(ATTRIBUTE 'my_time' 'start_date')
      _timespan = OBJORG(ATTRIBUTE 'my_time' 'timespan')
      _member = 'L1_0'
     
      DEFINE &_post_model model
      CONSIDER &_post_model
      MODEL JOINLINES( -
               JOINCHARS('dimension ' _aw_dim) -
               JOINCHARS(_aw_dim '(\'' _member '\')=' _aw_dim '(\'L2_2\')*2') -
               'end')
     
      CALL SET_INCLUDED_MODEL('my_time', 'post_model', _post_model)
      CALL ADD_CUBE_MODEL('my_cube', 'my_time', 'post_model', NO)
     
      " Add _member to the dimension
      CALL ADD_DIMENSION_MEMBER(_member, 'my_time', NA, 'L1', NA, NO)
      CALL UPDATE_ATTRIBUTE_VALEU(_member, 'my_time', 'start_date', -
                                  &_start_date(&_aw_dim 'L1_1')-365, NO)
      CALL UPDATE_ATTRIBUTE_VALUE(_member, 'my_time', 'timespan', -
                                  &_timespan(&_aw_dim 'L1_1'))
      UPDATE
      COMMIT
    END
     
  5. Execute the following statement to report on the new values of my_time, sales and moving_sales.

     
    select my_time||'  '||lpad(sales, 2)||'  '||lpad(moving_sales, 2)
        from my_cube_view
        order by my_time asc;
    
    MY_TIME||''||LPAD(SALES,2)||''||LPAD(MOVING_SALES,2)
    --------------------------------------------------------------------
    L1_0   4   4
    L1_1  14  18
    L2_1  12  12
    L2_2   2  14
    L3_1   1   1
    L3_2   1   2
    L3_3  10  11
    L3_4   1  11
    L3_5   1   2
     
    9 rows selected.

10.53 SET_PROPERTY

The SET_PROPERTY program modifies the values of the $LOOP_DENSE or $LOOP_VAR properties of a derived measure of a cube as defined in the Oracle data dictionary. The changes made when this program executes are not transactional; an automatic COMMIT is executed as part of the program.

Syntax

CALL SET_PROPERTY(property_name, logical_cube, meas_name, property_value)

Parameters

CALL

Because SET_PROPERTY is an OLAP DML program with arguments, you invoke it using the OLAP DML CALL statement.

property_name

A text expression that is either $LOOP_VAR or $LOOP_DENSE.

logical_cube

A text expression that is the Oracle data dictionary name of the cube that contains meas_name.

meas_name

A text expression that is the Oracle data dictionary name of the derived measure for which you want to modify the value of either the $LOOP_VAR or $LOOP_DENSE property.

property_value

A text expression that is a valid value for the property you specified in property_name. For valid values, see $LOOP_DENSE or $LOOP_VAR.

10.54 SHOW

The SHOW command shows a single value of an expression. Normally, you would use SHOW to show the value of a single-cell variable or to show a message. SHOW is useful in programs when you want to generate an error-like message without creating an error condition. The output from SHOW is sent to the current outfile.

Syntax

SHOW expression [NONL]

Parameters

expression

The value you want to show. When expression is dimensioned, only the first value of the expression is shown, based on the current status of its dimensions. When you are showing a text literal, you must enclose the value in single quotes.

NONL

Indicates that a new line sequence should not be appended to the end of the value. By default, SHOW appends a new line sequence.

Usage Notes

Concatenating Output Lines

The NONL argument to SHOW is useful in programs. Using this argument you can concatenate several values into a single line of output. To accomplish this, include one or more SHOW commands with the NONL argument, followed by a single SHOW statement without the NONL argument. The values from all the SHOW commands are concatenated into a single output value, in the order specified. Depending on the length of the line, this value might actually produce multiple lines of output.

Generating Error Messages

SHOW can be used as an alternative to SIGNAL when you want to generate an error message from a program. Unlike SIGNAL, SHOW produces a message without signaling an error condition and thus halting execution of the program. Your error message may be most useful when you send it to a debugging file. When you use a DBGOUTFILE statement to direct messages to a debugging file, the output from SHOW is sent to the debugging file and to your current outfile.

Showing Values of Composites

When SHOW is used with a named or unnamed composite, an NA value is shown when the composite does not have a value that corresponds to the first values in the status for its base dimensions. For example, the statement

SHOW SPARSE <market product>

produces an NA value when the combination of the current values of market and product does not exist in the composite.

Breaking Lines of Text

To break a text expression into two or more lines of output text, insert newline delimiters (\n) at the appropriate places in the text.

Using SHOW With NTEXT Values

The SHOW command converts NTEXT values to the character set of the outfile. When an NTEXT value cannot be represented in the outfile character set, the character is not displayed correctly.

Examples

Example 10-119 Showing the Value of an Option

This example uses SHOW to report the current value of the DECIMALS option. The OLAP DML statement

SHOW DECIMALS

produces the following output.

2

Example 10-120 Showing a Data Value

When you use SHOW to report the value of a dimensioned variable, only the first value of the variable, based on the current status of its dimensions, is shown. The OLAP DML statement

SHOW JOINCHARS('Actual = ' actual)

produces the following output.

Actual = 533,362,88 

Example 10-121 Creating Error Messages Using SHOW

When you want to produce a warning message without branching to an error label, then you can use a SHOW statement.

select:
LIMIT month TO nummonths
IF STATLEN(month) GT 9
   THEN DO
     SHOW 'You can select no more than 9 months.'
     GOTO finish
     DOEND
REPORT DOWN district W 6 units
finish:
POP month
RETURN

Example 10-122 Showing the Values of a Valueset

Suppose an analytic workspace contains a valueset called monthset that has the values Jan95, May95, and Dec95. You can use SHOW to list the values in that valueset.

SHOW monthset
Jan95
May95
Dec95

10.55 SIGNAL

The SIGNAL command produces a user-defined error message from within a program. When Oracle OLAP executes a SIGNAL statement when TRAP is ON, execution branches to the trap label. Any statements following the trap label in the program are then executed.When the program contains an active trap label, execution branches to the label. Without a trap label, execution of the program terminates and, when the program was called by another program, execution control returns to the calling program.

Syntax

SIGNAL {errname [message]|STOP}

Parameters

errname

A TEXT expression that indicates the name of the error message to be produced. When Oracle OLAP executes a SIGNAL statement, it stores the errname in the ERRORNAME option. Normally, the name of the error does not appear in the error message. However, when you omit message, the error name (errname) appears along with a stock message as described in the message argument.

You can use the special name PRGERR to communicate to a calling program that an error has occurred. The statement SIGNAL PRGERR sets ERRORNAME to a blank value and passes an error condition to the calling program without causing another error message to be displayed. For a complete explanation of how to use SIGNAL to pass an error up a chain of nested programs, see the TRAP command.

message

A TEXT expression that specifies the error message to be produced. When you supply a long line as your error message, you must add your own line breaks to format the text. Type the newline escape sequence (\n) where you want each line to end. You can type up to a limit of 6 lines or 4,000 characters, whichever you reach first. An error occurs when you try to supply a single line longer than 4,000 characters.

When you omit this argument, SIGNAL produces the following message.

ERROR: (errname) Please contact the administrator of your
   Oracle Oracle OLAP application.

When Oracle OLAP executes a SIGNAL statement, it stores message in the ERRORTEXT option.

STOP

Immediately stops execution of all currently running programs. No error message is produced. The error condition is not trapped by an active TRAP label.

Examples

Example 10-123 Signaling an Error

Suppose you have written a program that requires one argument. When no argument is supplied, there is no purpose in running the program. Therefore, the first thing the program does is check if an argument has been passed. When it has not, the program terminates after sending an error message to the current outfile.

The following program lines check for the argument and signal an error when it is not found.

IF ARGS EQ ''
THEN SIGNAL msg1 'You must supply an argument.'

SIGNAL sends the following message to the current outfile.

ERROR: You must supply an argument.

Example 10-124 Signaling an Error When an Argument Value is Invalid

Suppose your program produces a report that can present from one to nine months of data. You can signal an error when the program is called with an argument value greater than nine. In this example, nummonths is the name of the argument that must be no greater than nine.

select:
TRAP ON error
PUSH month
LIMIT month TO nummonths
IF STATLEN(month) GT 9
   THEN SIGNAL toomany -
     'You can specify no more than 9 months.'
REPORT DOWN district W 6 units
finish:
POP month
RETURN
error:
POP month
IF ERRORNAME EQ 'TOOMANY'
   THEN SHOW 'No report produced'

10.56 SLEEP

Within an OLAP DML program, the SLEEP command suspends the program execution for at least the specified number of seconds.

Note:

SLEEP is rarely used in Oracle OLAP programs, because there is seldom a need to suspend program execution.

Syntax

SLEEP n

Parameters

n

A numeric expression that specifies the number of seconds for Oracle OLAP to "sleep." Program execution is suspended for at least this number of seconds.

Examples

Example 10-125 Suspending Program Execution

In a program, suppose you execute a statement that might take 10 seconds to complete. You can follow that statement with this SLEEP statement, which suspends program execution for 10 seconds.

SLEEP 10

10.57 SORT command

The SORT command arranges the order of values in the current status list of a dimension or a dimension surrogate, or in a valueset.

See Also:

SORT function

Syntax

SORT dimension [byhierarchy] [bycriterion...]

where:

  • byhierarchy is an optional phrase that uses a parent relation to arrange the order of values in the current status list of a hierarchical dimension or its dimension surrogate, or to assign values to a valueset, based on family relationships within the hierarchy. You can include only one byhierarchy phrase in a SORT statement. It must be the first phrase in a SORT statement.

    HIERARCHY parent-relation [INVERT] [DEPTH n] [SORTORPHANS]

  • bycriterion uses an explicit criterion to arrange the order of values in the current status list of a dimension or its dimension surrogate, or to assign values to a valueset. You can include as many bycriterion phrases as you want in a SORT statement.

    {A|D} [NAFIRST] criterion

Parameters

dimension

A text expression whose value is the name of a dimension, a dimension surrogate, or a valueset.

HIERARCHY

Specifies that Oracle OLAP is to sort dimension values based on the values position in parentrel.

parent-relation

Specifies the name of a child-parent self-relation for dimension. For each dimension value, the relation holds another value of the dimension which is its parent dimension value (the one immediately above it in a given hierarchy). This parent relation can have multiple dimensions.

Tip:

You can specify a QDR of parent-relation to specify a single value.

INVERT

Indicates that Oracle OLAP places the children in the hierarchy before their parents. (By default, children are placed after their parents.)

DEPTH n

Specifies the number of generations down from the top of the hierarchy that Oracle OLAP should place into status and. there, for the values that are included in the result. The default value of n is 99. When you do not want any values in the result (that is, when you want a NULL status), specify -1 for n. When you only want the top of the hierarchy in status (that is, those dimension values that do not have parents), specify 0 (zero).

SORTORPHANS

Specifies that all first cousins whose parents are not in status are sorted together. By default, Oracle OLAP preserves the hierarchical structure when sorting children even when their parents are not in status.

A
D

The order in which the values are to be sorted. A means ascending order (alphabetical when the sorting criterion is TEXT, ID, or a relation), and D means descending order (reverse alphabetical when the sorting criterion is TEXT, ID or a relation).

NAFIRST

Specifies that NA values are to placed first in the sort rather than last.

criterion

The expression to be used as a sorting criterion. Each criterion must be dimensioned by dimension. The first expression is the major sorting criterion. When the expression is multidimensional, SORT uses the first value in status for all dimensions other than the dimension being sorted. You cannot use a valueset as the sorting criterion.

Usage Notes

Sorting a Dimension and a Valueset

When Oracle OLAP sorts a dimension, it sorts the temporary status list of a dimension, not the data dimensioned by it. Because many OLAP DML statements operate on data according to the current status of its dimensions, sorting a dimension appears to have the effect of sorting data. A dimension and any dimension surrogates for it share the same status. Therefore, a SORT statement on a dimension or any of its surrogates sorts them all.

When Oracle OLAP sorts a valueset, it sorts the actual values within the valueset. When you execute UPDATE and COMMIT commands after sorting a valueset, the values in the valueset are stored in that sorted order.

Sorting Alphabetically

To sort a TEXT or ID dimension or its valueset in alphabetical order, use the dimension itself as the sorting criterion.

SORT district A district
<