|Oracle9i OLAP Services Developer's Guide to the OLAP DML
Release 1 (9.0.1)
Part Number A86720-01
Designing Programs, 10 of 13
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:
Contexts are the most sophisticated way to save object values for use during a session of OLAP Services. With contexts, you can access and update the saved object values, whereas PUSH and POP simply allow you to save and restore values. Typically, you use the PUSH and POP commands within a program to make changes that apply only during the program's execution.
The 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 POP command.
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 PUSHLEVEL and POPLEVEL commands provide an alternative and more 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.
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 FIRSTLEVEL marker.
If you place more than one PUSH command between the PUSHLEVEL and POPLEVEL commands, then all the objects that are specified in those PUSH commands are restored with a single POPLEVEL command.
By using PUSHLEVEL and 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.
You can nest PUSHLEVEL and 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 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 will not use more than one set 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.
As an alternative to using PUSHLEVEL and POPLEVEL, you can use the CONTEXT command and CONTEXT function. With these, you can access and update your saved object values, as well as save and restore them. For details about using named contexts, see the entries for the CONTEXT command and the CONTEXT function in OLAP DML Reference.