User-Written Programs Looked For by Oracle OLAP

ONATTACH
ONDETACH
PERMIT_READ
PERMIT_WRITE
TRIGGER_AFTER_UPDATE
TRIGGER_AW
TRIGGER_BEFORE_UPDATE
TRIGGER_DEFINE

ONATTACH

An ONATTACH program is a program that you can create and that Oracle OLAP checks for by name when an AW ATTACH command executes. Depending on the value returned by the program, Oracle OLAP executes the code within the program immediately after attaching the analytic workspace. Depending on the statements in the onattach program, the user is granted or denied access to specific objects or sets of object values.

For multiwriter attachment, you can use ACQUIRE commands to provide access to individual workspace objects. For read-only and read/write attachment, you can use PERMIT commands that grant or restrict access to individual workspace objects. All of the objects referred to in a given onattach program must exist in the same analytic workspace.

Note:

Oracle OLAP checks for other programs when a user attaches an analytic workspace. See "Programs Executed When Attaching Analytic Workspaces" for more information.

Return Value

BOOLEAN

TRUE when Oracle OLAP has successfully set up and attached the analytic workspace; or FALSE when it has not or when the onattach program has thrown an exception.

Note:

You are encouraged to use the normal return values rather than relying on exceptions to create a return value of FALSE.

Syntax

To define a program with the name ONATTACH use the syntax shown in DEFINE PROGRAM. Code the actual program as a user-defined function with the following argument.

ONATTACH ({READ|WRITE|EXCLUSIVE|MULTI} password)

Arguments

See AW ATTACH for explanations of the attachment modes (that is, READ, WRITE, EXCLUSIVE, and MULTI) and password.

Examples

For examples of how attachment programs behave, see Example 9-49, "Startup Programs".

ONDETACH

An ONDETACH program is a program that you can create and that Oracle OLAP checks for by name when an AW DETACH command executes. Depending on the value returned by the program, Oracle OLAP executes the code within the program immediately after detaching the analytic workspace.

Note:

Oracle OLAP checks for other programs when a user attaches an analytic workspace. See "Programs Executed When Attaching Analytic Workspaces" for more information.

Return Value

BOOLEAN

TRUE when Oracle OLAP has successfully detached the analytic workspace; or FALSE when it has not or when the detach program has thrown an exception.

Note:

You are encouraged to use the normal return values rather than relying on exceptions to create a return value of FALSE.

Syntax

To define a program with the name ONDETACH use the syntax shown in DEFINE PROGRAM.

PERMIT_READ

A PERMIT_READ program is a program that you can create and that Oracle OLAP checks for by name when an AW ATTACH read-only command executes. Depending on the value returned by the program, Oracle OLAP executes the code within the program after attaching the analytic workspace. Depending on the statements in the permit_read program the user is granted or denied access to specific objects or sets of object values. Within permit_read program, you can specify PERMIT commands that grant or restrict access to individual workspace objects. All of the objects referred to in a given permit_read must exist in the same analytic workspace.

See also:

"Startup Programs"

Return Value

BOOLEAN

TRUE when Oracle OLAP has successfully set up and attached the analytic workspace; or FALSE when it has not or when the permit_read program has thrown an exception

Note:

You are encouraged to use the normal return values rather than relying on exceptions to create a return value of FALSE.

Syntax

To define a program with the name PERMIT_READ use the syntax shown in DEFINE PROGRAM. Code the actual program as a user-defined function with the following argument.

PERMIT_READ (password)

Arguments

See AW ATTACH for an explanation of password. When a user specifies a password when attaching the analytic workspace, then the password is passed as an argument to the program for processing.

Examples

To see the order in which permission programs are executed when an analytic workspace is attached, see Example 9-49, "Startup Programs".

PERMIT_WRITE

A PERMIT_WRITE program is a program that you can create and that Oracle OLAP checks for by name when an AW ATTACH read/write command executes. Depending on the value returned by the program, Oracle OLAP executes the code within the program after attaching the analytic workspace. Depending on the statements in the permit_write program, the user is granted or denied access to specific objects or sets of object values. Within permit_write program, you can specify PERMIT commands that grant or restrict access to individual workspace object. All of the objects referred to in a given permit_write program must exist in the same analytic workspace.

See also:

"Startup Programs"

Return Value

BOOLEAN

TRUE when Oracle OLAP has successfully set up and attached the analytic workspace; or FALSE when it has not or when the permit_write program has thrown an exception

Note:

You are encouraged to use the normal return values rather than relying on exceptions to create a return value of FALSE.

Syntax

To define a program with the name PERMIT_WRITE use the syntax shown in DEFINE PROGRAM. Code the actual program as a user-defined function with the following argument.

PERMIT_WRITE (password)

Arguments

See AW ATTACH for an explanation of password. When a user specifies a password when attaching the analytic workspace, then the password is passed as an argument to the program for processing.

Examples

To see the order in which permission programs are executed when an analytic workspace is attached, see Example 9-49, "Startup Programs".

TRIGGER_AFTER_UPDATE

A TRIGGER_AFTER_UPDATE program is a program that you can create in an analytic workspace and that Oracle OLAP checks for by name when an UPDATE command for that analytic workspace executes. When the program exists in the same analytic workspace that you are updating, Oracle OLAP executes the program after executing the UPDATE.

Note:

The USETRIGGERS option must be set to its default value of TRUE for a TRIGGER_AFTER_UPDATE program to execute

See also:

"Trigger Programs".

Syntax

To create a program with the name TRIGGER_AFTER_UPDATE, follow the guidelines presented in "Trigger Programs".

