|Oracle9i OLAP Developer's Guide to the OLAP DML
Release 2 (9.2)
Part Number A95298-01
Developing Programs, 9 of 12
One advantage to the modular design approach is that each program has a clearly defined area of responsibility, and it does not affect the workings of other programs. To make this possible, each program must act as a "good citizen" by saving global settings before it changes them and restoring global settings before it finishes execution.
There are two types of environment settings:
To perform a task within a program, you often need to change the output destination or some dimension and option values. For example, you might run a monthly sales report that always shows the last six months of sales data. You might want to show the data without decimal places, include the text "No Sales" where the sales figure is zero, and send the report to a file. To set up this program environment, you can use the following commands in your program.
To avoid disrupting the session environment, the initialization section of a program should save the values of the dimensions and options that will be set in the program. In the normal and abnormal exit sections at the end of the program, you can restore the saved environment, so that other programs do not need to be concerned about whether any values have been changed. In addition, if you have sent output to a file, then the exit sections should return the output destination to the default outfile.
The following suggestions let you save the environment of a program or a session:
PUSHcommands. You can restore the current status values using the
CONTEXTcommand to define the context.
Contexts are the most sophisticated way to save object values for use during a session. With contexts, you can access, update, and commit the saved object values. In contrast,
POP simply allow you to save and restore values. Typically, you use the
POP commands within a program to make changes that apply only during the program's execution.
PUSH command saves the current status of a dimension, the value of an option, or the value of a single-cell variable. For example, to save the current value of the
DECIMALS option so you can set it to a different value for the duration of the program, use the following command in the initialization section.
You do not need to know the original value of the option to save it or to restore it later. You can restore the saved value with the
You must make sure the
POP command is executed when errors cause abnormal termination of the program as well as when the program ends normally. Therefore, you should place the
POP command in the normal and abnormal exit sections of the program.
You can save the status of one or more dimensions and the values of any number of options and variables in a single
PUSH command, and you can restore the values with a single
POP command, as shown in the following example.
If you are saving the values of several dimensions and options, then the
POPLEVEL commands provide a convenient way to save and restore the session environment.
You first use the
PUSHLEVEL command to establish a level marker. Once the level marker is established, you use the
PUSH command to save the status of dimensions and the values of options or single-cell variables.
If you place more than one
PUSH command between the
POPLEVEL commands, then all the objects that are specified in those
PUSH commands are restored with a single
POPLEVEL, you save some typing as you write your program because you only need to type the list of objects once. You also reduce the risk of omitting an object from the list or misspelling the name of an object.
For example, you can use the
PUSHLEVEL command to establish a level marker called
firstlevel, and then use
PUSH to save the current values.
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 the
POPLEVEL command to restore all the values you saved since establishing the
You can nest
POPLEVEL 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 '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 will not use more than one set of
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
As an alternative to using
POPLEVEL, you can use the
CONTEXT command. After you create a context, you can save the current status of dimensions and the values of options, single-cell variables, valuesets, and single-cell relations in the context. You can then restore some or all of the object values from the context. The
CONTEXT function returns information about objects in a context.