Examples

Example 4-1 TRIGGER_AFTER_UPDATE Program

Assume you have defined the following program in your analytic workspace.

DEFINE TRIGGER_AFTER_UPDATE PROGRAM
PROGRAM
SHOW JOINCHARS ('calltype = ' CALLTYPE)
SHOW JOINCHARS ('triggering event = ' TRIGGER(EVENT))
SHOW JOINCHARS ('triggering subevent = ' TRIGGER(SUBEVENT))
END

When you issue an UPDATE statement the program executes and displays the following output.

calltype = TRIGGER
triggering event = AFTER_UPDATE
triggering subevent = AW

TRIGGER_AW

A TRIGGER_AW program is a program that you can create in one analytic workspace and that Oracle OLAP checks for by name when that analytic workspace is current and you create, attach, detach, or delete any other analytic workspace.

See also:

"Trigger Programs".

Return Value

None.

Syntax

To create a program with the name TRIGGER_AW, follow the guidelines presented in"How to Create a TRIGGER_AW Program".

Notes

How to Create a TRIGGER_AW Program

You create a TRIGGER_AW program by following the following procedure:

Define the program as described in DEFINE PROGRAM.
Name the program TRIGGER_AW.
Code the actual program as described in"Specifying Program Contents".

Note:
There is no support for recursive triggers. You must set the USETRIGGERS option to NO before you issue an AW statement within an TRIGGER_AW program

TRIGGER_BEFORE_UPDATE

A TRIGGER_BEFORE_UPDATE program is a program that you can create and that Oracle OLAP checks for by name when an UPDATE command executes. When the program exists in the same analytic workspace that you are updating, Oracle OLAP executes the program and then, depending on the value returned by the program (if any), either does nor does not update the workspace.

Note:

The USETRIGGERS option must be set to its default value of TRUE for a TRIGGER_BEFORE_UPDATE program to execute

See also:

"Trigger Programs".

Return Value

You can write the program as a function that returns a BOOLEAN value. In this case, when the program returns FALSE, Oracle OLAP does not execute the UPDATE statement that triggered the execution of the TRIGGER_BEFORE_UPDATE program; when the program returns TRUE or NA, the UPDATE statement executes.

Syntax

To create a program with the name TRIGGER_UPDATE, follow the guidelines presented in"Trigger Programs".

Examples

Example 4-2 TRIGGER_BEFORE_UPDATE Program

Assume that an analytic workspace named myaw has an TRIGGER_BEFORE_UPDATE program with the following definition.

DEFINE TRIGGER_BEFORE_UPDATE PROGRAM BOOLEAN
PROGRAM
SHOW JOINCHARS ('calltype = ' CALLTYPE)
SHOW JOINCHARS ('triggering event = ' TRIGGER(EVENT))
SHOW JOINCHARS ('triggering subevent = ' TRIGGER(SUBEVENT))
RETURN TRUE
END

Assume that you define a TEXT variable named myvar and, then, issue an UPDATE statement. The TRIGGER_BEFORE_UPDSATE program executes.

calltype = TRIGGER
triggering event = BEFORE_UPDATE
triggering subevent = AW

Because the program returned TRUE, the definition for myvar exists after you detach and reattach the workspace.

AW DETACH myaw
AW ATTACH myaw
DESCRIBE

DEFINE TRIGGER_BEFORE_UPDATE PROGRAM BOOLEAN
PROGRAM
SHOW JOINCHARS ('calltype = ' CALLTYPE)
SHOW JOINCHARS ('triggering event = ' TRIGGER(EVENT))
SHOW JOINCHARS ('triggering subevent = ' TRIGGER(SUBEVENT))
RETURN TRUE
END
 
DEFINE MYVAR VARIABLE TEXT

However, if you modified the program so that it returned FALSE, then when you detach and reattach the workspace, not only would the myvar definition not in the workspace, the definition for the TRIGGER_BEFORE_UPDATE program would also not be in the workspace.

TRIGGER_DEFINE

A TRIGGER_DEFINE program is a program that you create and that Oracle OLAP checks for by name when a DEFINE command executes. When the program exists in the same analytic workspace in which you are defining a new object, Oracle OLAP executes the program.

Note:

The USETRIGGERS option must be set to its default value of TRUE for a TRIGGER_DEFINE program to execute

See also:

"Trigger Programs".

Syntax

To create a program with the name TRIGGER_DEFINE, follow the guidelines presented in "Trigger Programs".

Examples

Example 4-3 A TRIGGER_DEFINE Program

Assume that you have written a TRIGGER_DEFINE program with the following description in your analytic workspace.

DEFINE TRIGGER_DEFINE PROGRAM
PROGRAM
SHOW JOINCHARS ('calltype = ' CALLTYPE)
SHOW JOINCHARS ('triggering event = ' TRIGGER(EVENT))
SHOW JOINCHARS ('fully-qualified object name ='TRIGGER(NAME))
SHOW JOINCHARS ('type of object = 'OBJ(TYPE TRIGGER(NAME))
DESCRIBE &TRIGGER(NAME)
END

Assume, as shown in the following statements, that you issue a DEFINE VARIABLE statement to define a variable named myvar. As shown by the output following the statement, Oracle OLAP defines the variable and executes the TRIGGER_DEFINE program.

DEFINE myvar VARIABLE TEXT
calltype = TRIGGER
triggering event = DEFINE
fully-qualified object name =MYAW!MYVAR
type of object = VARIABLE
 
DEFINE MYVAR VARIABLE TEXT