If the definition of object A references object B, then A depends on B. This chapter explains dependencies among schema objects, and how Oracle Database automatically tracks and manages these dependencies. Because of this automatic dependency management, A never uses an obsolete version of B, and you almost never have to explicitly recompile A after you change B.
Topics:
Some types of schema objects can reference other objects in their definitions. For example, a view is defined by a query that references tables or other views, and the body of a subprogram can include SQL statements that reference other objects. If the definition of object A references object B, then A is a dependent object (of B) and B is a referenced object (of A).
Example 18-1 shows how to display the dependent and referenced object types in your database (if you are logged in as DBA).
Example 18-1 Displaying Dependent and Referenced Object Types
Display dependent object types:
SELECT DISTINCT TYPE FROM DBA_DEPENDENCIES ORDER BY TYPE;
Result:
TYPE ------------------ DIMENSION EVALUATION CONTXT FUNCTION INDEX INDEXTYPE JAVA CLASS JAVA DATA MATERIALIZED VIEW OPERATOR PACKAGE PACKAGE BODY TYPE ------------------ PROCEDURE RULE RULE SET SYNONYM TABLE TRIGGER TYPE TYPE BODY UNDEFINED VIEW XML SCHEMA 22 rows selected.
Display referenced object types:
SELECT DISTINCT REFERENCED_TYPE FROM DBA_DEPENDENCIES ORDER BY REFERENCED_TYPE;
Result:
REFERENCED_TYPE ------------------ EVALUATION CONTXT FUNCTION INDEX INDEXTYPE JAVA CLASS LIBRARY NON-EXISTENT OPERATOR PACKAGE PROCEDURE SEQUENCE REFERENCED_TYPE ------------------ SYNONYM TABLE TYPE VIEW XML SCHEMA 16 rows selected.
If you alter the definition of a referenced object, dependent objects might not continue to function without error, depending on the type of alteration. For example, if you drop a table, no view based on the dropped table is usable.
As an example of a schema object change that invalidates some dependents but not others, consider the two views in Example 18-2, which are based on the HR.EMPLOYEES table.
Example 18-2 creates two views from the EMPLOYEES table: SIXFIGURES, which selects all columns in the table, and COMMISSIONED, which does not include the EMAIL column. As the example shows, changing the EMAIL column invalidates SIXFIGURES, but not COMMISSIONED.
Example 18-2 Schema Object Change that Invalidates Some Dependents
CREATE OR REPLACE VIEW sixfigures AS SELECT * FROM employees WHERE salary >= 100000; CREATE OR REPLACE VIEW commissioned AS SELECT first_name, last_name, commission_pct FROM employees WHERE commission_pct > 0.00;
SQL*Plus formatting command:
COLUMN object_name FORMAT A16
Query:
SELECT object_name, status FROM user_objects WHERE object_type = 'VIEW' ORDER BY object_name;
Result:
OBJECT_NAME STATUS ---------------- ------- COMMISSIONED VALID SIXFIGURES VALID
Lengthen EMAIL column of EMPLOYEES table:
ALTER TABLE employees MODIFY email VARCHAR2(100);
Query:
SELECT object_name, status FROM user_objects WHERE object_type = 'VIEW' ORDER BY object_name;
Result:
OBJECT_NAME STATUS ---------------- ------- COMMISSIONED INVALID SIXFIGURES VALID
A view depends on every object referenced in its query. The view in Example 18-3, depends on the tables employees and departments.
Example 18-3 View that Depends on Multiple Objects
CREATE OR REPLACE VIEW v AS SELECT last_name, first_name, department_name FROM employees e, departments d WHERE e.department_id = d.department_id ORDER BY last_name;
|
Notes:
|
The static data dictionary views USER_DEPENDENCIES, ALL_DEPENDENCIES, and DBA_DEPENDENCIES describe dependencies between database objects.
The utldtree.sql SQL script creates the view DEPTREE, which contains information on the object dependency tree, and the view IDEPTREE, a presorted, pretty-print version of DEPTREE.
|
See Also: Oracle Database Reference for more information about theDEPTREE, IDEPTREE, and utldtree.sql script |
Every database object has a status value described in Table 18-1.
Table 18-1 Database Object Status
| Status | Meaning |
|---|---|
|
Valid |
The object was successfully compiled, using the current definition in the data dictionary. |
|
Compiled with errors |
The most recent attempt to compile the object produced errors. |
|
Invalid |
The object is marked invalid because an object that it references has changed. (Only a dependent object can be invalid.) |
|
Unauthorized |
An access privilege on a referenced object was revoked. (Only a dependent object can be unauthorized.) |
|
Note: The static data dictionary viewsUSER_OBJECTS, ALL_OBJECTS, and DBA_OBJECTS do not distinguish between "Compiled with errors," "Invalid," and "Unauthorized"—they describe all of these as INVALID. |
If object A depends on object B, which depends on object C, then A is a direct dependent of B, B is a direct dependent of C, and A is an indirect dependent of C.
Direct dependents are invalidated only by changes to the referenced object that affect them (changes to the signature of the referenced object).
Indirect dependents can be invalidated by changes to the reference object that do not affect them. If a change to C invalidates B, it invalidates A (and all other direct and indirect dependents of B). This is called cascading invalidation.
With coarse-grained invalidation, a data definition language (DDL) statement that changes a referenced object invalidates all of its dependents.
With fine-grained invalidation, a DDL statement that changes a referenced object invalidates only dependents for which either of these statements is true:
The dependent relies on the attribute of the referenced object that the DDL statement changed.
The compiled metadata of the dependent is no longer correct for the changed referenced object.
For example, if view v selects columns c1 and c2 from table t, a DDL statement that changes only column c3 of t does not invalidate v.
The DDL statement CREATE OR REPLACE object has no effect under these conditions:
object is a PL/SQL object, the new PL/SQL source text is identical to the existing PL/SQL source text, and the PL/SQL compilation parameter settings stored with object are identical to those in the session environment.
For information about PL/SQL compilation parameter settings, see Oracle Database PL/SQL Language Reference.
object is a synonym and the statement does not change the target object.
The operations in the left column of Table 18-2 cause fine-grained invalidation, except in the cases in the right column. The cases in the right column, and all operations not listed in Table 18-2, cause coarse-grained invalidation.
Table 18-2 Operations that Cause Fine-Grained Invalidation
| Operation | Exceptions |
|---|---|
|
|
|
|
|
|
|
Online Table Redefinition ( |
Column lists of new and old definitions differ, and at least one of these is true:
|
|
|
|
|
|
|
|
|
Call signature changes. Call signature is the parameter list (order, names, and types of parameters), return type, purityFoot 1 , determinism, parallelism, pipelining, and (if the procedure or function is implemented in C or Java) implementation properties. |
|
|
|
Footnote 1 Purity refers to a set of rules for preventing side effects (such as unexpected data changes) when invoking PL/SQL functions within SQL queries. Package purity refers to the purity of the code in the package initialization block.
Footnote 2 The entry-point number of a procedure or function is determined by its location in the PL/SQL package code. A procedure or function added to the end of a PL/SQL package is given a new entry-point number.
|
Note: A dependent object that is invalidated by an operation in Table 18-2 appears in the static data dictionary views*_OBJECTS and *_OBJECTS_AE only after an attempt to reference it (either during compilation or execution) or after invoking one of these subprograms:
|
Topics:
Each session that references a package construct has its own instantiation of that package, including a persistent state of any public and private variables, cursors, and constants. All of a session's package instantiations, including state, can be lost if any of the session's instantiated packages are subsequently invalidated and revalidated.
|
See Also:
|
When a data manipulation language (DML) object or system privilege is granted to, or revoked from, a user or PUBLIC, Oracle Database invalidates all the owner's dependent objects, to verify that an owner of a dependent object continues to have the necessary privileges for all referenced objects.
To reduce invalidation of dependent objects, follow these guidelines:
When adding items to a package, add them to the end of the package. This preserves the entry point numbers of existing top-level package items, preventing their invalidation.
For example, consider this package:
CREATE OR REPLACE PACKAGE pkg1 IS FUNCTION get_var RETURN VARCHAR2; END; /
Adding an item to the end of pkg1, as follows, does not invalidate dependents that reference the get_var function:
CREATE OR REPLACE PACKAGE pkg1 IS
FUNCTION get_var RETURN VARCHAR2;
PROCEDURE set_var (v VARCHAR2);
END;
/
Inserting an item between the get_var function and the set_var procedure, as follows, invalidates dependents that reference the set_var function:
CREATE OR REPLACE PACKAGE pkg1 IS
FUNCTION get_var RETURN VARCHAR2;
PROCEDURE assert_var (v VARCHAR2);
PROCEDURE set_var (v VARCHAR2);
END;
/
Reference tables indirectly, using views, enabling you to:
Add columns to the table without invalidating dependent views or dependent PL/SQL objects
Modify or delete columns not referenced by the view without invalidating dependent objects
The statement CREATE OR REPLACE VIEW does not invalidate an existing view or its dependents if the new ROWTYPE matches the old ROWTYPE.
An object that is not valid when it is referenced must be validated before it can be used. Validation occurs automatically when an object is referenced; it does not require explicit user action.
If an object is not valid, its status is either compiled with errors, unauthorized, or invalid. For definitions of these terms, see Table 18-1.
Topics:
Revalidation of Objects that Compiled with Errors
The compiler cannot automatically revalidate an object that compiled with errors. The compiler recompiles the object, and if it recompiles without errors, it is revalidated; otherwise, it remains invalid.
Revalidation of Unauthorized Objects
The compiler checks whether the unauthorized object has access privileges to all of its referenced objects. If so, the compiler revalidates the unauthorized object without recompiling it. If not, the compiler issues appropriate error messages.
Revalidation of Invalid SQL Objects
The SQL compiler recompiles the invalid object. If the object recompiles without errors, it is revalidated; otherwise, it remains invalid.
Revalidation of Invalid PL/SQL Objects
For an invalid PL/SQL program unit (procedure, function, or package), the PL/SQL compiler checks whether any referenced object changed in a way that affects the invalid object. If so, the compiler recompiles the invalid object. If the object recompiles without errors, it is revalidated; otherwise, it remains invalid. If not, the compiler revalidates the invalid object without recompiling it.
Object names referenced in SQL statements have one or more pieces. Pieces are separated by periods—for example, hr.employees.department_id has three pieces.
Oracle Database uses this procedure to try to resolve an object name:
Try to qualify the first piece of the object name.
If the object name has only one piece, then that piece is the first piece. Otherwise, the first piece is the piece to the left of the leftmost period; for example, in hr.employees.department_id, the first piece is hr.
The procedure for trying to qualify the first piece is:
If the object name is a table name that appears in the FROM clause of a SELECT statement, and the object name has multiple pieces, go to step d. Otherwise, go to step b.
Search the current schema for an object whose name matches the first piece.
Search for a public synonym that matches the first piece.
Search for a schema whose name matches the first piece.
If found, and if the object name has a second piece, go to step e. Otherwise, return an error—the object name cannot be qualified.
Search the schema found at step d for a SQL function whose name matches the second piece of the object name.
If found, the schema redefined that SQL function. The object name resolves to the original SQL function, not to the schema-defined function of the same name. Go to step 2.
If not found, return an error—the object name cannot be qualified.
A schema object has been qualified. Any remaining pieces of the object name must match a valid part of this schema object.
For example, if the object name is hr.employees.department_id, hr is qualified as a schema. If employees is qualified as a table, department_id must correspond to a column of that table. If employees is qualified as a package, department_id must correspond to a public constant, variable, procedure, or function of that package.
Because of how Oracle Database resolves references, an object can depend on the nonexistence of other objects. This situation occurs when the dependent object uses a reference that would be interpreted differently if another object were present.
|
See Also:
|
Local dependency management occurs when Oracle Database manages dependencies among the objects in a single database. For example, a statement in a procedure can reference a table in the same database.
Remote dependency management occurs when Oracle Database manages dependencies in distributed environments across a network. For example, an Oracle Forms trigger can depend on a schema object in the database. In a distributed database, a local view can reference a remote table.
Oracle Database also manages distributed database dependencies. For example, an Oracle Forms application might contain a trigger that references a table. The database system must account for dependencies among such objects. Oracle Database uses different mechanisms to manage remote dependencies, depending on the objects involved.
Topics:
Dependencies among stored procedures (including functions, packages, and triggers) in a distributed database system are managed using either time-stamp checking or signature checking (see "Time-Stamp Dependency Mode" and "RPC-Signature Dependency Mode").
The dynamic initialization parameter REMOTE_DEPENDENCIES_MODE determines whether time stamps or signatures govern remote dependencies.
Oracle Database does not manage dependencies among remote schema objects other than local-procedure-to-remote-procedure dependencies.
For example, assume that a local view is created and defined by a query that references a remote table. Also assume that a local procedure includes a SQL statement that references the same remote table. Later, the definition of the table is altered.
Therefore, the local view and procedure are never invalidated, even if the view or procedure is used after the table is altered, and even if the view or procedure now returns errors when used. In this case, the view or procedure must be altered manually so that errors are not returned. In such cases, lack of dependency management is preferable to unnecessary recompilations of dependent objects.
Code in database applications can reference objects in the connected database. For example, Oracle Call Interface (OCI) and precompiler applications can submit anonymous PL/SQL blocks. Triggers in Oracle Forms applications can reference a schema object.
Such applications are dependent on the schema objects they reference. Dependency management techniques vary, depending on the development environment. Oracle Database does not automatically track application dependencies.
|
See Also: Manuals for your application development tools and your operating system for more information about managing the remote dependencies within database applications |
Remote procedure call (RPC) dependency management occurs when a local stored procedure calls a remote procedure in a distributed database system. The dynamic initialization parameter REMOTE_DEPENDENCIES_MODE controls the dependency mode. The choice is either time-stamp dependency mode or RPC-signature dependency mode.
Topics:
Whenever a procedure is compiled, its time stamp is recorded in the data dictionary. The time stamp shows when the procedure was created, altered, or replaced.
A compiled procedure contains information about each remote procedure that it calls, including the schema, package name, procedure name, and time stamp of the remote procedure.
In time-stamp dependency mode, when a local stored procedure calls a remote procedure, Oracle Database compares the time stamp that the local procedure has for the remote procedure to the current time stamp of the remote procedure. If the two timestamps match, both the local and remote procedures run. Neither is recompiled.
If the two timestamps do not match, the local procedure is invalidated and an error is returned to the calling environment. All other local procedures that depend on the remote procedure with the new time stamp are also invalidated.
Time stamp comparison occurs when a statement in the body of the local procedure calls the remote procedure. Therefore, statements in the local procedure that precede the invalid call might run successfully. Statements after the invalid call do not run. The local procedure must be recompiled.
If DML statements precede the invalid call, they roll back only if they and the invalid call are in the same PL/SQL block. For example, the UPDATE statement rolls back in this code:
BEGIN
UPDATE table SET ... invalid_proc; COMMIT;
END;
But the UPDATE statement does not roll back in this code:
UPDATE table SET ... EXECUTE invalid_proc; COMMIT;
The disadvantages of time-stamp dependency mode are:
Dependent objects across the network are often recompiled unnecessarily, degrading performance.
If the client-side application uses PL/SQL, this mode can cause situations that prevent the application from running on the client side.
An example of such an application is Oracle Forms. During installation, you must recompile the client-side PL/SQL procedures that Oracle Forms uses at the client site. Also, if a client-side procedure depends on a server procedure, and if the server procedure changes or is automatically recompiled, you must recompile the client-side PL/SQL procedure. However, no PL/SQL compiler is available on the client. Therefore, the developer of the client application must distribute new versions of the application to all customers.
Oracle Database provides RPC signatures to handle remote dependencies. RPC signatures do not affect local dependencies, because recompilation is always possible in the local environment.
An RPC signature is associated with each compiled stored program unit. It identifies the unit by these characteristics:
Name
Number of parameters
Data type class of each parameter
Mode of each parameter
Data type class of return value (for a function)
An RPC signature changes only when at least one of the preceding characteristics changes.
A compiled program unit contains the RPC signature of each remote procedure that it calls (and the schema, package name, procedure name, and time stamp of the remote procedure).
In RPC-signature dependency mode, when a local program unit calls a subprogram in a remote program unit, the database ignores time-stamp mismatches and compares the RPC signature that the local unit has for the remote subprogram to the current RPC signature of the remote subprogram. If the RPC signatures match, the call succeeds; otherwise, the database returns an error to the local unit, and the local unit is invalidated.
For example, suppose that this procedure, get_emp_name, is stored on a server in Boston (BOSTON_SERVER):
CREATE OR REPLACE PROCEDURE get_emp_name ( emp_number IN NUMBER, hiredate OUT VARCHAR2, emp_name OUT VARCHAR2) AS BEGIN SELECT last_name, TO_CHAR(hire_date, 'DD-MON-YY') INTO emp_name, hiredate FROM employees WHERE employee_id = emp_number; END; /
When get_emp_name is compiled on BOSTON_SERVER, Oracle Database records both its RPC signature and its time stamp.
Suppose that this PL/SQL procedure, print_name, which calls get_emp_name, is on a server in California:
CREATE OR REPLACE PROCEDURE print_ename (emp_number IN NUMBER) AS
hiredate VARCHAR2(12);
ename VARCHAR2(10);
BEGIN
get_emp_name@BOSTON_SERVER(emp_number, hiredate, ename);
dbms_output.put_line(ename);
dbms_output.put_line(hiredate);
END;
/
When print_name is compiled on the California server, the database connects to the Boston server, sends the RPC signature of get_emp_name to the California server, and records the RPC signature of get_emp_name in the compiled state of print_ename.
At run time, when print_name calls get_emp_name, the database sends the RPC signature of get_emp_name that was recorded in the compiled state of print_ename to the Boston server. If the recorded RPC signature matches the current RPC signature of get_emp_name on the Boston server, the call succeeds; otherwise, the database returns an error to print_name, which is invalidated.
Topics:
Changing the name or default value of a subprogram parameter does not change the RPC signature of the subprogram. For example, procedure P1 has the same RPC signature in these two examples:
PROCEDURE P1 (Param1 IN NUMBER := 100); PROCEDURE P1 (Param2 IN NUMBER := 200);
However, if your application requires that callers get the new default value, you must recompile the called procedure.
Because the subprogram parameter mode IN is the default, you can specify it either implicitly or explicitly. Changing its specification from implicit to explicit, or the reverse, does not change the RPC signature of the subprogram. For example, procedure P1 has the same RPC signature in these two examples:
PROCEDURE P1 (Param1 NUMBER); -- implicit specification
PROCEDURE P1 (Param1 IN NUMBER); -- explicit specification
Changing the body of a subprogram does not change the RPC signature of the subprogram.
Example 18-4 changes only the body of the procedure get_hire_date; therefore, it does not change the RPC signature of get_hire_date.
Example 18-4 Changing Body of Procedure get_hire_date
CREATE OR REPLACE PROCEDURE get_hire_date ( emp_number IN NUMBER, hiredate OUT VARCHAR2, emp_name OUT VARCHAR2) AS BEGIN SELECT last_name, TO_CHAR(hire_date, 'DD-MON-YY') INTO emp_name, hiredate FROM employees WHERE employee_id = emp_number; END; / CREATE OR REPLACE PROCEDURE get_hire_date ( emp_number IN NUMBER, hiredate OUT VARCHAR2, emp_name OUT VARCHAR2) AS BEGIN -- Change date format model SELECT last_name, TO_CHAR(hire_date, 'DD/MON/YYYY') INTO emp_name, hiredate FROM employees WHERE employee_id = emp_number; END; /
Changing the data type of a parameter to another data type in the same class does not change the RPC signature, but changing the data type to a data type in another class does.
Table 18-3 lists the data type classes and the data types that comprise them. Data types not listed in Table 18-3, such as NCHAR, do not belong to a data type class. Changing their type always changes the RPC signature.
Table 18-3 Data Type Classes
| Data Type Class | Data Types in Class |
|---|---|
CHAR CHARACTER | |
VARCHAR VARCHAR2 STRING LONG ROWID | |
RAW LONG RAW | |
BINARY_INTEGER PLS_INTEGER SIMPLE_INTEGER BOOLEAN NATURAL NATURALN POSITIVE POSITIVEN | |
NUMBER INT INTEGER SMALLINT DEC DECIMAL REAL FLOAT NUMERIC DOUBLE PRECISION | |
DATE TIMESTAMP TIMESTAMP WITH TIME ZONE TIMESTAMP WITH LOCAL TIME ZONE INTERVAL YEAR TO MONTH INTERVAL DAY TO SECOND |
Example 18-5 changes the data type of the parameter hiredate from VARCHAR2 to DATE. VARCHAR2 and DATE are not in the same data type class, so the RPC signature of the procedure get_hire_date changes.
Example 18-5 Changing Data Type Class of get_hire_date Parameter
CREATE OR REPLACE PROCEDURE get_hire_date (
emp_number IN NUMBER,
hiredate OUT DATE,
emp_name OUT VARCHAR2) AS
BEGIN
SELECT last_name, TO_CHAR(hire_date, 'DD/MON/YYYY')
INTO emp_name, hiredate
FROM employees
WHERE employee_id = emp_number;
END;
/
Changing the name of a package type, or the names of its internal components, does not change the RPC signature of the package.
Example 18-6 defines a record type, emp_data_type, inside the package emp_package. Next, it changes the names of the record fields, but not their types. Finally, it changes the name of the type, but not its characteristics. The RPC signature of the package does not change.
Example 18-6 Changing Names of Fields in Package Record Type
CREATE OR REPLACE PACKAGE emp_package AS
TYPE emp_data_type IS RECORD (
emp_number NUMBER,
hiredate VARCHAR2(12),
emp_name VARCHAR2(10)
);
PROCEDURE get_emp_data (
emp_data IN OUT emp_data_type
);
END;
/
CREATE OR REPLACE PACKAGE emp_package AS
TYPE emp_data_type IS RECORD (
emp_num NUMBER,
hire_dat VARCHAR2(12),
empname VARCHAR2(10)
);
PROCEDURE get_emp_data (
emp_data IN OUT emp_data_type
);
END;
/
CREATE OR REPLACE PACKAGE emp_package AS
TYPE emp_data_record_type IS RECORD (
emp_num NUMBER,
hire_dat VARCHAR2(12),
empname VARCHAR2(10)
);
PROCEDURE get_emp_data (
emp_data IN OUT emp_data_record_type
);
END;
/
The dynamic initialization parameter REMOTE_DEPENDENCIES_MODE controls the dependency mode. If the initialization parameter file contains this specification, then only time stamps are used to resolve dependencies (if this is not explicitly overridden dynamically):
REMOTE_DEPENDENCIES_MODE = TIMESTAMP
If the initialization parameter file contains this parameter specification, then RPC signatures are used to resolve dependencies (if this not explicitly overridden dynamically):
REMOTE_DEPENDENCIES_MODE = SIGNATURE
You can alter the mode dynamically by using the DDL statements. For example, this example alters the dependency mode for the current session:
ALTER SESSION SET REMOTE_DEPENDENCIES_MODE = {SIGNATURE | TIMESTAMP}
This example alters the dependency mode systemwide after startup:
ALTER SYSTEM SET REMOTE_DEPENDENCIES_MODE = {SIGNATURE | TIMESTAMP}
If the REMOTE_DEPENDENCIES_MODE parameter is not specified, either in the init.ora parameter file or using the ALTER SESSION or ALTER SYSTEM statements, TIMESTAMP is the default value. Therefore, unless you explicitly use the REMOTE_DEPENDENCIES_MODE parameter, or the appropriate DDL statement, your server is operating using the time-stamp dependency mode.
When you use REMOTE_DEPENDENCIES_MODE=SIGNATURE:
If you change the initial value of a parameter of a remote procedure, then the local procedure calling the remote procedure is not invalidated. If the call to the remote procedure does not supply the parameter, then the initial value is used. In this case, because invalidation and recompilation does not automatically occur, the old initial value is used. To see the new initial values, recompile the calling procedure manually.
If you add an overloaded procedure in a package (a procedure with the same name as an existing one), then local procedures that call the remote procedure are not invalidated. If it turns out that this overloading results in a rebinding of existing calls from the local procedure under the time-stamp mode, then this rebinding does not happen under the RPC signature mode, because the local procedure does not get invalidated. You must recompile the local procedure manually to achieve the rebinding.
If the types of parameters of an existing package procedure are changed so that the new types have the same shape as the old ones, then the local calling procedure is not invalidated or recompiled automatically. You must recompile the calling procedure manually to get the semantics of the new type.
Topics:
When REMOTE_DEPENDENCIES_MODE = TIMESTAMP (the default value), dependencies among program units are handled by comparing time stamps at run time. If the time stamp of a called remote procedure does not match the time stamp of the called procedure, then the calling (dependent) unit is invalidated and must be recompiled. In this case, if there is no local PL/SQL compiler, then the calling application cannot proceed.
In the time-stamp dependency mode, RPC signatures are not compared. If there is a local PL/SQL compiler, then recompilation happens automatically when the calling procedure is run.
When REMOTE_DEPENDENCIES_MODE = SIGNATURE, the recorded time stamp in the calling unit is first compared to the current time stamp in the called remote unit. If they match, then the call proceeds. If the time stamps do not match, then the RPC signature of the called remote subprogram, as recorded in the calling subprogram, is compared with the current RPC signature of the called subprogram. If they do not match (using the criteria described in the section "Changing Data Type Classes of Parameters"), then an error is returned to the calling session.
Follow these guidelines for setting the REMOTE_DEPENDENCIES_MODE parameter:
Server-side PL/SQL users can set the parameter to TIMESTAMP (or let it default to that) to get the time-stamp dependency mode.
Server-side PL/SQL users can use RPC-signature dependency mode if they have a distributed system and they want to avoid possible unnecessary recompilations.
Client-side PL/SQL users must set the parameter to SIGNATURE. This allows:
Installation of applications at client sites without recompiling procedures.
Ability to upgrade the server, without encountering time stamp mismatches.
When using RPC signature mode on the server side, add procedures to the end of the procedure (or function) declarations in a package specification. Adding a procedure in the middle of the list of declarations can cause unnecessary invalidation and recompilation of dependent procedures.
In addition to managing dependencies among schema objects, Oracle Database also manages dependencies of each shared SQL area in the shared pool. If a table, view, synonym, or sequence is created, altered, or dropped, or a procedure or package specification is recompiled, all dependent shared SQL areas are invalidated. At a subsequent execution of the cursor that corresponds to an invalidated shared SQL area, Oracle Database reparses the SQL statement to regenerate the shared SQL area.
This topic briefly describes the new Oracle Database features that this book documents and provides links to more information.
Topics:
Edition Attribute of Database Service
Before Release 11.2.0.2, you could not specify your initial session edition when using a database service to connect to Oracle Database. If you wanted to use Edition-Based Redefinition for hot rollover, where some database clients use the pre-upgrade edition while others use the post-upgrade edition, then you had to change the client code.
As of Release 11.2.0.2, you can specify the initial session edition as an attribute of a database service, which makes it easier to ensure that each session uses the desired edition during hot rollover. For more information, see "Your Initial Session Edition".
As of Release 11.2.0.2, each *_SERVICES static data dictionary view has an EDITION column that shows the default initial session edition. For more information, see "Displaying Information About Editions, Editioning Views, and Crossedition Triggers".
The Oracle Database features for Oracle Database 11g Release 2 are:
Flashback Transaction Foreign Key Dependency Tracking
Flashback Transaction (the DBMS_FLASHBACK.TRANSACTION_BACKOUT procedure) with the CASCADE option rolls back a transaction and its dependent transactions while the database remains online.
Before Oracle Database 11g Release 2, Flashback Transaction did not track foreign key dependencies. Therefore, if you tried to use Flashback Transaction with the CASCADE option to roll back a transaction that had foreign key dependencies, you could get a foreign key violation error. The workaround was to include the foreign-key-dependent transactions in the list of transactions to roll back.
As of Oracle Database 11g Release 2, when using Flashback Transaction with the CASCADE option, you do not have to include any dependent transactions in the list of transactions to be rolled back.
Foreign key dependency tracking for Flashback Transaction requires that you enable foreign key supplemental logging. For instructions, see "Configuring Your Database for Flashback Transaction". For information about Flashback Transaction, see "Using Flashback Transaction".
Fine-Grained Invalidation for Triggers
The Oracle Database 11g Release 1 feature "Fine-Grained Invalidation" has been extended to triggers.
Edition-Based Redefinition
Edition-based redefinition enables you to upgrade the database component of an application while it is in use, thereby minimizing or eliminating down time.
To upgrade an application while it is in use, you copy the database objects that comprise the application and redefine the copied objects in isolation. Your changes do not affect users of the application—they continue to run the unchanged application. When you are sure that your changes are correct, you make the upgraded application available to all users.
Using edition-based redefinition means using one or more of its component features. The features you use, and the down time, depend on these factors:
What kind of database objects you redefine
How available the database objects must be to users while you are redefining them
Whether you make the upgraded application available to some users while others continue to use the older version of the application
You always use the edition feature to copy the database objects and redefine the copied objects in isolation.
If you change the structure of one or more tables, you also use the feature editioning views.
If other users must be able to change data in the tables while you are changing their structure, you also use forward crossedition triggers. If the pre- and post-upgrade applications will be in ordinary use at the same time (hot rollover), you also use reverse crossedition triggers. Crossedition triggers are not a permanent part of the application—you drop them when all users are using the post-upgrade application.
For more information, see Chapter 19, "Edition-Based Redefinition."
APPLYING_CROSSEDITION_TRIGGER Function
The body of a forward crossedition trigger must handle data transformation collisions. If your collision-handling strategy depends on why the trigger is running, you can determine the reason with the function APPLYING_CROSSEDITION_TRIGGER, which is defined in the package DBMS_STANDARD.
For more information, see "Handling Data Transformation Collisions".
IGNORE_ROW_ON_DUPKEY_INDEX Hint
When a statement of the form INSERT INTO target subquery runs, a unique key for some rows to be inserted might collide with existing rows. Suppose that your application must ignore such collisions and insert the rows that do not collide with existing rows.
Before Oracle Database 11g Release 2, you had to write a PL/SQL program which, in a block with a NULL handler for the DUP_VAL_ON_INDEX exception, selected the source rows and then inserted them, one at a time, into the target.
As of Oracle Database 11g Release 2, you do not have to write a PL/SQL program. You can use the IGNORE_ROW_ON_DUPKEY_INDEX hint in an INSERT statement, which is easier to write and runs much faster. This hint is especially helpful when implementing crossedition triggers.
For more information, see "Handling Data Transformation Collisions".
CHANGE_DUPKEY_ERROR_INDEX Hint
When an INSERT or UPDATE statement runs, a unique key might collide with existing rows.
Before Oracle Database 11g Release 2, the collision caused error ORA-00001. You could tell that a collision had occurred, but you could not tell where.
As of Oracle Database 11g Release 2, you can use the CHANGE_DUPKEY_ERROR_INDEX hint in an INSERT or UPDATE statement, specifying that when a unique key violation occurs for a specified index or set of columns, ORA-38911 is reported instead of ORA-00001. This hint is especially helpful when implementing crossedition triggers.
For more information, see "Handling Data Transformation Collisions".
DBMS_PARALLEL_EXECUTE Package
The DBMS_PARALLEL_EXECUTE package enables you to incrementally update the data in a large table in parallel, in two high-level steps:
Group sets of rows in the table into smaller chunks.
Apply the desired UPDATE statement to the chunks in parallel, committing each time you have finished processing a chunk.
This technique improves performance, reduces rollback space consumption, and reduces the number of row locks held. The DBMS_PARALLEL_EXECUTE package is recommended whenever you are updating a lot of data; for example, when you are applying forward crossedition triggers.
For more information, see "Transforming Data from Pre- to Post-Upgrade Representation".
Internet Protocol version 6 (IPv6) Support
Internet Protocol version 6 (IPv6) supports a much larger address space than IPv4 does. An IPv6 address has 128 bits, while an IPv4 address has only 32 bits.
Applications that use network addresses might need small changes, and recompilation, to accommodate IPv6 addresses. For more information, see "Performing Network Operations in PL/SQL Subprograms".
The agent control utility, agtctl, which starts a multithreaded extproc agent, now accepts IPv6 addresses. For more information, see "Configuration Parameters for Multithreaded extproc Agent Control".
|
See Also: Oracle Database Net Services Administrator's Guide for detailed information about IPv6 support in Oracle Database |
The application development features for Oracle Database 11g Release 1 are:
Support for XA/JTA in Oracle Real Application Clusters (Oracle RAC) Environment
Oracle Database Spawns Multithreaded extproc Agent Directly by Default
WAIT Option for Data Definition Language (DDL) Statements
DDL statements require exclusive locks on internal structures. If these locks are unavailable when a DDL statement is issued, the DDL statement fails, though it might have succeeded if it had been issued subseconds later. The WAIT option of the SQL statement LOCK TABLE enables a DDL statement to wait for its locks for a specified period before failing.
For more information, see "Choosing a Locking Strategy".
Binary XML Support for Oracle XML Database
Binary XML is a third way to represent an XML document. Binary XML complements, rather than replaces, the existing object-relational storage and CLOB storage representations. Binary XML has two significant benefits:
XML operations can be significantly optimized, with or without an XML schema is available.
The internal representation of XML is the same on disk, in memory, and on wire.
As with other storage mechanisms, the details of binary XML storage are transparent to you. You continue to use XMLType and its associated methods and operators.
For more information, see "Representing XML Data".
Metadata for SQL Operators and Functions
Metadata for SQL operators and functions is accessible through dynamic performance (V$) views. Third-party tools can leverage SQL functions without maintaining their metadata in the application layer.
For more information, see "Metadata for SQL Operators and Functions".
Enhancements to Regular Expression SQL Functions
The regular expression SQL functions REGEXP_INSTR and REGEXP_SUBSTR have increased functionality. A new regular expression SQL function, REGEXP_COUNT, returns the number of times a pattern appears in a string. These functions act the same in SQL and PL/SQL.
For more information, see "Oracle SQL Support for Regular Expressions".
Invisible Indexes
An invisible index is maintained by Oracle Database for every data manipulation language (DML) statement, but is ignored by the optimizer unless you explicitly set the parameter OPTIMIZER_USE_INVISIBLE_INDEXES to TRUE on a session or system level.
Making an index invisible is an alternative to making it unusable or dropping it. Using invisible indexes, you can:
Test the removal of an index before dropping it
Create invisible indexes temporarily for specialized, nonstandard operations, such as online application upgrades, without affecting the behavior of existing applications
For more information, see Oracle Database Administrator's Guide.
PL/SQL Function Result Cache
Before Oracle Database 11g Release 1, if you wanted your PL/SQL application to cache the results of a function, you had to design and code the cache and cache-management subprograms. If multiple sessions ran your application, each session had to have its own copy of the cache and cache-management subprograms. Sometimes each session had to perform the same expensive computations.
As of Oracle Database 11g Release 1, PL/SQL provides a function result cache. Because the function result cache is stored in a shared global area (SGA), it is available to any session that runs your application.
For more information, see "PL/SQL Function Result Cache".
Sequences in PL/SQL Expressions
The pseudocolumns CURRVAL and NEXTVAL make writing PL/SQL source code easier for you and improve runtime performance and scalability. You can use sequence_name.CURRVAL and sequence_name.NEXTVAL wherever you can use a NUMBER expression.
See Example 6-6.
PL/Scope
PL/Scope is a compiler-driven tool that collects and organizes data about user-defined identifiers from PL/SQL source code. Because PL/Scope is a compiler-driven tool, you use it through interactive development environments (such as SQL Developer and JDeveloper), rather than directly.
PL/Scope enables the development of powerful and effective PL/Scope source code browsers that increase PL/SQL developer productivity by minimizing time spent browsing and understanding source code.
For a detailed description of PL/Scope, see Chapter 7, "Using PL/Scope."
PL/SQL Hierarchical Profiler
Nonhierarchical (flat) profilers record the time that a program spends within each subprogram—the function time or self time of each subprogram. Function time is helpful, but often inadequate. For example, it is helpful to know that a program spends 40% of its time in the subprogram INSERT_ORDER, but it is more helpful to know which subprograms call INSERT_ORDER often and the total time the program spends under INSERT_ORDER (including its descendent subprograms). Hierarchical profilers provide such information.
The PL/SQL hierarchical profiler does this:
Reports the dynamic execution profile of your PL/SQL program, organized by subprogram calls
Accounts for SQL and PL/SQL execution times separately
Requires no special source or compile-time preparation
Stores results in database tables (hierarchical profiler tables) for custom report generation by integrated development environment (IDE) tools (such as SQL Developer and third-party tools)
To generate simple HTML reports from raw profiler output, you can use the plshprof command-line utility.
Each subprogram-level summary in the dynamic execution profile includes information such as:
Number of calls to the subprogram
Time spent in the subprogram itself (function time or self time)
Time spent in the subprogram itself and in its descendent subprograms (subtree time)
Detailed parent-children information, for example:
All callers of a given subprogram (parents)
All subprograms that a given subprogram called (children)
How much time was spent in subprogram x when called from y
How many calls to subprogram x were from y
You can browse the generated HTML reports in any browser. The browser's navigational capabilities, combined with well chosen links, provide a powerful way to analyze performance of large applications, improve application performance, and lower development costs.
For a detailed description of PL/SQL hierarchical profiler, see Chapter 8, "Using the PL/SQL Hierarchical Profiler."
Query Result Change Notification
Before Oracle Database 11g Release 1, Continuous Query Notification (CQN) published only object change notifications, which result from DML or DDL changes to the objects associated with registered the queries.
As of Oracle Database 11g Release 1, CQN can also publish query result change notifications, which result from DML or DDL changes to the result set associated with the registered queries. New static data dictionary views enable you to see which queries are registered for result-set-change notifications (see "Querying CQN Registrations").
For more information, see Chapter 11, "Using Continuous Query Notification (CQN)."
Flashback Transaction
The DBMS_FLASHBACK.TRANSACTION_BACKOUT procedure rolls back a transaction and its dependent transactions while the database remains online. This recovery operation uses undo data to create and run the compensating transactions that return the affected data to its original state.
For more information, see "Using Flashback Transaction".
Flashback Data Archive (Oracle Total Recall)
A Flashback Data Archive provides the ability to store and track transactional changes to a record over its lifetime. It is no longer necessary to build this intelligence into the application. A Flashback Data Archive is useful for compliance with record stage policies and audit reports.
For more information, see "Using Flashback Data Archive (Oracle Total Recall)".
XA API Available Within PL/SQL
The XA interface functionality that supports transactions involving multiple resource managers, such as databases and queues, is now available within PL/SQL. You can use PL/SQL to switch and share transactions across SQL*Plus sessions and across processes.
For more information, see "Using the DBMS_XA Package".
Support for XA/JTA in Oracle Real Application Clusters (Oracle RAC) Environment
An XA transaction now spans Oracle RAC instances by default, enabling any application that uses XA to take full advantage of the Oracle RAC environment, enhancing the availability and scalability of the application.
For more information, see "Using Oracle XA with Oracle Real Application Clusters (Oracle RAC)".
Identity Code Package
The Identity Code Package provides tools to store, retrieve, encode, decode, and translate between various product or identity codes, including Electronic Product Code (EPC), in Oracle Database. The Identity Code Package provides new data types, metadata tables and views, and PL/SQL packages for storing EPC standard RFID tags or new types of RFID tags in a user table.
The Identity Code Package enables Oracle Database to recognize EPC coding schemes, to support efficient storage and component-level retrieval of EPC data, and to meet the EPCglobal Tag Data Translation 1.0 (TDT) standard that defines how to decode, encode, and translate between various EPC RFID tag representations.
The Identity Code Package also provides an extensible framework that enables you to use pre-existing coding schemes with applications that are not included in the EPC standard and adapt Oracle Database both to these older systems and to evolving identity codes that might become part of a future EPC standard.
The Identity Code Package also lets you create your own identity codes by first registering the new encoding category, registering the new encoding type, and then registering the new components associated with each new encoding type.
For more information, see Chapter 17, "Using the Identity Code Package."
Enhanced Online Index Creation and Rebuilding
Online index creation and rebuilding no longer requires a DML-blocking lock.
Before Oracle Database 11g Release 1, online index creation and rebuilding required a very short-term DML-blocking lock at the end of the rebuilding. The DML-blocking lock could cause a spike in the number of waiting DML operations, and therefore a short drop and spike of system usage. This system usage anomaly could trigger operating system alarm levels.
Embedded PL/SQL Gateway
The PL/SQL gateway enables a user-written PL/SQL subprogram to be invoked in response to a URL with parameters derived from an HTTP request. mod_plsql is a form of the gateway that exists as a plug-in to the Oracle HTTP Server. Now the PL/SQL gateway is also embedded in the database itself. The embedded PL/SQL gateway uses the internal Oracle XML Database Listener and does not depend on the Oracle HTTP Server. You configure the embedded version of the gateway with the DBMS_EPG package.
For more information, see "Using Embedded PL/SQL Gateway".
Oracle Database Spawns Multithreaded extproc Agent Directly by Default
When an application calls an external C procedure, either Oracle Database or Oracle Listener starts the external procedure agent, extproc.
Before Oracle Database 11g Release 1, Oracle Listener spawned the multithreaded extproc agent, and you defined environment variables for extproc in the file listener.ora.
As of Oracle Database 11g Release 1, by default, Oracle Database spawns extproc directly, eliminating the risk that Oracle Listener might spawn extproc unexpectedly. This default configuration is recommended for maximum security. If you use it, you define environment variables for extproc in the file extproc.ora.
For more information, including situations in which you cannot use the default configuration, see "Loading External Procedures".
Fine-Grained Invalidation
Before Oracle Database 11g Release 1, a DDL statement that changed a referenced object invalidated all of its dependents.
As of Oracle Database 11g Release 1, a DDL statement that changes a referenced object invalidates only the dependents for which either of these statements is true:
The dependent relies on the attribute of the referenced object that the DDL statement changed.
The compiled metadata of the dependent is no longer correct for the changed referenced object.
For example, if view v selects columns c1 and c2 from table t, a DDL statement that changes only column c3 of t does not invalidate v.
For more information, see "Invalidation of Dependent Objects".
In a database application, maintaining data integrity means ensuring that the data in the tables that the application manipulates conform to the appropriate business rules. A business rule specifies a condition or relationship that must always be true or must always be false. For example, a business rule might be that no employee can have a salary over $100,000 or that every employee in the EMPLOYEES table must belong to a department in the DEPARTMENTS table. Business rules vary from company to company, because each company defines its own policies about salaries, employee numbers, inventory tracking, and so on.
As explained in Oracle Database Concepts, there are several ways to ensure data integrity, and the one to use whenever possible is the integrity constraint (or constraint).
This chapter supplements this information:
The explanation of data integrity and constraints in Oracle Database Concepts
The information about managing constraints in Oracle Database Administrator's Guide
The syntactic and semantic information about constraints in Oracle Database SQL Language Reference
|
Note: This chapter applies to only to constraints on tables. Constraints on views do not help maintain data integrity or have associated indexes. Instead, they enable query rewrites on queries involving views, thereby improving performance when using materialized views and other data warehousing features.For more information about constraints on views, see Oracle Database SQL Language Reference. For information about using constraints in data warehouses, see Oracle Database Data Warehousing Guide. |
Topics:
Enforcing Business Rules with Both Constraints and Application Code
Enforcing Referential Integrity with FOREIGN KEY Constraints
Minimizing Space and Time Overhead for Indexes Associated with Constraints
Whenever possible, enforce business rules with constraints. In addition to the advantages explained in Oracle Database Concepts, constraints have the advantage of speed: Oracle Database can check that all the data in a table obeys a constraint faster than application code can do the equivalent checking.
Example 5-1 creates a table of departments, a table of employees, a constraint to enforce the rule that all values in the department table are unique, and a constraint to enforce the rule that every employee must work for a valid department.
Example 5-1 Enforcing Business Rules with Constraints
Create table of departments:
DROP TABLE dept_tab; CREATE TABLE dept_tab ( deptname VARCHAR2(20), deptno INTEGER );
Create table of employees:
DROP TABLE emp_tab; CREATE TABLE emp_tab ( empname VARCHAR2(80), empno INTEGER, deptno INTEGER );
Create constraint to enforce rule that all values in department table are unique:
ALTER TABLE dept_tab ADD PRIMARY KEY (deptno);
Create constraint to enforce rule that every employee must work for a valid department:
ALTER TABLE emp_tab ADD FOREIGN KEY (deptno) REFERENCES dept_tab(deptno);
Now, whenever you insert an employee record into emp_tab, Oracle Database checks that its deptno value appears in dept_tab.
Suppose that instead of using a constraint to enforce the rule that every employee must work for a valid department, you use a trigger that queries dept_tab to check that it contains the deptno value of the employee record to be inserted into emp_tab. Because the query uses consistent read (CR), it might miss uncommitted changes from other transactions. For more information about using triggers to enforce business rules, see Oracle Database Concepts.
|
See Also: Oracle Database SQL Language Reference for syntactic and semantic information about constraints |
Enforcing business rules with both constraints and application code is recommended when application code can determine that data values are invalid without querying tables. The application code can provide immediate feedback to the user and reduce the load on the database by preventing attempts to insert invalid data into tables.
For Example 5-2, assume that Example 5-1 was run and then this column was added to the table emp_tab:
empgender VARCHAR2(1)
The only valid values for empgender are 'M' and 'F'. When someone tries to insert a row into emp_tab or update the value of emp_tab.empgender, application code can determine whether the new value for emp_tab.empgender is valid without querying a table. If the value is invalid, the application code can notify the user instead of trying to insert the invalid value, as in Example 5-2.
Example 5-2 Enforcing Business Rules with Both Constraints and Application Code
CREATE OR REPLACE PROCEDURE add_employee ( e_name emp_tab.empname%TYPE, e_gender emp_tab.empgender%TYPE, e_number emp_tab.empno%TYPE, e_dept emp_tab.deptno%TYPE ) AUTHID DEFINER IS BEGIN IF UPPER(e_gender) IN ('M','F') THEN INSERT INTO emp_tab VALUES (e_name, e_gender, e_number, e_dept); ELSE DBMS_OUTPUT.PUT_LINE('Gender must be M or F.'); END IF; END; / BEGIN add_employee ('Smith', 'H', 356, 20); END; /
Result:
Gender must be M or F.
When a unique or primary key constraint is enabled, Oracle Database creates an index automatically, but Oracle recommends that you create these indexes explicitly. If you want to use an index with a foreign key constraint, then you must create the index explicitly. For information about creating indexes explicitly, see Oracle Database Administrator's Guide or Oracle Database SQL Language Reference.
When a constraint can use an existing index, Oracle Database does not create an index for that constraint. Note that:
A unique or primary key constraint can use either a unique index, an entire nonunique index, or the first few columns of a nonunique index.
If a unique or primary key constraint uses a nonunique index, then no other unique or primary key constraint can use that nonunique index.
The column order in the constraint and index need not match.
The object number of the index used by a unique or primary key constraint is stored in CDEF$.ENABLED for that constraint. No static data dictionary view or dynamic performance view shows this information.
If an enabled unique or primary key constraint is using an index, you cannot drop only the index. To drop the index, you must either drop the constraint itself or disable the constraint and then drop the index. For information about disabling and dropping constraints, see Oracle Database Administrator's Guide.
|
See Also:
|
By default, a column can contain a NULL value. To ensure that the column never contains a NULL value, use the NOT NULL constraint (described in Oracle Database SQL Language Reference).
Use a NOT NULL constraint in both of these situations:
A column must contain a non-NULL value.
For example, in the table HR.EMPLOYEES, each employee must have an employee ID. Therefore, the column HR.EMPLOYEES.EMPLOYEE_ID has a NOT NULL constraint, and nobody can insert a new employee record into HR.EMPLOYEES without specifying a non-NULL value for EMPLOYEE_ID. You can insert a new employee record into HR.EMPLOYEES without specifying a salary; therefore, the column HR.EMPLOYEES.SALARY does not have a NOT NULL constraint.
You want to allow index scans of the table, or allow an operation that requires indexing all rows.
Oracle Database indexes do not store keys whose values are all NULL. Therefore, for the preceding kinds of operations, at least one indexed column must have a NOT NULL constraint.
Example 5-3 uses the SQL*Plus command DESCRIBE to show which columns of the DEPARTMENTS table have NOT NULL constraints, and then shows what happens if you try to insert NULL values in columns that have NOT NULL constraints.
Example 5-3 Inserting NULL Values into Columns with NOT NULL Constraints
DESCRIBE DEPARTMENTS;
Result:
Name Null? Type ----------------------------------------- -------- ------------ DEPARTMENT_ID NOT NULL NUMBER(4) DEPARTMENT_NAME NOT NULL VARCHAR2(30) MANAGER_ID NUMBER(6) LOCATION_ID NUMBER(4)
Try to insert NULL into DEPARTMENT_ID column:
INSERT INTO DEPARTMENTS ( DEPARTMENT_ID, DEPARTMENT_NAME, MANAGER_ID, LOCATION_ID ) VALUES (NULL, 'Sales', 200, 1700);
Result:
VALUES (NULL, 'Sales', 200, 1700)
*
ERROR at line 4:
ORA-01400: cannot insert NULL into ("HR"."DEPARTMENTS"."DEPARTMENT_ID")
Omitting a value for a column that cannot be NULL is the same as assigning it the value NULL:
INSERT INTO DEPARTMENTS (
DEPARTMENT_NAME, MANAGER_ID, LOCATION_ID
)
VALUES ('Sales', 200, 1700);
Result:
INSERT INTO DEPARTMENTS (
*
ERROR at line 1:
ORA-01400: cannot insert NULL into ("HR"."DEPARTMENTS"."DEPARTMENT_ID")
You can prevent the preceding error by giving DEPARTMENT_ID a non-NULL default value. For more information, see "When to Use Default Column Values".
You can combine NOT NULL constraints with other constraints to further restrict the values allowed in specific columns. For example, the combination of NOT NULL and UNIQUE constraints forces the input of values in the UNIQUE key, eliminating the possibility that data in a new conflicts with data in an existing row. For more information, see "UNIQUE and NOT NULL Constraints on the Foreign Key".
When an INSERT statement (described in Oracle Database SQL Language Reference) does not specify a value for a specific column, that column receives its default value. By default, that default value is NULL. You can change the default value when you define the column (with the CREATE TABLE statement, described in Oracle Database SQL Language Reference) or when you alter the column (with the ALTER TABLE statement, described in Oracle Database SQL Language Reference).
|
Note: Giving a column a non-NULL default value does not ensure that the value of the column will never have the value NULL, as the NOT NULL constraint does. For information about the NOT NULL constraint, see "When to Use NOT NULL Constraints". |
Use a default column value in these situations:
The column has a NOT NULL constraint.
Giving the column a non-NULL default value prevents the error that would occur if someone inserted a row without specifying a value for the column.
There is a most common value for the column.
For example, if most departments in the company are in New York, then set the default value of the column DEPARTMENTS.LOCATION to 'NEW YORK'.
There is a non-NULL value that signifies no entry.
For example, if the value zero in the column EMPLOYEES.SALARY means that the salary has not yet been determined, then set the default value of that column to zero.
A default column value that signifies no entry can simplify testing. For example, it lets you change this test:
IF (employees.salary IS NOT NULL) AND (employees.salary < 50000)
To this test:
IF employees.salary < 50000
You want to automatically record the names of users who modify a table.
For example, suppose that you allow users to insert rows into a table through a view. You give the base table a column named inserter (which need not be included in the definition of the view), to store the name of the user who inserted the row. To record the user name automatically, define a default value that invokes the USER function. For example:
CREATE TABLE audit_trail (
value1 NUMBER,
value2 VARCHAR2(32),
inserter VARCHAR2(30) DEFAULT USER);
The primary key of a table uniquely identifies each row and ensures that no duplicate rows exist (and typically, this is its only purpose). Therefore, a primary key value cannot be NULL.
A table can have at most one primary key, but that key can have multiple columns (that is, it can be a composite key). To designate a primary key, use the PRIMARY KEY constraint.
Whenever practical, choose as the primary key a single column whose values are generated by a sequence. For information about sequences, see Oracle Database SQL Language Reference.
The second-best choice for a primary key is a single column whose values are all of the following:
Unique
Never changed
Never NULL
Short and numeric (and therefore easy to type)
Minimize your use of composite primary keys, whose values are long and cannot be generated by a sequence.
|
See Also:
|
Use a UNIQUE constraint (which designates a unique key) on any column or combination of columns (except the primary key) where duplicate non-NULL values are not allowed. For example:
| Unique Key | Primary Key |
|---|---|
| Employee Social Security Number | Employee number |
| Truck license plate number | Truck number |
| Customer phone number (country code column, area code column, and local phone number column) | Customer number |
| Department name column and location column | Department number |
Figure 5-1 shows a table with a UNIQUE constraint, a row that violates the constraint, and a row that satisfies it.
Figure 5-1 Rows That Violate and Satisfy a UNIQUE Constraint
|
See Also:
|
When two tables share one or more columns, you use can use a FOREIGN KEY constraint to enforce referential integrity—that is, to ensure that the shared columns always have the same values in both tables.
|
Note: AFOREIGN KEY constraint is also called a referential integrity constraint, and its CONSTRAINT_TYPE is R in the static data dictionary views *_CONSTRAINTS. |
Designate one table as the referenced or parent table and the other as the dependent or child table. In the parent table, define either a PRIMARY KEY or UNIQUE constraint on the shared columns. In the child table, define a FOREIGN KEY constraint on the shared columns. The shared columns now comprise a foreign key. Defining additional constraints on the foreign key affects the parent-child relationship—for details, see "Defining Relationships Between Parent and Child Tables".
Figure 5-2 shows a foreign key defined on the department number. It guarantees that every value in this column must match a value in the primary key of the department table. This constraint prevents erroneous department numbers from getting into the employee table.
Figure 5-2 shows parent and child tables that share one column, a row that violates the FOREIGN KEY constraint, and a row that satisfies it.
Figure 5-2 Rows That Violate and Satisfy a FOREIGN KEY Constraint
Topics:
|
See Also:
|
Foreign keys allow key values that are all NULL, even if there are no matching PRIMARY or UNIQUE keys.
By default (without any NOT NULL or CHECK clauses), the FOREIGN KEY constraint enforces the match none rule for composite foreign keys in the ANSI/ISO standard.
To enforce the match full rule for NULL values in composite foreign keys, which requires that all components of the key be NULL or all be non-null, define a CHECK constraint that allows only all nulls or all non-nulls in the composite foreign key. For example, with a composite key comprised of columns A, B, and C:
CHECK ((A IS NULL AND B IS NULL AND C IS NULL) OR
(A IS NOT NULL AND B IS NOT NULL AND C IS NOT NULL))
In general, it is not possible to use declarative referential integrity to enforce the match partial rule for NULL values in composite foreign keys, which requires the non-null portions of the key to appear in the corresponding portions in the primary or unique key of a single row in the referenced table. You can often use triggers to handle this case, as described in Oracle Database PL/SQL Language Reference.
Several relationships between parent and child tables can be determined by the other types of constraints defined on the foreign key in the child table.
No Constraints on the Foreign Key When no other constraints are defined on the foreign key, any number of rows in the child table can reference the same parent key value. This model allows nulls in the foreign key.
This model establishes a one-to-many relationship between the parent and foreign keys that allows undetermined values (nulls) in the foreign key. An example of such a relationship is shown in Figure 5-2 between the employee and department tables. Each department (parent key) has many employees (foreign key), and some employees might not be in a department (nulls in the foreign key).
NOT NULL Constraint on the Foreign Key When nulls are not allowed in a foreign key, each row in the child table must explicitly reference a value in the parent key because nulls are not allowed in the foreign key.
Any number of rows in the child table can reference the same parent key value, so this model establishes a one-to-many relationship between the parent and foreign keys. However, each row in the child table must have a reference to a parent key value; the absence of a value (a null) in the foreign key is not allowed. The same example in the previous section illustrates such a relationship. However, in this case, employees must have a reference to a specific department.
UNIQUE Constraint on the Foreign Key When a UNIQUE constraint is defined on the foreign key, only one row in the child table can reference a given parent key value. This model allows nulls in the foreign key.
This model establishes a one-to-one relationship between the parent and foreign keys that allows undetermined values (nulls) in the foreign key. For example, assume that the employee table had a column named MEMBERNO, referring to an employee membership number in the company insurance plan. Also, a table named INSURANCE has a primary key named MEMBERNO, and other columns of the table keep respective information relating to an employee insurance policy. The MEMBERNO in the employee table must be both a foreign key and a unique key:
To enforce referential integrity rules between the EMP_TAB and INSURANCE tables (the FOREIGN KEY constraint)
To guarantee that each employee has a unique membership number (the UNIQUE key constraint)
UNIQUE and NOT NULL Constraints on the Foreign Key When both UNIQUE and NOT NULL constraints are defined on the foreign key, only one row in the child table can reference a given parent key value, and because NULL values are not allowed in the foreign key, each row in the child table must explicitly reference a value in the parent key.
This model establishes a one-to-one relationship between the parent and foreign keys that does not allow undetermined values (nulls) in the foreign key. If you expand the previous example by adding a NOT NULL constraint on the MEMBERNO column of the employee table, in addition to guaranteeing that each employee has a unique membership number, you also ensure that no undetermined values (nulls) are allowed in the MEMBERNO column of the employee table.
Oracle Database allows a column to be referenced by multiple FOREIGN KEY constraints; there is no limit on the number of dependent keys. This situation might be present if a single column is part of two different composite foreign keys.
When Oracle Database checks a constraint, it signals an error if the constraint is not satisfied. To defer checking constraints until the end of the current transaction, use the SET CONSTRAINTS statement.
|
Note: You cannot use theSET CONSTRAINTS statement inside a trigger. |
When deferring constraint checks:
Select appropriate data.
You might want to defer constraint checks on UNIQUE and FOREIGN keys if the data you are working with has any of these characteristics:
Tables are snapshots.
Some tables contain a large amount of data being manipulated by another application, which might not return the data in the same order.
Update cascade operations on foreign keys.
Ensure that constraints are deferrable.
After identifying the appropriate tables, ensure that their FOREIGN, UNIQUE and PRIMARY key constraints are created DEFERRABLE.
Within the application that manipulates the data, set all constraints deferred before you begin processing any data, as follows:
SET CONSTRAINTS ALL DEFERRED;
(Optional) Check for constraint violations immediately before committing the transaction.
Immediately before the COMMIT statement, run the SET CONSTRAINTS ALL IMMEDIATE statement. If there are any problems with a constraint, this statement fails, and identifies the constraint that caused the error. If you commit while constraints are violated, the transaction rolls back and you get an error message.
In Example 5-4, the PRIMARY and FOREIGN keys of the table emp are created DEFERRABLE and then deferred.
Example 5-4 Deferring Constraint Checks
DROP TABLE dept; CREATE TABLE dept ( deptno NUMBER PRIMARY KEY, dname VARCHAR2 (30) ); DROP TABLE emp; CREATE TABLE emp ( empno NUMBER, ename VARCHAR2(30), deptno NUMBER, CONSTRAINT pk_emp_empno PRIMARY KEY (empno) DEFERRABLE, CONSTRAINT fk_emp_deptno FOREIGN KEY (deptno) REFERENCES dept(deptno) DEFERRABLE ); INSERT INTO dept (deptno, dname) VALUES (10, 'Accounting'); INSERT INTO dept (deptno, dname) VALUES (20, 'SALES'); INSERT INTO emp (empno, ename, deptno) VALUES (1, 'Corleone', 10); INSERT INTO emp (empno, ename, deptno) VALUES (2, 'Costanza', 20); COMMIT; SET CONSTRAINTS ALL DEFERRED; UPDATE dept SET deptno = deptno + 10 WHERE deptno = 20;
Query:
SELECT * from dept ORDER BY deptno;
Result:
DEPTNO DNAME
---------- ------------------------------
10 Accounting
30 SALES
2 rows selected.
Update:
UPDATE emp SET deptno = deptno + 10 WHERE deptno = 20;
Result:
1 row updated.
Query:
SELECT * from emp ORDER BY deptno;
Result:
EMPNO ENAME DEPTNO
---------- ------------------------------ ----------
1 Corleone 10
2 Costanza 30
2 rows selected.
The SET CONSTRAINTS applies only to the current transaction, and its setting lasts for the duration of the transaction, or until another SET CONSTRAINTS statement resets the mode. The ALTER SESSION SET CONSTRAINTS statement applies only for the current session. The defaults specified when you create a constraint remain while the constraint exists.
|
See Also: Oracle Database SQL Language Reference for more information about theSET CONSTRAINTS statement |
When you create a UNIQUE or PRIMARY key, Oracle Database checks to see if an existing index enforces uniqueness for the constraint. If there is no such index, the database creates one.
When Oracle Database uses a unique index to enforce a constraint, and constraints associated with the unique index are dropped or disabled, the index is dropped. To preserve the statistics associated with the index (which would take a long time to re-create), specify the KEEP INDEX clause on the DROP CONSTRAINT statement.
While enabled foreign keys reference a PRIMARY or UNIQUE key, you cannot disable or drop the PRIMARY or UNIQUE key constraint or the index.
|
Note: UNIQUE and PRIMARY keys with deferrable constraints must all use nonunique indexes. |
To use existing indexes when creating unique and primary key constraints, include USING INDEX in the CONSTRAINT clause. For details and examples, see Oracle Database SQL Language Reference.
Index foreign keys unless the matching unique or primary key is never updated or deleted.
The declaration of a referential constraint cannot specify a foreign key that references a primary or unique key of a remote table.
However, you can maintain parent/child table relationships across nodes using triggers.
|
See Also: Oracle Database PL/SQL Language Reference for more information about triggers that enforce referential integrity |
|
Note: If you decide to define referential integrity across the nodes of a distributed database using triggers, be aware that network failures can make both the parent table and the child table inaccessible.For example, assume that the child table is in the If the network connection between the two databases fails, then some data manipulation language (DML) statements against the child table (those that insert rows or update a foreign key value) cannot proceed, because the referential integrity triggers must have access to the parent table in the |
Use CHECK constraints when you must enforce integrity rules based on logical expressions, such as comparisons. Never use CHECK constraints when any of the other types of constraints can provide the necessary checking.
Examples of CHECK constraints include:
A CHECK constraint on employee salaries so that no salary value is greater than 10000.
A CHECK constraint on department locations so that only the locations "BOSTON", "NEW YORK", and "DALLAS" are allowed.
A CHECK constraint on the salary and commissions columns to prevent the commission from being larger than the salary.
A CHECK constraint requires that a condition be true or unknown for every row of the table. If a statement causes the condition to evaluate to false, then the statement is rolled back. The condition of a CHECK constraint has these limitations:
The condition must be a boolean expression that can be evaluated using the values in the row being inserted or updated.
The condition cannot contain subqueries or sequences.
The condition cannot include the SYSDATE, UID, USER, or USERENV SQL functions.
The condition cannot contain the pseudocolumns LEVEL or ROWNUM.
The condition cannot contain the PRIOR operator.
The condition cannot contain a user-defined function.
|
See Also:
|
When using CHECK constraints, remember that a CHECK constraint is violated only if the condition evaluates to false; true and unknown values (such as comparisons with nulls) do not violate a check condition. Ensure that any CHECK constraint that you define is specific enough to enforce the rule.
For example, consider this CHECK constraint:
CHECK (Sal > 0 OR Comm >= 0)
At first glance, this rule may be interpreted as "do not allow a row in the employee table unless the employee salary is greater than zero or the employee commission is greater than or equal to zero." But if a row is inserted with a null salary, that row does not violate the CHECK constraint, regardless of whether the commission value is valid, because the entire check condition is evaluated as unknown. In this case, you can prevent such violations by placing NOT NULL constraints on both the SAL and COMM columns.
|
Note: If you are not sure when unknown values result inNULL conditions, review the truth tables for the logical conditions in Oracle Database SQL Language Reference |
A single column can have multiple CHECK constraints that reference the column in its definition. There is no limit to the number of CHECK constraints that can be defined that reference a column.
The order in which the constraints are evaluated is not defined, so be careful not to rely on the order or to define multiple constraints that conflict with each other.
According to the ANSI/ISO standard, a NOT NULL constraint is an example of a CHECK constraint, where the condition is:
CHECK (column_name IS NOT NULL)
Therefore, you can write NOT NULL constraints for a single column using either a NOT NULL constraint or a CHECK constraint. The NOT NULL constraint is easier to use than the CHECK constraint.
In the case where a composite key can allow only all nulls or all values, you must use a CHECK constraint. For example, this CHECK constraint allows a key value in the composite key made up of columns C1 and C2 to contain either all nulls or all values:
CHECK ((C1 IS NULL AND C2 IS NULL) OR (C1 IS NOT NULL AND C2 IS NOT NULL))
Example 5-5 and Example 5-6 show how to create simple constraints during the prototype phase of your database design. In these examples, each constraint is given a name. Naming the constraints prevents the database from creating multiple copies of the same constraint, with different system-generated names, if the data definition language (DDL) statement runs multiple times.
Example 5-5 creates tables and their constraints at the same time, using the CREATE TABLE statement.
Example 5-5 Defining Constraints with the CREATE TABLE Statement
DROP TABLE DeptTab; CREATE TABLE DeptTab ( Deptno NUMBER(3) CONSTRAINT pk_DeptTab_Deptno PRIMARY KEY, Dname VARCHAR2(15), Loc VARCHAR2(15), CONSTRAINT u_DeptTab_Dname_Loc UNIQUE (Dname, Loc), CONSTRAINT c_DeptTab_Loc CHECK (Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO'))); DROP TABLE EmpTab; CREATE TABLE EmpTab ( Empno NUMBER(5) CONSTRAINT pk_EmpTab_Empno PRIMARY KEY, Ename VARCHAR2(15) NOT NULL, Job VARCHAR2(10), Mgr NUMBER(5) CONSTRAINT r_EmpTab_Mgr REFERENCES EmpTab, Hiredate DATE, Sal NUMBER(7,2), Comm NUMBER(5,2), Deptno NUMBER(3) NOT NULL CONSTRAINT r_EmpTab_DeptTab REFERENCES DeptTab ON DELETE CASCADE);
Example 5-6 creates constraints for existing tables, using the ALTER TABLE statement.
You cannot create a validated constraint on a table if the table contains rows that violate the constraint.
Example 5-6 Defining Constraints with the ALTER TABLE Statement
-- Create tables without constraints: DROP TABLE DeptTab; CREATE TABLE DeptTab ( Deptno NUMBER(3), Dname VARCHAR2(15), Loc VARCHAR2(15) ); DROP TABLE EmpTab; CREATE TABLE EmpTab ( Empno NUMBER(5), Ename VARCHAR2(15), Job VARCHAR2(10), Mgr NUMBER(5), Hiredate DATE, Sal NUMBER(7,2), Comm NUMBER(5,2), Deptno NUMBER(3) ); --Define constraints with the ALTER TABLE statement: ALTER TABLE DeptTab ADD CONSTRAINT pk_DeptTab_Deptno PRIMARY KEY (Deptno); ALTER TABLE EmpTab ADD CONSTRAINT fk_DeptTab_Deptno FOREIGN KEY (Deptno) REFERENCES DeptTab; ALTER TABLE EmpTab MODIFY (Ename VARCHAR2(15) NOT NULL);
|
See Also: Oracle Database Administrator's Guide for information about creating and maintaining constraints for a large production database |
The creator of a constraint must have the ability to create tables (the CREATE TABLE or CREATE ANY TABLE system privilege), or the ability to alter the table (the ALTER object privilege for the table or the ALTER ANY TABLE system privilege) with the constraint. Additionally, UNIQUE and PRIMARY KEY constraints require that the owner of the table have either a quota for the tablespace that contains the associated index or the UNLIMITED TABLESPACE system privilege. FOREIGN KEY constraints also require some additional privileges.
Assign names to constraints NOT NULL, UNIQUE, PRIMARY KEY, FOREIGN KEY, and CHECK using the CONSTRAINT option of the constraint clause. This name must be unique among the constraints that you own. If you do not specify a constraint name, one is assigned automatically by Oracle Database.
Choosing your own name makes error messages for constraint violations more understandable, and prevents the creation of duplicate constraints with different names if the SQL statements are run more than once.
See the previous examples of the CREATE TABLE and ALTER TABLE statements for examples of the CONSTRAINT option of the constraint clause. The name of each constraint is included with other information about the constraint in the data dictionary.
This section explains the mechanisms and procedures for manually enabling and disabling constraints.
enabled constraint. When a constraint is enabled, the corresponding rule is enforced on the data values in the associated columns. The definition of the constraint is stored in the data dictionary.
disabled constraint. When a constraint is disabled, the corresponding rule is not enforced. The definition of the constraint is still stored in the data dictionary.
An integrity constraint represents an assertion about the data in a database. This assertion is always true when the constraint is enabled. The assertion might not be true when the constraint is disabled, because data that violates the integrity constraint can be in the database.
Topics:
During day-to-day operations, keep constraints enabled. In certain situations, temporarily disabling the constraints of a table makes sense for performance reasons. For example:
When loading large amounts of data into a table using SQL*Loader
When performing batch operations that make massive changes to a table (such as changing each employee number by adding 1000 to the existing number)
When importing or exporting one table at a time
Temporarily turning off constraints can speed up these operations.
When you define an integrity constraint (using either CREATE TABLE or ALTER TABLE), Oracle Database enables the constraint by default. For code clarity, you can explicitly enable the constraint by including the ENABLE clause in its definition, as in Example 5-7.
Example 5-7 Creating Enabled Constraints
/* Use CREATE TABLE statement to create enabled constraint (ENABLE keyword is optional): */ DROP TABLE t1; CREATE TABLE t1 (Empno NUMBER(5) PRIMARY KEY ENABLE); /* Create table without constraint and then use ALTER TABLE statement to add enabled constraint (ENABLE keyword is optional): */ DROP TABLE t2; CREATE TABLE t2 (Empno NUMBER(5)); ALTER TABLE t2 ADD PRIMARY KEY (Empno) ENABLE;
Include the ENABLE clause when defining a constraint for a table to be populated a row at a time by individual transactions. This ensures that data is always consistent, and reduces the performance overhead of each DML statement.
An ALTER TABLE statement that tries to enable an integrity constraint fails if an existing row of the table violates the integrity constraint. The statement rolls back and the constraint definition is neither stored nor enabled.
You define and disable an integrity constraint (using either CREATE TABLE or ALTER TABLE), by including the DISABLE clause in its definition, as in Example 5-8.
Example 5-8 Creating Disabled Constraints
/* Use CREATE TABLE statement to create disabled constraint */ DROP TABLE t1; CREATE TABLE t1 (Empno NUMBER(5) PRIMARY KEY DISABLE); /* Create table without constraint and then use ALTER TABLE statement to add disabled constraint */ DROP TABLE t2; CREATE TABLE t2 (Empno NUMBER(5)); ALTER TABLE t2 ADD PRIMARY KEY (Empno) DISABLE;
Include the DISABLE clause when defining a constraint for a table to have large amounts of data inserted before anybody else accesses it, particularly if you must cleanse data after inserting it, or must fill empty columns with sequence numbers or parent/child relationships.
An ALTER TABLE statement that defines and disables a constraint never fails, because its rule is not enforced.
After you have cleansed the data and filled the empty columns, you can enable constraints that were disabled during data insertion.
To enable an existing constraint, use the ALTER TABLE statement with the ENABLE clause, as in Example 5-9.
Example 5-9 Enabling Existing Constraints
-- Create table with disabled constraints:
DROP TABLE DeptTab;
CREATE TABLE DeptTab (
Deptno NUMBER(3) PRIMARY KEY DISABLE,
Dname VARCHAR2(15),
Loc VARCHAR2(15),
CONSTRAINT uk_DeptTab_Dname_Loc UNIQUE (Dname, Loc) DISABLE,
CONSTRAINT c_DeptTab_Loc
CHECK (Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO')) DISABLE
);
-- Enable constraints:
ALTER TABLE DeptTab
ENABLE PRIMARY KEY
ENABLE CONSTRAINT uk_DeptTab_Dname_Loc
ENABLE CONSTRAINT c_DeptTab_Loc;
An ALTER TABLE statement that attempts to enable an integrity constraint fails if any of the table rows violate the integrity constraint. The statement is rolled back and the constraint is not enabled.
If you must perform a large insert or update when a table contains data, you can temporarily disable constraints to improve performance of the bulk operation.
To disable an existing constraint, use the ALTER TABLE statement with the DISABLE clause, as in Example 5-10.
Example 5-10 Disabling Existing Constraints
-- Create table with enabled constraints:
DROP TABLE DeptTab;
CREATE TABLE DeptTab (
Deptno NUMBER(3) PRIMARY KEY ENABLE,
Dname VARCHAR2(15),
Loc VARCHAR2(15),
CONSTRAINT uk_DeptTab_Dname_Loc UNIQUE (Dname, Loc) ENABLE,
CONSTRAINT c_DeptTab_Loc
CHECK (Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO')) ENABLE
);
-- Disable constraints:
ALTER TABLE DeptTab
DISABLE PRIMARY KEY
DISABLE CONSTRAINT uk_DeptTab_Dname_Loc
DISABLE CONSTRAINT c_DeptTab_Loc;
When enabling or disabling UNIQUE, PRIMARY KEY, and FOREIGN KEY constraints, be aware of several important issues and prerequisites. UNIQUE key and PRIMARY KEY constraints are usually managed by the database administrator.
If a row of a table disobeys an integrity constraint, then this row is in violation of the constraint and is called an exception to the constraint. If any exceptions exist, then the constraint cannot be enabled. The rows that violate the constraint must be updated or deleted before the constraint can be enabled.
You can identify exceptions for a specific integrity constraint as you try to enable the constraint.
When you try to create or enable a constraint, and the statement fails because integrity constraint exceptions exist, the statement is rolled back. You cannot enable the constraint until all exceptions are either updated or deleted. To determine which rows violate the integrity constraint, include the EXCEPTIONS option in the ENABLE clause of a CREATE TABLE or ALTER TABLE statement.
|
See Also: Oracle Database Administrator's Guide for more information about responding to constraint exceptions |
Starting with Oracle8i, you can modify an existing constraint with the MODIFY CONSTRAINT clause, as in Example 5-11.
|
See Also: Oracle Database SQL Language Reference for information about the parameters you can modify |
Example 5-11 Modifying Constraints
/* Create & then modify a CHECK constraint: */ DROP TABLE X1Tab; CREATE TABLE X1Tab ( a1 NUMBER CONSTRAINT c_X1Tab_a1 CHECK (a1>3) DEFERRABLE DISABLE ); ALTER TABLE X1Tab MODIFY CONSTRAINT c_X1Tab_a1 ENABLE; ALTER TABLE X1Tab MODIFY CONSTRAINT c_X1Tab_a1 RELY; ALTER TABLE X1Tab MODIFY CONSTRAINT c_X1Tab_a1 INITIALLY DEFERRED; ALTER TABLE X1Tab MODIFY CONSTRAINT c_X1Tab_a1 ENABLE NOVALIDATE; /* Create & then modify a PRIMARY KEY constraint: */ DROP TABLE t1; CREATE TABLE t1 (a1 INT, b1 INT); ALTER TABLE t1 ADD CONSTRAINT pk_t1_a1 PRIMARY KEY(a1) DISABLE; ALTER TABLE t1 MODIFY PRIMARY KEY INITIALLY IMMEDIATE USING INDEX PCTFREE = 30 ENABLE NOVALIDATE; ALTER TABLE t1 MODIFY PRIMARY KEY ENABLE NOVALIDATE;
One property of a constraint that you can modify is its name. Situations in which you would rename a constraint include:
You want to clone a table and its constraints.
Constraint names must be unique, even across multiple schemas. Therefore, the constraints in the original table cannot have the same names as those in the cloned table.
You created a constraint with a default system-generated name, and now you want to give it a name that is easy to remember, so that you can easily enable and disable it.
Example 5-12 shows how to find the system-generated name of a constraint and change it.
Example 5-12 Renaming a Constraint
DROP TABLE T; CREATE TABLE T ( C1 NUMBER PRIMARY KEY, C2 NUMBER );
Query:
SELECT CONSTRAINT_NAME FROM USER_CONSTRAINTS WHERE TABLE_NAME = 'T' AND CONSTRAINT_TYPE = 'P';
Result (system-generated name of constraint name varies):
CONSTRAINT_NAME
------------------------------
SYS_C0013059
1 row selected.
Rename constraint from name reported in preceding query to T_C1_PK:
ALTER TABLE T RENAME CONSTRAINT SYS_C0013059 TO T_C1_PK;
Query:
SELECT CONSTRAINT_NAME FROM USER_CONSTRAINTS WHERE TABLE_NAME = 'T' AND CONSTRAINT_TYPE = 'P';
Result:
CONSTRAINT_NAME ------------------------------ T_C1_PK 1 row selected.
You can drop a constraint using the DROP clause of the ALTER TABLE statement. Situations in which you would drop a constraint include:
The constraint enforces a rule that is no longer true.
The constraint is no longer needed.
To drop a constraint and all other integrity constraints that depend on it, specify CASCADE.
Example 5-13 Dropping Constraints
-- Create table with constraints:
DROP TABLE DeptTab;
CREATE TABLE DeptTab (
Deptno NUMBER(3) PRIMARY KEY,
Dname VARCHAR2(15),
Loc VARCHAR2(15),
CONSTRAINT uk_DeptTab_Dname_Loc UNIQUE (Dname, Loc),
CONSTRAINT c_DeptTab_Loc
CHECK (Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO'))
);
-- Drop constraints:
ALTER TABLE DeptTab
DROP PRIMARY KEY
DROP CONSTRAINT uk_DeptTab_Dname_Loc
DROP CONSTRAINT c_DeptTab_Loc;
When dropping UNIQUE, PRIMARY KEY, and FOREIGN KEY constraints, be aware of several important issues and prerequisites. UNIQUE and PRIMARY KEY constraints are usually managed by the database administrator.
|
See Also:
|
FOREIGN KEY constraints enforce relationships between columns in different tables. Therefore, they cannot be enabled if the constraint of the referenced primary or unique key is not present or not enabled.
You must use the same data type for corresponding columns in the dependent and referenced tables. The column names need not match.
Because foreign keys reference primary and unique keys of the parent table, and PRIMARY KEY and UNIQUE key constraints are enforced using indexes, composite foreign keys are limited to 32 columns.
If the column list is not included in the REFERENCES option when defining a FOREIGN KEY constraint (single column or composite), then Oracle Database assumes that you intend to reference the primary key of the specified table. Alternatively, you can explicitly specify the column(s) to reference in the parent table within parentheses. Oracle Database automatically checks to verify that this column list references a primary or unique key of the parent table. If it does not, then an informative error is returned.
To create a FOREIGN KEY constraint, the creator of the constraint must have privileged access to the parent and child tables.
Parent Table The creator of the referential integrity constraint must own the parent table or have REFERENCES object privileges on the columns that constitute the parent key of the parent table.
Child Table The creator of the referential integrity constraint must have the ability to create tables (that is, the CREATE TABLE or CREATE ANY TABLE system privilege) or the ability to alter the child table (that is, the ALTER object privilege for the child table or the ALTER ANY TABLE system privilege).
In both cases, necessary privileges cannot be obtained through a role; they must be explicitly granted to the creator of the constraint.
These restrictions allow:
The owner of the child table to explicitly decide which constraints are enforced and which other users can create constraints
The owner of the parent table to explicitly decide if foreign keys can depend on the primary and unique keys in her tables
Oracle Database allows different types of referential integrity actions to be enforced, as specified with the definition of a FOREIGN KEY constraint:
Prevent Delete or Update of Parent Key The default setting prevents the deletion or update of a parent key if there is a row in the child table that references the key. For example:
CREATE TABLE Emp_tab ( FOREIGN KEY (Deptno) REFERENCES Dept_tab);
Delete Child Rows When Parent Key Deleted The ON DELETE CASCADE action allows parent key data that is referenced from the child table to be deleted, but not updated. When data in the parent key is deleted, all rows in the child table that depend on the deleted parent key values are also deleted. To specify this referential action, include the ON DELETE CASCADE option in the definition of the FOREIGN KEY constraint. For example:
CREATE TABLE Emp_tab ( FOREIGN KEY (Deptno) REFERENCES Dept_tab ON DELETE CASCADE);
Set Foreign Keys to Null When Parent Key Deleted The ON DELETE SET NULL action allows data that references the parent key to be deleted, but not updated. When referenced data in the parent key is deleted, all rows in the child table that depend on those parent key values have their foreign keys set to null. To specify this referential action, include the ON DELETE SET NULL option in the definition of the FOREIGN KEY constraint. For example:
CREATE TABLE Emp_tab ( FOREIGN KEY (Deptno) REFERENCES Dept_tab ON DELETE SET NULL);
To find the names of constraints, what columns they affect, and other information to help you manage them, query the static data dictionary views *_CONSTRAINTS and *_CONS_COLUMNS, as in Example 5-14.
Example 5-14 Viewing Information About Constraints
DROP TABLE DeptTab;
CREATE TABLE DeptTab (
Deptno NUMBER(3) PRIMARY KEY,
Dname VARCHAR2(15),
Loc VARCHAR2(15),
CONSTRAINT uk_DeptTab_Dname_Loc UNIQUE (Dname, Loc),
CONSTRAINT c_DeptTab_Loc
CHECK (Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO'))
);
DROP TABLE EmpTab;
CREATE TABLE EmpTab (
Empno NUMBER(5) PRIMARY KEY,
Ename VARCHAR2(15) NOT NULL,
Job VARCHAR2(10),
Mgr NUMBER(5) CONSTRAINT r_EmpTab_Mgr
REFERENCES EmpTab ON DELETE CASCADE,
Hiredate DATE,
Sal NUMBER(7,2),
Comm NUMBER(5,2),
Deptno NUMBER(3) NOT NULL
CONSTRAINT r_EmpTab_Deptno REFERENCES DeptTab
);
-- Format columns (optional):
COLUMN CONSTRAINT_NAME FORMAT A20;
COLUMN CONSTRAINT_TYPE FORMAT A4 HEADING 'TYPE';
COLUMN TABLE_NAME FORMAT A10;
COLUMN R_CONSTRAINT_NAME FORMAT A17;
COLUMN SEARCH_CONDITION FORMAT A40;
COLUMN COLUMN_NAME FORMAT A12;
List accessible constraints in DeptTab and EmpTab:
SELECT CONSTRAINT_NAME, CONSTRAINT_TYPE, TABLE_NAME, R_CONSTRAINT_NAME FROM USER_CONSTRAINTS WHERE (TABLE_NAME = 'DEPTTAB' OR TABLE_NAME = 'EMPTAB') ORDER BY CONSTRAINT_NAME;
Result:
CONSTRAINT_NAME TYPE TABLE_NAME R_CONSTRAINT_NAME -------------------- ---- ---------- ----------------- C_DEPTTAB_LOC C DEPTTAB R_EMPTAB_DEPTNO R EMPTAB SYS_C006286 R_EMPTAB_MGR R EMPTAB SYS_C006290 SYS_C006286 P DEPTTAB SYS_C006288 C EMPTAB SYS_C006289 C EMPTAB SYS_C006290 P EMPTAB UK_DEPTTAB_DNAME_LOC U DEPTTAB 8 rows selected.
Distinguish between NOT NULL and CHECK constraints in DeptTab and EmpTab:
SELECT CONSTRAINT_NAME, SEARCH_CONDITION FROM USER_CONSTRAINTS WHERE (TABLE_NAME = 'DEPTTAB' OR TABLE_NAME = 'EMPTAB') AND CONSTRAINT_TYPE = 'C' ORDER BY CONSTRAINT_NAME;
Result:
CONSTRAINT_NAME SEARCH_CONDITION
-------------------- ----------------------------------------
C_DEPTTAB_LOC Loc IN ('NEW YORK', 'BOSTON', 'CHICAGO')
SYS_C006288 "ENAME" IS NOT NULL
SYS_C006289 "DEPTNO" IS NOT NULL
3 rows selected.
For DeptTab and EmpTab, list columns that constitute constraints:
SELECT CONSTRAINT_NAME, TABLE_NAME, COLUMN_NAME FROM USER_CONS_COLUMNS WHERE (TABLE_NAME = 'DEPTTAB' OR TABLE_NAME = 'EMPTAB') ORDER BY CONSTRAINT_NAME;
Result:
CONSTRAINT_NAME TABLE_NAME COLUMN_NAME -------------------- ---------- ------------ C_DEPTTAB_LOC DEPTTAB LOC R_EMPTAB_DEPTNO EMPTAB DEPTNO R_EMPTAB_MGR EMPTAB MGR SYS_C006286 DEPTTAB DEPTNO SYS_C006288 EMPTAB ENAME SYS_C006289 EMPTAB DEPTNO SYS_C006290 EMPTAB EMPNO UK_DEPTTAB_DNAME_LOC DEPTTAB LOC UK_DEPTTAB_DNAME_LOC DEPTTAB DNAME 9 rows selected.
Note that:
Some constraint names are user specified (such as UK_DEPTTAB_DNAME_LOC), while others are system specified (such as SYS_C006290).
Each constraint type is denoted with a different character in the CONSTRAINT_TYPE column. This table summarizes the characters used for each constraint type:
| Constraint Type | Character |
|---|---|
PRIMARY KEY | P |
UNIQUE KEY | U |
FOREIGN KEY | R |
CHECK, NOT NULL | C |
|
Note: An additional constraint type is indicated by the character "V" in the CONSTRAINT_TYPE column. This constraint type corresponds to constraints created using the WITH CHECK OPTION for views. |
These constraints are explicitly listed in the SEARCH_CONDITION column:
NOT NULL constraints
The conditions for user-defined CHECK constraints
Advanced Application Developer's Guide
11g Release 2 (11.2)
E25518-05
April 2012
Oracle Database Advanced Application Developer's Guide, 11g Release 2 (11.2)
E25518-05
Copyright © 1996, 2012, Oracle and/or its affiliates. All rights reserved.
Primary Author: Sheila Moore
Contributing Authors: D. Adams, L. Ashdown, M. Cowan, T. Kyte, J. Melnick, R. Moran, E. Paapanen, J. Russell, R. Strohm, R. Ward
Contributors: D. Alpern, G. Arora, C. Barclay, D. Bronnikov, T. Chang, L. Chen, B. Cheng, M. Davidson, R. Day, R. Decker, G. Doherty, D. Elson, A. Ganesh, M. Hartstein, Y. Hu, J. Huang, C. Iyer, N. Jain, R. Jenkins Jr., S. Kotsovolos, V. Krishnaswamy, S. Kumar, C. Lei, B. Llewellyn, D. Lorentz, V. Moore, K. Muthukkaruppan, V. Moore, J. Muller, R. Murthy, R. Pang, B. Sinha, S. Vemuri, W. Wang, D. Wong, A. Yalamanchi, Q. Yu
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
This chapter explains how to develop applications on the publish-subscribe model.
Topics:
Because the database is the most significant resource of information within the enterprise, Oracle created a publish-subscribe solution for enterprise information delivery and messaging to complement this role.
Networking technologies and products enable a high degree of connectivity across a large number of computers, applications, and users. In these environments, it is important to provide asynchronous communications for the class of distributed systems that operate in a loosely-coupled and autonomous fashion, and which require operational immunity from network failures. This requirement is filled by various middleware products that are characterized as messaging, message-oriented middleware (MOM), message queuing, or publish-subscribe.
Applications that communicate through a publish and subscribe paradigm require the sending applications (publishers) to publish messages without explicitly specifying recipients or having knowledge of intended recipients. Similarly, receiving applications (subscribers) must receive only those messages that the subscriber has registered an interest in.
This decoupling between senders and recipients is usually accomplished by an intervening entity between the publisher and the subscriber, which serves as a level of indirection. This intervening entity is a queue that represents a subject or channel. Figure 16-1 illustrates publish and subscribe functionality.
Figure 16-1 Oracle Publish-Subscribe Functionality
A subscriber subscribes to a queue by expressing interest in messages enqueued to that queue and by using a subject- or content-based rule as a filter. This results in a set of rule-based subscriptions associated with a given queue.
At run time, publishers post messages to various queues. The queue (in other words, the delivery mechanisms of the underlying infrastructure) then delivers messages that match the various subscriptions to the appropriate subscribers.
Oracle Database includes these features to support database-enabled publish-subscribe messaging:
Database events support declarative definitions for publishing database events, detection, and runtime publication of such events. This feature enables active publication of information to end-users in an event-driven manner, to complement the traditional pull-oriented approaches to accessing information.
Oracle Advanced Queuing (AQ) supports a queue-based publish-subscribe paradigm. Database queues serve as a durable store for messages, along with capabilities to allow publish and subscribe based on queues. A rules-engine and subscription service dynamically route messages to recipients based on expressed interest. This allows decoupling of addressing between senders and receivers to complement the existing explicit sender-receiver message addressing.
Client notifications support asynchronous delivery of messages to interested subscribers, enabling database clients to register interest in certain queues, and it enables these clients to receive notifications when publications on such queues occur. Asynchronous delivery of messages to database clients is in contrast to the traditional polling techniques used to retrieve information.
A queue is an entity that supports the notion of named subjects of interest. Queues can be characterized as persistent or nonpersistent (lightweight).
A persistent queue serves as a durable container for messages. Messages are delivered in a deferred and reliable mode.
The underlying infrastructure of a nonpersistent, or lightweight, queue pushes the messages published to connected clients in a lightweight, at-best-once, manner.
Publishers and subscribers are internally represented as agents.
An agent is a persistent logical subscribing entity that expresses interest in a queue through a subscription. An agent has properties, such as an associated subscription, an address, and a delivery mode for messages. In this context, an agent is an electronic proxy for a publisher or subscriber.
client
A client is a transient physical entity. The attributes of a client include the physical process where the client programs run, the node name, and the client application logic. Several clients can act on behalf of a single agent. The same client, if authorized, can act on behalf of multiple agents.
A rule on a queue is specified as a conditional expression using a predefined set of operators on the message format attributes or on the message header attributes. Each queue has an associated message content format that describes the structure of the messages represented by that queue. The message format may be unstructured (RAW) or it may have a well-defined structure (ADT). This allows both subject- or content-based subscriptions.
Subscribers (agents) may specify subscriptions on a queue using a rule. Subscribers are durable and are stored in a catalog.
database event publication framework
The database represents a significant source for publishing information. An event framework is proposed to allow declarative definition of database event publication. As these pre-defined events occur, the framework detects and publishes such events. This allows active delivery of information to end-users in an event-driven manner as part of the publish-subscribe capability.
Registration is the process of associated delivery information by a given client, acting on behalf of an agent. There is an important distinction between the subscription and registration related to the agent/client separation.
Subscription indicates an interest in a particular queue by an agent. It does not specify where and how delivery must occur. Delivery information is a physical property that is associated with a client, and it is a transient manifestation of the logical agent (the subscriber). A specific client process acting on behalf of an agent registers delivery information by associating a host and port, indicating where the delivery is to be done, and a callback, indicating how there delivery is to be done.
publishing a message
Publishers publish messages to queues by using the appropriate queuing interfaces. The interfaces may depend on which model the queue is implemented on. For example, an enqueue call represents the publishing of a message.
When a message is posted or published to a given queue, a rules engine extracts the set of candidate rules from all rules defined on that queue that match the published message.
Corresponding to the list of candidate rules on a given queue, the set of subscribers that match the candidate rules can be evaluated. In turn, the set of agents corresponding to this subscription list can be determined and notified.
posting
The queue notifies all registered clients of the appropriate published messages. This concept is called posting. When the queue must notify all interested clients, it posts the message to all registered clients.
receiving a message
A subscriber may receive messages through any of these mechanisms:
A client process acting on behalf of the subscriber specifies a callback using the registration mechanism. The posting mechanism then asynchronously invokes the callback when a message matches the subscriber's subscription. The message content may be passed to the callback function (nonpersistent queues only).
A client process acting on behalf of the subscriber specifies a callback using the registration mechanism. The posting mechanism then asynchronously invokes the callback function, but without the full message content. This serves as a notification to the client, which subsequently retrieves the message content in a pull fashion (persistent queues only).
A client process acting on behalf of the subscriber simply retrieves messages from the queue in a periodic, or some other appropriate, manner. While the messages are deferred, there is no asynchronous delivery to the end-client.
This example shows how database events, client notification, and AQ work to implement publish-subscribe.
Create under the user schema, pubsub, with all objects necessary to support a publish-subscribe mechanism. In this particular code, the Agent snoop subscribe to messages that are published at logon events. To use AQ functionality, user pubsub needs AQ_ADMINISTRATOR_ROLE privileges and EXECUTE privilege on DBMS_AQ and DBMS_AQADM.
Rem ------------------------------------------------------
REM create queue table for persistent multiple consumers:
Rem ------------------------------------------------------
Rem Create or replace a queue table
BEGIN
DBMS_AQADM.CREATE_QUEUE_TABLE(
Queue_table => 'Pubsub.Raw_msg_table',
Multiple_consumers => TRUE,
Queue_payload_type => 'RAW',
Compatible => '8.1');
END;
/
Rem ------------------------------------------------------
Rem Create a persistent queue for publishing messages:
Rem ------------------------------------------------------
Rem Create a queue for logon events
BEGIN
DBMS_AQADM.CREATE_QUEUE(
Queue_name => 'Pubsub.Logon',
Queue_table => 'Pubsub.Raw_msg_table',
Comment => 'Q for error triggers');
END;
/
Rem ------------------------------------------------------
Rem Start the queue:
Rem ------------------------------------------------------
BEGIN
DBMS_AQADM.START_QUEUE('pubsub.logon');
END;
/
Rem ------------------------------------------------------
Rem define new_enqueue for convenience:
Rem ------------------------------------------------------
CREATE OR REPLACE PROCEDURE New_enqueue(
Queue_name IN VARCHAR2,
Payload IN RAW ,
Correlation IN VARCHAR2 := NULL,
Exception_queue IN VARCHAR2 := NULL)
AS
Enq_ct DBMS_AQ.Enqueue_options_t;
Msg_prop DBMS_AQ.Message_properties_t;
Enq_msgid RAW(16);
Userdata RAW(1000);
BEGIN
Msg_prop.Exception_queue := Exception_queue;
Msg_prop.Correlation := Correlation;
Userdata := Payload;
DBMS_AQ.ENQUEUE(Queue_name, Enq_ct, Msg_prop, Userdata, Enq_msgid);
END;
/
Rem ------------------------------------------------------
Rem add subscriber with rule based on current user name,
Rem using correlation_id
Rem ------------------------------------------------------
DECLARE
Subscriber Sys.Aq$_agent;
BEGIN
Subscriber := sys.aq$_agent('SNOOP', NULL, NULL);
DBMS_AQADM.ADD_SUBSCRIBER(
Queue_name => 'Pubsub.logon',
Subscriber => subscriber,
Rule => 'CORRID = ''HR'' ');
END;
/
Rem ------------------------------------------------------
Rem create a trigger on logon on database:
Rem ------------------------------------------------------
Rem create trigger on after logon:
CREATE OR REPLACE TRIGGER pubsub.Systrig2
AFTER LOGON
ON DATABASE
BEGIN
New_enqueue('Pubsub.Logon', HEXTORAW('9999'), Dbms_standard.login_user);
END;
/
After subscriptions are created, the next step is for the client to register for notification using callback functions. This is done using the Oracle Call Interface (OCI). This code performs necessary steps for registration. The initial steps of allocating and initializing session handles are omitted here for sake of clarity:
ub4 namespace = OCI_SUBSCR_NAMESPACE_AQ; /* callback function for notification of logon of user 'HR' on database: */ ub4 notifySnoop(ctx, subscrhp, pay, payl, desc, mode) dvoid *ctx; OCISubscription *subscrhp; dvoid *pay; ub4 payl; dvoid *desc; ub4 mode; { printf("Notification : User HR Logged on\n"); } int main() { OCISession *authp = (OCISession *) 0; OCISubscription *subscrhpSnoop = (OCISubscription *)0; /***************************************************** Initialize OCI Process/Environment Initialize Server Contexts Connect to Server Set Service Context ******************************************************/ /* Registration Code Begins */ /* Each call to initSubscriptionHn allocates and Initialises a Registration Handle */ initSubscriptionHn( &subscrhpSnoop, /* subscription handle */ "ADMIN:PUBSUB.SNOOP", /* subscription name */ /* <agent_name>:<queue_name> */ (dvoid*)notifySnoop); /* callback function */ /***************************************************** The Client Process does not need a live Session for Callbacks End Session and Detach from Server ******************************************************/ OCISessionEnd ( svchp, errhp, authp, (ub4) OCI_DEFAULT); /* detach from server */ OCIServerDetach( srvhp, errhp, OCI_DEFAULT); while (1) /* wait for callback */ sleep(1); } void initSubscriptionHn (subscrhp, subscriptionName, func) OCISubscription **subscrhp; char* subscriptionName; dvoid * func; { /* allocate subscription handle: */ (void) OCIHandleAlloc((dvoid *) envhp, (dvoid **)subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION, (size_t) 0, (dvoid **) 0); /* set subscription name in handle: */ (void) OCIAttrSet((dvoid *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION, (dvoid *) subscriptionName, (ub4) strlen((char *)subscriptionName), (ub4) OCI_ATTR_SUBSCR_NAME, errhp); /* set callback function in handle: */ (void) OCIAttrSet((dvoid *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION, (dvoid *) func, (ub4) 0, (ub4) OCI_ATTR_SUBSCR_CALLBACK, errhp); (void) OCIAttrSet((dvoid *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION, (dvoid *) 0, (ub4) 0, (ub4) OCI_ATTR_SUBSCR_CTX, errhp); /* set namespace in handle: */ (void) OCIAttrSet((dvoid *) *subscrhp, (ub4) OCI_HTYPE_SUBSCRIPTION, (dvoid *) &namespace, (ub4) 0, (ub4) OCI_ATTR_SUBSCR_NAMESPACE, errhp); checkerr(errhp, OCISubscriptionRegister(svchp, subscrhp, 1, errhp, OCI_DEFAULT)); }
If user HR logs on to the database, the client is notified, and the call back function notifySnoop is invoked.
This chapter explains how to use the Oracle XA library. Typically, you use this library in applications that work with transaction monitors. The XA features are most useful in applications in which transactions interact with multiple databases.
Topics:
|
See Also:
|
The X/Open Distributed Transaction Processing (DTP) architecture defines a standard architecture or interface that enables multiple application programs (APs) to share resources provided by multiple, and possibly different, resource managers (RMs). It coordinates the work between APs and RMs into global transactions.
The Oracle XA library conforms to the X/Open software architecture's XA interface specification. The Oracle XA library is an external interface that enables a client-side transaction manager (TM) that is not an Oracle client-side TM to coordinate global transactions, thereby allowing inclusion of database RMs that are not Oracle Database RMs in distributed transactions. For example, a client application can manage an Oracle Database transaction and a transaction in an NTFS file system as a single, global transaction.
Figure 15-1 illustrates a possible X/Open DTP model.
Topics:
Resource Manager (RM)
A resource manager controls a shared, recoverable resource that can be returned to a consistent state after a failure. Examples are relational databases, transactional queues, and transactional file systems. Oracle Database is an RM and uses its online redo log and undo segments to return to a consistent state after a failure.
Distributed Transaction
A distributed transaction, also called a global transaction, is a client transaction that involves updates to multiple distributed resources and requires "all-or-none" semantics across distributed RMs.
Branch
A branch is a unit of work contained within one RM. Multiple branches comprise a global transaction. For Oracle Database, each branch maps to a local transaction inside the database server.
Transaction Manager (TM)
A transaction manager provides an API for specifying the boundaries of the transaction and manages commit and recovery. The TM implements a two-phase commit engine to provide "all-or-none" semantics across distributed RMs.
An external TM is a middle-tier component that resides outside Oracle Database. Normally, the database is its own internal TM. Using a standards-based TM enables Oracle Database to cooperate with other heterogeneous RMs in a single transaction.
Transaction Processing Monitor (TPM)
A TM is usually provided by a transaction processing monitor (TPM), such as:
A TPM coordinates the flow of transaction requests between the client processes that issue requests and the back-end servers that process them. Basically, a TPM coordinates transactions that require the services of several different types of back-end processes, such as application servers and RMs distributed over a network.
The TPM synchronizes any commits or rollbacks required to complete a distributed transaction. The TM portion of the TPM is responsible for controlling when distributed commits and rollbacks take place. Thus, if a distributed application program takes advantage of a TPM, then the TM portion of the TPM is responsible for controlling the two-phase commit protocol. The RMs enable the TMs to perform this task.
Because the TM controls distributed commits or rollbacks, it must communicate directly with Oracle Database (or any other RM) through the XA interface. It uses Oracle XA library subprograms, which are described in "Oracle XA Library Subprograms", to tell Oracle Database how to process the transaction, based on its knowledge of all RMs in the transaction.
Two-Phase Commit Protocol
The Oracle XA library interface follows the two-phase commit protocol. The sequence of events is as follows:
In the prepare phase, the TM asks each RM to guarantee that it can commit any part of the transaction. If this is possible, then the RM records its prepared state and replies affirmatively to the TM. If it is not possible, then the RM might roll back any work, reply negatively to the TM, and forget about the transaction. The protocol allows the application, or any RM, to roll back the transaction unilaterally until the prepare phase completes.
In phase two, the TM records the commit decision and issues a commit or rollback to all RMs participating in the transaction. TM can issue a commit for an RM only if all RMs have replied affirmatively to phase one.
Application Program (AP)
An application program defines transaction boundaries and specifies actions that constitute a transaction. For example, an AP can be a precompiler or Oracle Call Interface (OCI) program. The AP operates on the RM resource through its native interface, for example, SQL.
TX Interface
An application program starts and completes all transaction control operations through the TM through an interface called TX. The AP does not directly use the XA interface. APs are not aware of branches that fork in the middle-tier: application threads do not explicitly join, leave, suspend, and resume branch work, instead the TM portion of the transaction processing monitor manages the branches of a global transaction for APs. Ultimately, APs call the TM to commit all-or-none.
|
Note: The naming conventions for the TX interface and associated subprograms are vendor-specific. For example, thetx_open call might be referred to as tp_open on your system. In some cases, the calls might be implicit, for example, at the entry to a transactional RPC. See the documentation supplied with the transaction processing monitor for details. |
Tight and Loose Coupling
Application threads are tightly coupled if the RM considers them as a single entity for all isolation semantic purposes. Tightly coupled branches must see changes in each other. Furthermore, an external client must either see all changes of a tightly coupled set or none of the changes. If application threads are not tightly coupled, then they are loosely coupled.
Dynamic and Static Registration
Oracle Database supports both dynamic and static registration. In dynamic registration, the RM runs an application callback before starting any work. In static registration, you must call xa_start for each RM before starting any work, even if some RMs are not involved.
As a resource manager, Oracle Database must publish the information described in Table 15-1.
Table 15-1 Required XA Features Published by Oracle Database
| XA Feature | Oracle Database Details |
|---|---|
|
|
The Oracle Database |
|
|
The Oracle Database resource manager name within the |
|
Close string |
The close string used by |
|
Open string |
For the description of the format of the open string that |
|
Libraries |
Libraries needed to link applications using Oracle XA have platform-specific names. The procedure is similar to linking an ordinary precompiler or OCI program except that you might have to link any TPM-specific libraries. If you are not using |
|
Requirements |
None. The functionality to support XA is part of both Standard Edition and Enterprise Edition. |
The Oracle XA library subprograms enable a TM to tell Oracle Database how to process transactions. Generally, the TM must open the resource by using xa_open. Typically, the opening of the resource results from the AP call to tx_open. Some TMs might call xa_open implicitly when the application begins.
Similarly, there is a close (using xa_close) that occurs when the application is finished with the resource. The close might occur when the AP calls tx_close or when the application terminates.
The TM instructs the RMs to perform several other tasks, which include:
Starting a transaction and associating it with an ID
Rolling back a transaction
Preparing and committing a transaction
Topics:
XA Library subprograms are described in Table 15-2.
Table 15-2 XA Library Subprograms
| XA Subprogram | Description |
|---|---|
|
|
Connects to the RM. |
|
|
Disconnects from the RM. |
|
|
Starts a transaction and associates it with the given transaction ID (XID), or associates the process with an existing transaction. |
|
|
Disassociates the process from the given XID. |
|
|
Rolls back the transaction associated with the given XID. |
|
|
Prepares the transaction associated with the given XID. This is the first phase of the two-phase commit protocol. |
|
|
Commits the transaction associated with the given XID. This is the second phase of the two-phase commit protocol. |
|
|
Retrieves a list of prepared, heuristically committed, or heuristically rolled back transactions. |
|
|
Forgets the heuristically completed transaction associated with the given XID. |
In general, the AP need not worry about the subprograms in Table 15-2 except to understand the role played by the xa_open string.
Oracle Database's XA interface includes some additional functions, which are described in Table 15-3.
Table 15-3 Oracle XA Interface Extensions
| Function | Description |
|---|---|
|
|
Returns the OCI service handle for a given XA connection. The |
|
|
Returns the OCI environment handle for a given XA connection. The |
|
|
Converts an Oracle Database error code to an XA error code (only applicable to dynamic registration). The first parameter is the service handle used to run the work in the database. The second parameter is the error code that was returned from Oracle Database. Use this function to determine if the error returned from an OCI statement was caused because the |
This section explains how to develop and install Oracle XA applications:
The responsibilities of the DBA or system administrator are as follows:
Define the open string, with help from the application developer. For details, see "Defining the xa_open String".
Ensure that the static data dictionary view DBA_PENDING_TRANSACTIONS exists and grant the SELECT privilege to the view for all Oracle users specified in the xa_open string.
Grant FORCE TRANSACTION privilege to the Oracle user who might commit or roll back pending (in-doubt) transactions that he or she created, using the command COMMIT FORCE local_tran_id or ROLLBACK FORCE local_tran_id.
Grant FORCE ANY TRANSACTION privilege to the Oracle user who might commit or roll back XA transactions created by other users. For example, if user A might commit or roll back a transaction that was created by user B, user A must have FORCE ANY TRANSACTION privilege.
In Oracle Database version 7 client applications, all Oracle Database accounts used by Oracle XA library must have the SELECT privilege on the dynamic performance view V$XATRANS$. This view must have been created during the XA library installation. If necessary, you can manually create the view by running the SQL script xaview.sql as Oracle Database user SYS.
|
See Also: Your Oracle Database platform-specific documentation for the location of thecatxpend.sql script |
Using the open string information, install the RM into the TPM configuration. Follow the TPM vendor instructions.
The DBA or system administrator must be aware that a TPM system starts the process that connects to Oracle Database. See your TPM documentation to determine what environment exists for the process and what user ID it must have. Ensure that correct values are set for $ORACLE_HOME and $ORACLE_SID in this environment.
Grant the user ID write permission to the directory in which the system is to write the XA trace file.
|
See Also: "Defining the xa_open String" for information about how to specify an Oracle System Identifier (SID) or a trace directory that is different from the defaults |
Start the relevant database instances to bring Oracle XA applications on-line. Perform this task before starting any TPM servers.
The responsibilities of the application developer are as follows:
Define the open string with help from the DBA or system administrator, as explained in "Defining the xa_open String".
Develop the applications.
Observe special restrictions on transaction-oriented SQL statements for precompilers.
Link the application according to TPM vendor instructions.
The open string is used by the transaction monitor to open the database. The maximum number of characters in an open string is 256.
Topics:
You can define an open string with the syntax shown in Example 15-1.
These strings shows sample parameter settings:
ORACLE_XA+DB=MANAGERS+SqlNet=SID1+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog ORACLE_XA+DB=PAYROLL+SqlNet=SID2+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog ORACLE_XA+SqlNet=SID3+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog
These topics describe valid parameters for the required_fields and optional_fields placeholders:
|
Note:
|
The required_fields placeholder in Example 15-1 refers to any of the name-value pairs described in Table 15-4.
Table 15-4 Required Fields of xa_open string
| Syntax Element | Description |
|---|---|
|
|
Specifies that no explicit user or password information is provided and that the operating system authentication form is used. For more information see Oracle Database Administrator's Guide. |
|
|
Specifies the user name and password for a valid Oracle Database account. As described in "DBA or System Administrator Responsibilities", ensure that HR has the |
|
|
Specifies the maximum number of seconds allowed in a transaction between one service and the next, or between a service and the commit or rollback of the transaction, before the system terminates the transaction. For example, For example, if the TPM uses remote subprogram calls between the client and the servers, then The value of |
The optional_fields placeholder in Example 15-1 refers to any of the name-value pairs described in Table 15-5.
Table 15-5 Optional Fields in the xa_open String
| Syntax Element | Description |
|---|---|
|
|
Specifies whether local transactions are allowed. The default value is |
|
|
Specifies the name used by Oracle Database precompilers to identify the database. For example, Application programs that use only the default database for the Oracle Database precompiler (that is, they do not use the The |
|
|
Specifies the path name on the local system where the Oracle XA library error and tracing information is to be logged. The default is |
|
|
Specifies whether the application is initialized in object mode. The default value is false. If the application must use certain API calls that require object mode, such as |
|
|
Specifies the number of cursors to be allocated when the database is opened. It serves the same purpose as the precompiler option |
|
|
Specifies the Oracle Net database link to use to log on to the system. This string must be an entry in You can use the |
|
|
Specifies whether locks are shared. Oracle Database transaction branches within the same global transaction can be coupled tightly or loosely. If branches are loosely coupled, then they do not share locks. Set the value to |
|
|
Specifies the number of seconds Oracle Database waits for a transaction branch that is being used by another session before |
|
|
Specifies whether the application is multithreaded. The default value is |
When used in an Oracle XA application, cursors are valid only for the duration of the transaction. Explicit cursors must be opened after the transaction begins, and closed before the commit or rollback.
You have these options when interfacing with precompilers:
The examples in this topic use the precompiler Pro*C/C++.
To interface to a precompiler with the default database, ensure that the DB=db_name field used in the open string is not present. The absence of this field indicates the default connection. Only one default connection is allowed for each process.
This is an example of an open string identifying a default Pro*C/C++ connection:
ORACLE_XA+SqlNet=maildb+ACC=P/username/password +SesTM=10+LogDir=/usr/local/logs
The DB=db_name is absent, indicating an empty database ID string.
The syntax of a SQL statement is:
EXEC SQL UPDATE Emp_tab SET Sal = Sal*1.5;
To interface to a precompiler with a named database, include the DB=db_name field in the open string. Any database you refer to must reference the same db_name you specified in the corresponding open string.
An application might include the default database and one or more named databases. For example, suppose you want to update an employee's salary in one database, his department number (DEPTNO) in another, and his manager in a third database. Configure the open strings in the transaction manager as shown in Example 15-2.
Example 15-2 Sample Open String Configuration
ORACLE_XA+DB=MANAGERS+SqlNet=SID1+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog ORACLE_XA+DB=PAYROLL+SqlNet=SID2+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog ORACLE_XA+SqlNet=SID3+ACC=P/username/password +SesTM=10+LogDir=/usr/local/xalog
There is no DB=db_name field in the last open string in Example 15-2.
In the application server program, enter declarations such as:
EXEC SQL DECLARE PAYROLL DATABASE; EXEC SQL DECLARE MANAGERS DATABASE;
Again, the default connection (corresponding to the third open string that does not contain the DB field) needs no declaration.
When doing the update, enter statements similar to these:
EXEC SQL AT PAYROLL UPDATE Emp_Tab SET Sal=4500 WHERE Empno=7788; EXEC SQL AT MANAGERS UPDATE Emp_Tab SET Mgr=7566 WHERE Empno=7788; EXEC SQL UPDATE Emp_Tab SET Deptno=30 WHERE Empno=7788;
There is no AT clause in the last statement because it is referring to the default database.
In Oracle Database precompilers release 1.5.3 or later, you can use a character host variable in the AT clause, as this example shows:
EXEC SQL BEGIN DECLARE SECTION;
DB_NAME1 CHARACTER(10);
DB_NAME2 CHARACTER(10);
EXEC SQL END DECLARE SECTION;
...
SET DB_NAME1 = 'PAYROLL'
SET DB_NAME2 = 'MANAGERS'
...
EXEC SQL AT :DB_NAME1 UPDATE...
EXEC SQL AT :DB_NAME2 UPDATE...
|
Caution: Do not have XA applications create connections other than those created throughxa_open. Work performed on non-XA connections is outside the global transaction and must be committed separately. |
Oracle Call Interface applications that use the Oracle XA library must not call OCISessionBegin to log on to the resource manager. Rather, the logon must be done through the TPM. The applications can run the function xaoSvcCtx to obtain the service context structure when they must access the resource manager.
In applications that must pass the environment handle to OCI functions, you can also call xaoEnv to find that handle.
Because an application server can have multiple concurrent open Oracle Database resource managers, it must call the function xaoSvcCtx with the correct arguments to obtain the correct service context.
When you use the XA library, transactions are not controlled by the SQL statements that commit or roll back transactions. Rather, they are controlled by an API accepted by the TM that starts and stops transactions. You call the API that is provided by the transaction manager, including the TX interface listed in Table 15-6, but not the XA Library Subprograms listed in Table 15-2.
The TMs typically control the transactions through the XA interface. This interface includes the functions described in Table 15-2.
Table 15-6 TX Interface Functions
| TX Function | Description |
|---|---|
|
|
Logs into the resource manager(s) |
|
|
Logs out of the resource manager(s) |
|
|
Starts a transaction |
|
|
Commits a transaction |
|
|
Rolls back the transaction |
Most TPM applications use a client/server architecture in which an application client requests services and an application server provides them. The examples shown in "Examples of Precompiler Applications" use such a client/server model. A service is a logical unit of work that, for Oracle Database as the resource manager, comprises a set of SQL statements that perform a related unit of work.
For example, when a service named "credit" receives an account number and the amount to be credited, it runs SQL statements to update information in certain tables in the database. In addition, a service might request other services. For example, a "transfer fund" service might request services from a "credit" and "debit" service.
Typically, application clients request services from the application servers to perform tasks within a transaction. For some TPM systems, however, the application client itself can offer its own local services. As shown in "Examples of Precompiler Applications", you can encode transaction control statements within either the client or the server.
To have multiple processes participating in the same transaction, the TPM provides a communication API that enables transaction information to flow between the participating processes. Examples of communications APIs include RPC, pseudo-RPC functions, and send/receive functions.
Because the leading vendors support different communication functions, these examples use the communication pseudo-function tpm_service to generalize the communications API.
X/Open includes several alternative methods for providing communication functions in their preliminary specification. At least one of these alternatives is supported by each of the leading TPM vendors.
These examples illustrate precompiler applications. Assume that the application server has logged onto the RMs system, in a TPM-specific manner. Example 15-3 shows a transaction started by an application server.
Example 15-3 Transaction Started by an Application Server
/***** Client: *****/
tpm_service("ServiceName"); /*Request Service*/
/***** Server: *****/
ServiceName()
{
<get service specific data>
tx_begin(); /* Begin transaction boundary */
EXEC SQL UPDATE ...;
/* This application server temporarily becomes */
/* a client and requests another service. */
tpm_service("AnotherService");
tx_commit(); /* Commit the transaction */
<return service status back to the client>
}
Example 15-4 shows a transaction started by an application client.
Example 15-4 Transaction Started by an Application Client
/***** Client: *****/
tx_begin(); /* Begin transaction boundary */
tpm_service("Service1");
tpm_service("Service2");
tx_commit(); /* Commit the transaction */
/***** Server: *****/
Service1()
{
<get service specific data>
EXEC SQL UPDATE ...;
<return service status back to the client>
}
Service2()
{
<get service specific data>
EXEC SQL UPDATE ...;
...
<return service status back to client>
}
To migrate existing precompiler or OCI applications to a TPM application that uses the Oracle XA library, you must:
Reorganize the application into a framework of "services" so that application clients request services from application servers. Some TPMs require the application to use the tx_open and tx_close functions, whereas other TPMs do the logon and logoff implicitly.
If you do not specify the SqlNet parameter in your open string, then the application uses the default Oracle Net driver. Thus, ensure that the application server is brought up with the ORACLE_HOME and ORACLE_SID environment variables properly defined. This is accomplished in a TPM-specific fashion. See your TPM vendor documentation for instructions on how to accomplish this.
Ensure that the application replaces the regular connect and disconnect statements. For example, replace the connect statements EXEC SQL CONNECT (for precompilers) or OCISessionBegin, OCIServerAttach, and OCIEnvCreate (for OCI) with tx_open. Replace the disconnect statements EXEC SQL COMMIT/ROLLBACK WORK RELEASE (for precompilers) or OCISessionEnd/OCIServerDetach (for OCI) with tx_close.
Ensure that the application replaces the regular commit or rollback statements for any global transactions and begins the transaction explicitly.
For example, replace the COMMIT/ROLLBACK statements EXEC SQL COMMIT/ROLLBACK WORK (for precompilers), or OCITransCommit/OCITransRollback (for OCI) with tx_commit/tx_rollback and start the transaction by calling tx_begin.
|
Note: The preceding is only true for global rather than local transactions. Commit or roll back local transactions with the Oracle API. |
Ensure that the application resets the fetch state before ending a transaction. In general, use release_cursor=no. Use release_cursor=yes only when you are certain that a statement will run only once.
Table 15-7 lists the TPM functions that replace regular Oracle Database statements when migrating precompiler or OCI applications to TPM applications.
If you use a transaction monitor that supports threads, then the Oracle XA library enables you to write applications that are thread-safe. Nevertheless, keep certain issues in mind.
A thread of control (or thread) refers to the set of connections to resource managers. In an nonthreaded system, each process is considered a thread of control because each process has its own set of connections to RMs and maintains its own independent resource manager table. In a threaded system, each thread has an autonomous set of connections to RMs and each thread maintains a private RM table. This private table must be allocated for each thread and de-allocated when the thread terminates, even if the termination is abnormal.
|
Note: In Oracle Database, each thread that accesses the database must have its own connection. |
Topics:
The xa_open string provides the clause Threads=. You must specify this clause as true to enable the use of threads by the TM. The default is false. In most cases, the TM creates the threads; the application does not know when a thread is created. Therefore, it is advisable to allocate a service context on the stack within each service that is written for a TM application. Before doing any Oracle Database-related calls in that service, you must call the xaoSvcCtx function to retrieve the initialized OCI service context. You can then use this context for OCI calls within the service.
These restrictions apply when using threads:
Any Pro* or OCI code that runs as part of the application server process on the transaction monitor cannot be threaded unless the transaction monitor is explicitly told when each application thread is started. This is typically accomplished by using a special C compiler provided by the TM vendor.
The Pro* statements EXEC SQL ALLOCATE and EXEC SQL USE are not supported. Therefore, when threading is enabled, you cannot use embedded SQL statements across non-XA connections.
If one thread in a process connects to Oracle Database through XA, then all other threads in the process that connect to Oracle Database must also connect through XA. You cannot connect through EXEC SQL CONNECT in one thread and through xa_open in another thread.
PL/SQL applications can use the Oracle XA library with the DBMS_XA package. For information about this package, see Oracle Database PL/SQL Packages and Types Reference.
In Example 15-5, one PL/SQL session starts a transaction but does not commit it, a second session resumes the transaction, and a third session commits the transaction. All three sessions are connected to the HR schema.
Example 15-5 Using the DBMS_XA Package
REM Session 1 starts a transaction and does some work. DECLARE rc PLS_INTEGER; oer PLS_INTEGER; xae EXCEPTION; BEGIN rc := DBMS_XA.XA_START(DBMS_XA_XID(123), DBMS_XA.TMNOFLAGS); IF rc!=DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('ORA-' || oer || ' occurred, XA_START failed'); RAISE xae; ELSE DBMS_OUTPUT.PUT_LINE('XA_START(new xid=123) OK'); END IF; UPDATE employees SET salary=salary*1.1 WHERE employee_id = 100; rc := DBMS_XA.XA_END(DBMS_XA_XID(123), DBMS_XA.TMSUSPEND); IF rc!=DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('ORA-' || oer || ' occurred, XA_END failed'); RAISE xae; ELSE DBMS_OUTPUT.PUT_LINE('XA_END(suspend xid=123) OK'); END IF; EXCEPTION WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE ('XA error('||rc||') occurred, rolling back the transaction ...'); rc := DBMS_XA.XA_END(DBMS_XA_XID(123), DBMS_XA.TMSUCCESS); rc := DBMS_XA.XA_ROLLBACK(DBMS_XA_XID(123)); IF rc != DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('XA-'||rc||', ORA-' || oer || ' XA_ROLLBACK does not return XA_OK'); raise_application_error(-20001, 'ORA-'||oer|| ' error in rolling back a failed transaction'); END IF; raise_application_error(-20002, 'ORA-'||oer|| ' error in transaction processing, transaction rolled back'); END; / SHOW ERRORS DISCONNECT REM Session 2 resumes the transaction and does some work. DECLARE rc PLS_INTEGER; oer PLS_INTEGER; s NUMBER; xae EXCEPTION; BEGIN rc := DBMS_XA.XA_START(DBMS_XA_XID(123), DBMS_XA.TMRESUME); IF rc!=DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('ORA-' || oer || ' occurred, xa_start failed'); RAISE xae; ELSE DBMS_OUTPUT.PUT_LINE('XA_START(resume xid=123) OK'); END IF; SELECT salary INTO s FROM employees WHERE employee_id = 100; DBMS_OUTPUT.PUT_LINE('employee_id = 100, salary = ' || s); rc := DBMS_XA.XA_END(DBMS_XA_XID(123), DBMS_XA.TMSUCCESS); IF rc!=DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('ORA-' || oer || ' occurred, XA_END failed'); RAISE xae; ELSE DBMS_OUTPUT.PUT_LINE('XA_END(detach xid=123) OK'); END IF; EXCEPTION WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE ('XA error('||rc||') occurred, rolling back the transaction ...'); rc := DBMS_XA.XA_END(DBMS_XA_XID(123), DBMS_XA.TMSUCCESS); rc := DBMS_XA.XA_ROLLBACK(DBMS_XA_XID(123)); IF rc != DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('XA-'||rc||', ORA-' || oer || ' XA_ROLLBACK does not return XA_OK'); raise_application_error(-20001, 'ORA-'||oer|| ' error in rolling back a failed transaction'); END IF; raise_application_error(-20002, 'ORA-'||oer|| ' error in transaction processing, transaction rolled back'); END; / SHOW ERRORS DISCONNECT REM Session 3 commits the transaction. DECLARE rc PLS_INTEGER; oer PLS_INTEGER; xae EXCEPTION; BEGIN rc := DBMS_XA.XA_COMMIT(DBMS_XA_XID(123), TRUE); IF rc!=DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('ORA-' || oer || ' occurred, XA_COMMIT failed'); RAISE xae; ELSE DBMS_OUTPUT.PUT_LINE('XA_COMMIT(commit xid=123) OK'); END IF; EXCEPTION WHEN xae THEN DBMS_OUTPUT.PUT_LINE ('XA error('||rc||') occurred, rolling back the transaction ...'); rc := DBMS_XA.XA_ROLLBACK(DBMS_XA_XID(123)); IF rc != DBMS_XA.XA_OK THEN oer := DBMS_XA.XA_GETLASTOER(); DBMS_OUTPUT.PUT_LINE('XA-'||rc||', ORA-' || oer || ' XA_ROLLBACK does not return XA_OK'); raise_application_error(-20001, 'ORA-'||oer|| ' error in rolling back a failed transaction'); END IF; raise_application_error(-20002, 'ORA-'||oer|| ' error in transaction processing, transaction rolled back'); END; / SHOW ERRORS DISCONNECT QUIT
Topics:
The Oracle XA library logs any error and tracing information to its trace file. This information is useful in supplementing the XA error codes. For example, it can indicate whether an xa_open failure is caused by an incorrect open string, failure to find the Oracle Database instance, or a logon authorization failure.
The name of the trace file is xa_db_namedate.trc, where db_name is the database name specified in the open string field DB=db_name, and date is the date when the information is logged to the trace file. If you do not specify DB=db_name in the open string, then it automatically defaults to NULL.
For example, xa_NULL06022005.trc indicates a trace file that was created on June 2, 2005. Its DB field was not specified in the open string when the resource manager was opened. The filename xa_Finance12152004.trc indicates a trace file was created on December 15, 2004. Its DB field was specified as "Finance" in the open string when the resource manager was opened.
|
Note: Multiple Oracle XA library resource managers with the sameDB field and LogDir field in their open strings log all trace information that occurs on the same day to the same trace file. |
Suppose that a trace file contains these contents:
1032.12345.2: ORA-01017: invalid username/password; logon denied 1032.12345.2: xaolgn: XAER_INVAL; logon denied
Table 15-8 explains the meaning of each element.
Table 15-8 Sample Trace File Contents
| String | Description |
|---|---|
|
|
The time when the information is logged. |
|
|
The process ID (PID). |
|
|
Resource manager ID |
|
|
Name of module |
|
|
Error returned as specified in the XA standard |
|
ORA-01017 |
Oracle Database information that was returned |
Topics:
Normally, the XA trace file is opened only if an error is detected. The xa_open string DbgFl provides a tracing facility to record additional detail about the XA library. By default, its value is zero. You can set it to any combination of these values:
0x1, which enables you to trace the entry and exit to each subprogram in the XA interface. This value can be useful in seeing exactly which XA calls the TP Monitor is making and which transaction identifier it is generating.
0x2, which enables you to trace the entry to and exit from other nonpublic XA library programs. This is generally of use only to Oracle Database developers.
0x4, which enables you to trace various other "interesting" calls made by the XA library, such as specific calls to the OCI. This is generally of use only to Oracle Database developers.
|
Note: The flags are independent bits of anub4, so to obtain printout from two or more flags, you must set a combined value of the flags. |
The XA application determines a location for the trace file according to this algorithm:
The LogDir directory specified in the open string.
If you do not specify LogDir in the open string, then the Oracle XA application attempts to create the trace file in this directory (if the Oracle home is accessible):
%ORACLE_HOME%\rdbms\trace on Windows
$ORACLE_HOME/rdbms/log on Linux and UNIX
If the Oracle XA application cannot determine where the Oracle home is located, then the application creates the trace file in the current working directory.
In-doubt or pending transactions are transactions that were prepared but not committed to the database. In general, the TM provided by the TPM system resolves any failure and recovery of in-doubt or pending transactions. The DBA might have to override an in-doubt transaction if these situations occur:
It is locking data that is required by other transactions.
It is not resolved in a reasonable amount of time.
See the TPM documentation for more information about overriding in-doubt transactions in such circumstances and about how to decide whether to commit or roll back the in-doubt transaction.
These views under the Oracle Database SYS account contain transactions generated by regular Oracle Database applications and Oracle XA applications:
DBA_PENDING_TRANSACTIONS
V$GLOBAL_TRANSACTION
DBA_2PC_PENDING
DBA_2PC_NEIGHBORS
For transactions generated by Oracle XA applications, this column information applies specifically to the DBA_2PC_NEIGHBORS table:
The DBID column is always xa_orcl
The DBUSER_OWNER column is always db_namexa.oracle.com
Remember that the db_name is always specified as DB=db_name in the open string. If you do not specify this field in the open string, then the value of this column is NULLxa.oracle.com for transactions generated by Oracle XA applications.
For example, this SQL statement provide more information about in-doubt transactions generated by Oracle XA applications:
SELECT * FROM DBA_2PC_PENDING p, DBA_2PC_NEIGHBORS n WHERE p.LOCAL_TRAN_ID = n.LOCAL_TRAN_ID AND n.DBID = 'xa_orcl';
Alternatively, if you know the format ID used by the transaction processing monitor, then you can use DBA_PENDING_TRANSACTIONS or V$GLOBAL_TRANSACTION. Whereas DBA_PENDING_TRANSACTIONS gives a list of prepared transactions, V$GLOBAL_TRANSACTION provides a list of all active global transactions.
Topics:
Oracle XA applications can access other Oracle Database instances through database links with these restrictions:
They must use the shared server configuration.
The transaction processing monitors (TPMs) use shared servers to open the connection to an Oracle Database A. Then the operating system network connection required for the database link is opened by the dispatcher instead of a dedicated server process. This allows different services or threads to operate on the transaction.
If this restriction is not satisfied, then when you use database links within an XA transaction, it creates an operating system network connection between the dedicated server process and the other Oracle Database B. Because this network connection cannot be moved from one dedicated server process to another, you cannot detach from this dedicated server process of database A. Then when you access the database B through a database link, you receive an ORA-24777 error.
The other database being accessed must be another Oracle Database.
If these restrictions are satisfied, Oracle Database allows such links and propagates the transaction protocol (prepare, rollback, and commit) to the other Oracle Database instances.
If using the shared server configuration is not possible, then access the remote database through the Pro*C/C++ application by using EXEC SQL AT syntax.
The init.ora parameter OPEN_LINKS_PER_INSTANCE specifies the number of open database link connections that can be migrated. These dblink connections are used by XA transactions so that the connections are cached after a transaction is committed. Another transaction can use the database link connection if the user who created the connection also created the transaction. This parameter is different from the init.ora parameter OPEN_LINKS, which specifies the maximum number of concurrent open connections (including database links) to remote databases in one session. The OPEN_LINKS parameter does not apply to XA applications.
Oracle Database transaction branches within the same global transaction can be coupled tightly or loosely. If the transaction branches are tightly coupled, then they share locks. Consequently, pre-COMMIT updates in one transaction branch are visible in other branches that belong to the same global transaction. In loosely coupled transaction branches, the branches do not share locks and do not see updates in other branches.
In a tightly coupled branch, Oracle Database obtains the DX lock before running any statement. Because the system does not obtain a lock before running the statement, loosely coupled transaction branches result in greater concurrency. The disadvantage is that all transaction branches must go through the two phases of commit, that is, the system cannot use XA one-phase optimization.
Table 15-9 summarizes the trade-offs between tightly coupled branches and loosely coupled branches.
As of Oracle Database 11g Release 1, an XA transaction can span Oracle RAC instances, allowing any application that uses XA to take full advantage of the Oracle RAC environment, enhancing the availability and scalability of the application.
|
Note: External procedure callouts combined with distributed transactions is not supported. |
Topics:
The initialization parameter GLOBAL_TXN_PROCESSES specifies the initial number of GTXn background processes for each Oracle RAC instance. Its default value is 1.
Leave this parameter at its default value clusterwide if distributed transactions might span multiple Oracle RAC instances. This allows the units of work performed across these Oracle RAC instances to share resources and act as a single transaction (that is, the units of work are tightly coupled). It also allows 2PC requests to be sent to any node in the cluster.
|
Note: This topic applies if either of the following is true:
|
Oracle Database permits different instances to operate on different transaction branches in Oracle RAC. For example, Node 1 can operate on branch A while Node 2 operates on branch B. Before Oracle Database 11g Release 1, if transaction branches were on different instances, then they were loosely coupled and did not share locks. In this case, Oracle Database treated different units of work in different application threads as separate entities that did not share resources.
A different case is when multiple instances operate on a single transaction branch. For example, assume that a single transaction lands on Node 1 and Node 2 as follows:
Node 1
xa_start
SQL operations
xa_end (SUSPEND)
Node 2
xa_start (RESUME)
xa_prepare
xa_commit
xa_end
In the immediately preceding sequence, Oracle Database returns an error because Node 2 must not resume a branch that is physically located on a different node (Node 1).
Before Oracle Database 11g Release 1, the way to achieve tight coupling in Oracle RAC was to use Distributed Transaction Processing (DTP) services, that is, services whose cardinality (one) ensured that all tightly-coupled branches landed on the same instance—regardless of whether load balancing was enabled. Middle-tier components addressed Oracle Database through a common logical database service name that mapped to a single Oracle RAC instance at any point in time. An intermediate name resolver for the database service hid the physical characteristics of the database instance. DTP services enabled all participants of a tightly-coupled global transaction to create branches on one instance.
As of Oracle Database 11g Release 1, the DTP service is no longer required to support XA transactions with tightly coupled branches. By default, tightly coupled branches that land on different Oracle RAC instances remain tightly coupled; that is, they share locks and resources across Oracle RAC instances.
For example, when you use a DTP service, this sequence of actions occurs on the same instance:
xa_start
SQL operations
xa_end (SUSPEND)
xa_start (RESUME)
SQL operations
xa_prepare
xa_commit or xa_rollback
Moreover, multiple tightly-coupled branches land on the same instance if each addresses the Oracle RM with the same DTP service.
To leverage all instances in the cluster, create multiple DTP services, with one or more on each node that hosts distributed transactions. All branches of a global distributed transaction exist on the same instance. Thus, you can leverage all instances and nodes of an Oracle RAC cluster to balance the load of many distributed XA transactions, thereby maximizing application throughput.
|
See Also: Oracle Real Application Clusters Administration and Deployment Guide to learn how to manage distributed transactions in a Real Application Clusters configuration |
Before Oracle Database 10g Release 2, TM was responsible for detecting failure and triggering failover and failback in Oracle RAC. To ensure that information about in-doubt transactions was propagated to DBA_2PC_PENDING, TM had to call xa_recover before resolving the in-doubt transactions. If an instance failed, then the XA client library could not fail over to another instance until it had run theSYS.DBMS_XA.DIST_TXN_SYNC procedure to ensure that the undo segments of the failed instance were recovered. As of Oracle Database 10g Release 2, there is no such requirement to call xa_recover in cases where the TM has enough information about in-flight transactions.
|
Note: As of Oracle Database 9g Release 2,xa_recover is required to wait for distributed data manipulation language (DML) statements to complete on remote sites. |
Using DTP services in Oracle RAC has these benefits:
Automates instance failure detection.
Automates instance failover and failback. When an instance fails, the DTP service hosted on this instance fails over to another instance. The fail% over forces clients to reconnect; nevertheless, the logical names for the service remain the same. Failover is automatic and does not require an administrator intervention. The administrator can induce failback by a service relocate statement, but all failback-related recovery is automatically handled within the database server.
Enables Oracle Database rather than the client to drive instance recovery. The database does not require middle-tier TM involvement to determine the state of transactions prepared by other instances.
|
See Also:
|
Before Oracle Database 11g Release 1, Oracle RAC database cannot determine whether a given XID is unique for XA transactions throughout the cluster.
For example, suppose that there is an XID Fmt(x).Tx(1).Br(1) on Oracle RAC instance 1 and another XID Fmt(x).Tx(1).Br(1) on Oracle RAC instance 2. Each of these can start a branch and run SQL even though the XID is not unique across Oracle RAC instances.
As of Oracle Database 11g Release 1, Oracle RAC database detects the duplicate XIDs across Oracle RAC instances and prevents a branch with a duplicate XID from starting.
|
See Also: Oracle Real Application Clusters Administration and Deployment Guide for information about services and distributed transaction processing in Oracle RAC |
Oracle Database transaction branches within the same global transaction can be coupled either tightly or loosely (for details, see "Managing Transaction Branches in Oracle XA Applications"). Ordinarily, coupling type is determined by the value of the Loose_Coupling field of the xa_open string (see Table 15-5). However, if branches are landed on different Oracle RAC instances when running Oracle RAC, they are loosely coupled even if Loose_Coupling=false.
|
See Also: Oracle Real Application Clusters Administration and Deployment Guide for information about services and distributed transaction processing in Oracle RAC |
This section describes restrictions concerning these SQL operations:
Because the transaction manager is responsible for coordinating and monitoring the progress of the global transaction, the application must not contain any Oracle Database-specific statement that independently rolls back or commits a global transaction. However, you can use rollbacks and commits in a local transaction.
Do not use EXEC SQL ROLLBACK WORK for precompiler applications when you are in the middle of a global transaction. Similarly, an OCI application must not run OCITransRollback, or the Version 7 equivalent orol. You can roll back a global transaction by calling tx_rollback.
Similarly, a precompiler application must not have the EXEC SQL COMMIT WORK statement in the middle of a global transaction. An OCI application must not run OCITransCommit or the Version 7 equivalent ocom. For example, use tx_commit or tx_rollback to end a global transaction.
Because a data definition language (DDL) statement, such as CREATE TABLE, implies an implicit commit, the Oracle XA application cannot run any DDL statements.
Oracle Database does not guarantee that session state is valid between TPM services. For example, if a TPM service updates a session variable (such as a global package variable), then another TPM service that runs as part of the same global transaction might not see the change. Use savepoints only within a TPM service. The application must not refer to a savepoint that was created in another TPM service. Similarly, an application must not attempt to fetch from a cursor that was executed in another TPM service.
Do not use the EXEC SQL statement to connect or disconnect. That is, do not use EXEC SQL CONNECT, EXEC SQL COMMIT WORK RELEASE or EXEC SQL ROLLBACK WORK RELEASE.
You cannot use both Oracle XA and a gateway in the same session.
Oracle Database does not support association migration (a means whereby a transaction manager might resume a suspended branch association in another branch).
The optional XA feature asynchronous XA calls is not supported.
Set the TRANSACTIONS initialization parameter to the expected number of concurrent global transactions. The initialization parameter OPEN_LINKS_PER_INSTANCE specifies the number of open database link connections that can be migrated. These database link connections are used by XA transactions so that the connections are cached after a transaction is committed.
The maximum number of xa_open calls for each thread is 32.
When building an XA application based on TP-monitor, ensure that the TP-monitors libraries (that define the symbols ax_reg and ax_unreg) are placed in the link line before Oracle Database's client shared library. If your platform does not support shared libraries or if your linker is not sensitive to ordering of libraries in the link line, use Oracle Database's nonshared client library. These link restrictions are applicable only when using XA's dynamic registration (Oracle XA switch xaoswd).
To choose a programming environment for a development project, read:
The topics in this chapter and the documents to which they refer.
The platform-specific documents that explain which compilers and development tools your platforms support.
Sometimes the choice of programming environment is obvious, for example:
Pro*COBOL does not support ADTs or collection types, while Pro*C/C++ does.
SQLJ does not support dynamic SQL the way that JDBC does.
If no programming language provides all the features you need, you can use multiple programming languages, because:
Every programming language in this chapter can invoke PL/SQL and Java stored subprograms. (Stored subprograms include triggers and ADT methods.)
PL/SQL, Java, SQL, and Oracle Call Interface (OCI) can invoke external C subprograms.
External C subprograms can access Oracle Database using SQL, OCI, or Pro*C (but not C++).
For more information about multilanguage programming, see Chapter 14, "Developing Applications with Multiple Programming Languages."
Topics:
In this topic, application architecture refers to the computing environment in which a database application connects to an Oracle Database.
Topics:
In a traditional client/server program, your application code runs on a client system; that is, a system other than the database server. Database calls are transmitted from the client system to the database server. Data is transmitted from the client to the server for insert and update operations and returned from the server to the client for query operations. The data is processed on the client system. Client/server programs are typically written by using precompilers, whereas SQL statements are embedded within the code of another language such as C, C++, or COBOL.
You can develop application logic that resides entirely inside the database by using triggers that are executed automatically when changes occur in the database or stored subprograms that are invoked explicitly. Off-loading the work from your application lets you reuse code that performs verification and cleanup and control database operations from a variety of clients. For example, by making stored subprograms invocable through a web server, you can construct a web-based user interface that performs the same functions as a client/server application.
Client/server computing is often referred to as a two-tier model: your application communicates directly with the database server. In the three-tier model, a separate application server processes the requests. The application server might be a basic web server, or might perform advanced functions like caching and load-balancing. Increasing the processing power of this middle tier lets you lessen the resources needed by client systems, resulting in a thin client configuration in which the client system might need only a web browser or other means of sending requests over the TCP/IP or HTTP protocols.
The program interface is the software layer between a database application and Oracle Database. The program interface:
Provides a security barrier, preventing destructive access to the SGA by client user processes
Acts as a communication mechanism, formatting information requests, passing data, and trapping and returning errors
Converts and translates data, particularly between different types of computers or to external user program data types
The Oracle code acts as a server, performing database tasks on behalf of an application (a client), such as fetching rows from data blocks. The program interface consists of several parts, provided by both Oracle Database software and operating system-specific software.
Topics:
The user interface is what your application displays to end users. It depends on the technology behind the application and the needs of the users themselves. Experienced users can enter SQL statements that are passed on to the database. Novice users can be shown a graphical user interface that uses the graphics libraries of the client system (such as Windows or X-Windows). Any of these traditional user interfaces can also be provided in a web browser through HTML and Java.
In traditional client/server applications, the application can keep a record of user actions and use this information over the course of one or more sessions. For example, past choices can be presented in a menu so that they do not have to be entered again. When the application can save information in this way, the application is considered stateful.
Web or thin-client applications that are stateless are easier to develop. Stateless applications gather all the required information, process it using the database, and then start over with the next user. This is a popular way to process single-screen requests such as customer registration.
There are many ways to add stateful action to web applications that are stateless by default. For example, an entry form on one web page can pass information to subsequent web pages, enabling you to construct a wizard-like interface that remembers user choices through several different steps. You can use cookies to store small items of information about the client system, and retrieve them when the user returns to a web site. You can use servlets to keep a database session open and store variables between requests from the same client.
PL/SQL, the Oracle procedural extension of SQL, is a completely portable, high-performance transaction-processing language. PL/SQL lets you manipulate data with SQL statements; control program flow with conditional selection and loops; declare constants and variables; define subprograms; define types, subtypes, and ADTs and declare variables of those types; and trap runtime errors.
Applications written in any of the Oracle Database programmatic interfaces can invoke PL/SQL stored subprograms and send blocks of PL/SQL code to Oracle Database for execution. Third-generation language (3GL) applications can access PL/SQL scalar and composite data types through host variables and implicit data type conversion. A 3GL language is easier than assembler language for a human to understand and includes features such as named variables. Unlike a fourth-generation language (4GL), it is not specific to an application domain.
You can use PL/SQL to develop stored procedures that can be invoked by a web client.
|
See Also:
|
This section provides an overview of Oracle Database features that support Java applications. The database includes the core JDK libraries such as java.lang, java.io, and so on. The database supports client-side Java standards such as JDBC and SQLJ, and provides server-side JDBC and SQLJ drivers that enable data-intensive Java code to run within the database.
Topics:
Oracle JVM, the Java Virtual Machine provided with the Oracle Database, is compliant with the J2SE version 1.5.x specification and supports the database session architecture.
Any database session can activate a dedicated JVM. All sessions share the same JVM code and statics; however, private states for any given session are held, and subsequently garbage collected, in an individual session space.
This design provides these benefits:
Java applications have the same session isolation and data integrity as SQL operations.
You need not run Java in a separate process for data integrity.
Oracle JVM is a robust JVM with a small memory footprint.
The JVM has the same linear Symmetric Multiprocessing (SMP) scalability as the database and can support thousands of concurrent Java sessions.
Oracle JVM works consistently with every platform supported by Oracle Database. Java applications that you develop with Oracle JVM can easily be ported to any supported platform.
Oracle JVM includes a deployment-time native compiler that enables Java code to be compiled once, stored in executable form, shared among users, and invoked more quickly and efficiently.
Security features of the database are also available with Oracle JVM. Java classes must be loaded in a database schema (by using Oracle JDeveloper, a third-party IDE, SQL*Plus, or the loadjava utility) before they can be called. Java class calls are secured and controlled through database authentication and authorization, Java 2 security, and invoker's rights (IR) or definer's rights (DR).
Java Database Connectivity (JDBC) is an Applications Programming Interface (API) that enables Java to send SQL statements to an object-relational database such as Oracle Database.
Oracle Database includes these extensions to the JDBC 1.22 standard:
Support for Oracle data types
Performance enhancement by row prefetching
Performance enhancement by execution batching
Specification of query column types to save round-trips
Control of DatabaseMetaData calls
Oracle Database supports all APIs from the JDBC 2.0 standard, including the core APIs, optional packages, and numerous extensions. Some highlights include datasources, JTA, and distributed transactions.
Oracle Database supports these features from the JDBC 3.0 standard:
Support for JDK 1.5.
Toggling between local and global transactions.
Transaction savepoints.
Reuse of prepared statements by connection pools.
|
Note: JDBC code and SQLJ code interoperate. For more information, see "Comparing Oracle JDBC and Oracle SQLJ".) |
Topics:
|
See Also: Oracle Database Concepts for additional general information about Java support in Oracle Database |
The JDBC standard defines four types of JDBC drivers:
| Type | Description |
|---|---|
| 1 | A JDBC-ODBC bridge. Software must be installed on client systems. |
| 2 | Native methods (calls C or C++) and Java methods. Software must be installed on the client. |
| 3 | Pure Java. The client uses sockets to call middleware on the server. |
| 4 | The most pure Java solution. Talks directly to the database by using Java sockets. |
JDBC is based on Part 3 of the SQL standard, "Call-Level Interface."
You can use JDBC to do dynamic SQL. In dynamic SQL, the embedded SQL statement to be executed is not known before the application is run and requires input to build the statement.
The drivers that are implemented by Oracle have extensions to the capabilities in the JDBC standard that was defined by Sun Microsystems.
Topics:
|
See Also:
|
The JDBC thin driver is a Type 4 (100% pure Java) driver that uses Java sockets to connect directly to a database server. It has its own implementation of a Two-Task Common (TTC), a lightweight implementation of TCP/IP from Oracle Net. It is written entirely in Java and is therefore platform-independent.
The thin driver does not require Oracle software on the client side. It does need a TCP/IP listener on the server side. Use this driver in Java applets that are downloaded into a web browser or in applications for which you do not want to install Oracle client software. The thin driver is self-contained, but it opens a Java socket, and thus can only run in a browser that supports sockets.
The JDBC OCI driver is a Type 2 JDBC driver. It makes calls to OCI written in C to interact with Oracle Database, thus using native and Java methods.
The OCI driver provides access to more features than the thin driver, such as Transparent Application Fail-Over, advanced security, and advanced LOB manipulation.
The OCI driver provides the highest compatibility between different Oracle Database versions. It also supports all installed Oracle Net adapters, including IPC, named pipes, TCP/IP, and IPX/SPX.
Because it uses native methods (a combination of Java and C) the OCI driver is platform-specific. It requires a client installation of version Oracle8i or later including Oracle Net, OCI libraries, CORE libraries, and all other dependent files. The OCI driver usually runs faster than the thin driver.
The OCI driver is not appropriate for Java applets, because it uses a C library that is platform-specific and cannot be downloaded into a web browser. It is usable in J2EE components running in middle-tier application servers, such as Oracle Application Server. Oracle Application Server provides middleware services and tools that support access between applications and browsers.
The JDBC server-side internal driver is a Type 2 driver that runs inside the database server, reducing the number of round-trips needed to access large amounts of data. The driver, the Java server VM, the database, the Java native compiler (which speeds execution by as much as 10 times), and the SQL engine all run within the same address space.
This driver provides server-side support for any Java program used in the database. You can also call PL/SQL stored subprograms and triggers.
The server driver fully supports the same features and extensions as the client-side drivers.
This example shows the recommended technique for looking up a data source using JNDI in JDBC 2.0:
// import the JDBC packages
import java.sql.*;
import javax.sql.*;
import oracle.jdbc.pool.*;
...
InitialContext ictx = new InitialContext();
DataSource ds = (DataSource)ictx.lookup("jdbc/OracleDS");
Connection conn = ds.getConnection();
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT last_name FROM employees");
while ( rs.next() ) {
out.println( rs.getString("ename") + "<br>");
}
conn.close();
This source code registers an Oracle JDBC thin driver, connects to the database, creates a Statement object, runs a query, and processes the result set.
The SELECT statement retrieves and lists the contents of the last_name column of the hr.employees table.
import java.sql.*
import java.math.*
import java.io.*
import java.awt.*
class JdbcTest {
public static void main (String args []) throws SQLException {
// Load Oracle driver
DriverManager.registerDriver (new oracle.jdbc.OracleDriver());
// Connect to the local database
Connection conn =
DriverManager.getConnection ("jdbc:oracle:thin:@myhost:1521:orcl",
"hr", "password");
// Query the employee names
Statement stmt = conn.createStatement ();
ResultSet rset = stmt.executeQuery ("SELECT last_name FROM employees");
// Print the name out
while (rset.next ())
System.out.println (rset.getString (1));
// Close the result set, statement, and the connection
rset.close();
stmt.close();
conn.close();
}
}
One Oracle Database extension to the JDBC drivers is a form of the getConnection() method that uses a Properties object. The Properties object lets you specify user, password, database information, row prefetching, and execution batching.
To use the OCI driver in this code, replace the Connection statement with this code, where MyHostString is an entry in the tnsnames.ora file:
Connection conn = DriverManager.getConnection ("jdbc:oracle:oci8:@MyHostString",
"hr", "password");
If you are creating an applet, then the getConnection() and registerDriver() strings are different.
|
Note: In this document, SQLJ refers to Oracle SQLJ and its extensions. |
SQLJ is an ANSI SQL-1999 standard for embedding SQL statements in Java source code. SQLJ provides a simpler alternative to JDBC for both client-side and server-side SQL data access from Java.
A SQLJ source file contains Java source with embedded SQL statements. Oracle SQLJ supports dynamic and static SQL. Support for dynamic SQL is an Oracle extension to the SQLJ standard.
Oracle Database provides a translator and a run time driver to support SQLJ. The SQLJ translator is 100% pure Java and is portable to any JVM that is compliant with JDK version 1.1 or higher.
The Oracle SQLJ translator performs these tasks:
Translates SQLJ source to Java code with calls to the SQLJ run time driver. The SQLJ translator converts the source code to pure Java source code and can check the syntax and semantics of static SQL statements against a database schema and verify the type compatibility of host variables with SQL types.
Compiles the generated Java code with the Java compiler.
(Optional) Creates profiles for the target database. SQLJ generates "profile" files with customization specific to Oracle Database.
Oracle Database sup ports SQLJ stored subprograms and triggers that run in the Oracle JVM. SQLJ is integrated with JDeveloper. Source-level debugging support for SQLJ is available in JDeveloper.
This is an example of a simple SQLJ executable statement, which returns one value because employee_id is unique in the employee table:
String name;
#sql { SELECT first_name INTO :name FROM employees WHERE employee_id=112 };
System.out.println("Name is " + name + ", employee number = " + employee_id);
Each host variable (or qualified name or complex Java host expression) included in a SQL expression is preceded by a colon (:). Other SQLJ statements declare Java types. For example, you can declare an iterator (a construct related to a database cursor) for queries that retrieve many values, as follows:
#sql iterator EmpIter (String EmpNam, int EmpNumb);
|
See Also: Oracle Database JPublisher User's Guide for more examples and details about Oracle SQLJ syntax |
Topics:
Oracle SQLJ extensions to Java enable rapid development and easy maintenance of applications that perform database operations through embedded SQL.
In particular, Oracle SQLJ does this:
Provides a concise, legible mechanism for database access from static SQL. Most SQL in applications is static. SQLJ provides more concise and less error-prone static SQL constructs than JDBC does.
Provides an SQL Checker module for verification of syntax and semantics at translate time.
Provides flexible deployment configurations, which makes it possible to implement SQLJ on the client, server, or middle tier.
Supports a software standard. SQLJ is an effort of a group of vendors and is supported by all of them. Applications can access multiple database vendors.
Provides source code portability. Executables can be used with all of the vendor DBMSs if the code does not rely on any vendor-specific features.
Enforces a uniform programming style for the clients and the servers.
Integrates the SQLJ translator with Oracle JDeveloper, a graphical IDE that provides SQLJ translation, Java compilation, profile customizing, and debugging at the source code level, all in one step.
Includes Oracle Database type extensions.
SQLJ applications can be stored and executed in the server by using these techniques:
Translate, compile, and customize the SQLJ source code on a client and load the generated classes and resources into the server with the loadjava utility. The classes are typically stored in a Java archive (.jar) file.
Load the SQLJ source code into the server, also using loadjava, where it is translated and compiled by the server's embedded translator.
JDBC code and SQLJ code interoperate, enabling dynamic SQL statements in JDBC to be used with both static and dynamic SQL statements in SQLJ. A SQLJ iterator class corresponds to the JDBC result set.
Some differences between JDBC and SQLJ are:
JDBC provides a complete dynamic SQL interface from Java to databases. It gives developers full control over database operations. SQLJ simplifies Java database programming to improve development productivity.
JDBC provides fine-grained control of the execution of dynamic SQL from Java, whereas SQLJ provides a higher-level binding to SQL operations in a specific database schema.
SQLJ source code is more concise than equivalent JDBC source code.
SQLJ uses database connections to type-check static SQL code. JDBC, being a completely dynamic API, does not.
SQLJ provides strong typing of query outputs and return parameters and provides type-checking on calls. JDBC passes values to and from SQL without compile-time type checking.
SQLJ programs enable direct embedding of Java bind expressions within SQL statements. JDBC requires a separate get or set statement for each bind variable and specifies the binding by position number.
SQLJ provides simplified rules for calling SQL stored subprograms.
For example, the following four examples show, on successive lines, how to call a stored procedure or a stored function using either JDBC escape syntax or Oracle JDBC syntax:
prepStmt.prepareCall("{call fun(?,?)}"); //stored proc. JDBC esc.
prepStmt.prepareCall("{? = call fun(?,?)}"); //stored func. JDBC esc.
prepStmt.prepareCall("begin fun(:1,:2);end;"); //stored proc. Oracle
prepStmt.prepareCall("begin :1 := fun(:2,:3);end;"); //stored func. Oracle
The SQLJ equivalent is:
#sql {call fun(param_list) }; //Stored procedure
// Declare x
...
#sql x = {VALUES(fun(param_list)) }; // Stored function
// where VALUES is the SQL construct
These benefits are common to SQLJ and JDBC:
SQLJ source files can contain JDBC calls. SQLJ and JDBC are interoperable.
Oracle JPublisher generates custom Java classes to be used in your SQLJ or JDBC application for mappings to Oracle Database ADTs and collections.
PL/SQL and Java stored subprograms can be used interchangeably.
Oracle JPublisher is a code generator that automates the process of creating database-centric Java classes by hand. Oracle JPublisher is a client-side utility and is built into the database system. You can run Oracle JPublisher from the command line or directly from the Oracle JDeveloper IDE.
Oracle JPublisher inspects PL/SQL packages and database object types such as ADTs, VARRAY types, and nested table types, and then generates a Java class that is a wrapper around the PL/SQL package with corresponding fields and methods.
The generated Java class can be incorporated and used by Java clients or J2EE components to exchange and transfer database object type instances to and from the database transparently.
|
See Also:
|
Java stored subprograms enable you to implement programs that run in the database server and are independent of programs that run in the middle tier. Structuring applications in this way reduces complexity and increases reuse, security, performance, and scalability.
For example, you can create a Java stored subprogram that performs operations that require data persistence and a separate program to perform presentation or business logic operations.
Java stored subprograms interface with SQL using an execution model similar to that of PL/SQL.
|
See Also:
|
Web services represent a distributed computing paradigm for Java application development that is an alternative to earlier Java protocols such as JDBC, and which enable applications to interact through the XML and web protocols. For example, an electronics parts vendor can provide a web-based programmatic interface to its suppliers for inventory management. The vendor can invoke a web service as part of a program and automatically order stock based on the data returned.
The key technologies used in web services are:
Web Services Description Language (WSDL), which is a standard format for creating an XML document. WSDL describes what a web service can do, where it resides, and how to invoke it. Specifically, it describes the operations and parameters, including parameter types, provided by a web service. In addition, a WSDL document describes the location, the transport protocol, and the invocation style for the web service.
Simple Object Access Protocol (SOAP) messaging, which is an XML-based message protocol used by web services. SOAP does not prescribe a specific transport mechanism such as HTTP, FTP, SMTP, or JMS; however, most web services accept messages that use HTTP or HTTPS.
Universal Description, Discovery, and Integration (UDDI) business registry, which is a directory that lists web services on the internet. The UDDI registry is often compared to a telephone directory, listing unique identifiers (white pages), business categories (yellow pages), and instructions for binding to a service protocol (green pages).
Web services can use a variety of techniques and protocols. For example:
Dispatching can occur in a synchronous (typical) or asynchronous manner.
You can invoke a web service in an RPC-style operation in which arguments are sent and a response returned, or in a message style such as a one-way SOAP document exchange.
You can use different encoding rules: literal or encoded.
You can invoke a web service statically, when you might know everything about it beforehand, or dynamically, in which case you can discover its operations and transport endpoints while using it.
Oracle Database can function as either a web service provider or as a web service consumer. When used as a provider, the database enables sharing and disconnected access to stored subprograms, data, metadata, and other database resources such as the queuing and messaging systems.
As a web service provider, Oracle Database provides a disconnected and heterogeneous environment that:
Exposes stored subprograms independently of the language in which the subprograms are written
Exposes SQL Queries and XQuery
|
See Also: Oracle Database Concepts for additional general information about Oracle Database as a web service provider |
PL/SQL and Java interoperate in the server. You can run a PL/SQL package from Java or wrap a PL/SQL class with a Java wrapper so that it can be invoked from distributed CORBA and Enterprise Java Beans clients.
Table 13-1 shows PL/SQL packages and their Java equivalents.
Table 13-1 PL/SQL Packages and Their Java Equivalents
| PL/SQL Package | Java Equivalent |
|---|---|
|
|
Call package with SQLJ or JDBC. |
|
|
JDBC has this functionality. |
|
|
Schedule a job that has a Java stored subprogram. |
|
|
Call with SQLJ or JDBC. |
|
|
Use JavaMail. |
|
|
Use subclass |
|
|
Call with SQLJ or JDBC. |
|
|
Use JDBC to run an |
|
|
Call with SQLJ or JDBC. |
|
|
Use JDBC. |
|
|
Use JDBC to run an |
|
|
Call with SQLJ or JDBC. |
|
|
Grant the |
Topics:
Both PL/SQL and Java provide packages and libraries.
Both PL/SQL and Java have object-oriented features:
Both have inheritance.
PL/SQL has type evolution, the ability to change methods and attributes of a type while preserving subtypes and table data that use the type.
Java has polymorphism and component models for developing distributed systems.
As an extension of SQL, PL/SQL supports all SQL data types, data encapsulation, information hiding, overloading, and exception-handling. Therefore:
SQL data types are easier to use in PL/SQL than in Java.
SQL operations are faster with PL/SQL than with Java, especially when a large amount of data is involved, when mostly database access is done, or when bulk operations are used.
Some advanced PL/SQL capabilities are not available for Java in Oracle9i (for example, autonomous transactions and the dblink facility for remote databases).
Code development is usually faster in PL/SQL than in Java.
Java is used for open distributed applications, and many Java-based development tools are available throughout the industry. Java has a richer type system than PL/SQL. Java can use CORBA (which can have many different computer languages in its clients) and Enterprise Java Beans. PL/SQL packages can be invoked from CORBA or Enterprise Java Beans clients. You can run XML tools, the Internet File System, or JavaMail from Java.
Client/server programs are typically written using precompilers, which are programming tools that let you embed SQL statements in high-level programs written in languages such as C, C++, or COBOL. Because the client application hosts the SQL statements, it is called a host program, and the language in which it is written is called the host language.
A precompiler accepts the host program as input, translates the embedded SQL statements into standard database runtime library calls, and generates a source program that you can compile, link, and run in the usual way.
Topics:
For the Pro*C/C++ precompiler, the host language is either C or C++. Some features of the Pro*C/C++ precompiler are:
You can write multithreaded programs if your platform supports a threads package. Concurrent connections are supported in either single-threaded or multithreaded applications.
You can improve performance by embedding PL/SQL blocks. These blocks can invoke subprograms in Java or PL/SQL that are written by you or provided in Oracle Database packages.
Using precompiler options, you can check the syntax and semantics of your SQL or PL/SQL statements during precompilation, and at run time.
You can invoke stored PL/SQL and Java subprograms. Modules written in COBOL or in C can be invoked from Pro*C/C++. External C subprograms in shared libraries can be invoked by your program.
You can conditionally precompile sections of your code so that they can run in different environments.
You can use arrays, or structures, or arrays of structures as host and indicator variables in your code to improve performance.
You can deal with errors and warnings so that data integrity is guaranteed. As a programmer, you control how errors are handled.
Your program can convert between internal data types and C language data types.
The Oracle Call Interface (OCI) and Oracle C++ Call Interface (OCCI), lower-level C and C++ interfaces, are available for use in your precompiler source.
Pro*C/C++ supports dynamic SQL, a technique that enables users to input variable values and statement syntax.
Pro*C/C++ can use special SQL statements to manipulate tables containing user-defined object types. An Object Type Translator (OTT) maps the ADTs and named collection types in your database to structures and headers that you include in your source.
Two kinds of collection types, nested tables and VARRAY, are supported with a set of SQL statements that give you a high degree of control over data.
Large Objects are accessed by another set of SQL statements.
A new ANSI SQL standard for dynamic SQL is supported for new applications, so that you can run SQL statements with a varying number of host variables. An older technique for dynamic SQL is still usable by pre-existing applications.
Globalization support lets you use multibyte characters and UCS2 Unicode data.
Using scrollable cursors, you can move backward and forward through a result set. For example, you can fetch the last row of the result set, or jump forward or backward to an absolute or relative position within the result set.
A connection pool is a group of physical connections to a database that can be shared by several named connections. Enabling the connection pool option can help optimize the performance of Pro*C/C++ application. The connection pool option is not enabled by default.
|
See Also: Pro*C/C++ Precompiler Programmer's Guide for complete information about the Pro*C/C++ precompiler |
Example 13-1 is a code fragment from a C source program that queries the table employees in the schema hr.
Example 13-1 Pro*C/C++ Application
...
#define UNAME_LEN 10
...
int emp_number;
/* Define a host structure for the output values of a SELECT statement. */
/* No declare section needed if precompiler option MODE=ORACLE */
struct {
VARCHAR last_name[UNAME_LEN];
float salary;
float commission_pct;
} emprec;
/* Define an indicator structure to correspond to the host output structure. */
struct {
short emp_name_ind;
short sal_ind;
short comm_ind;
} emprec_ind;
...
/* Select columns last_name, salary, and commission_pct given the user's input
/* for employee_id. */
EXEC SQL SELECT last_name, salary, commission_pct
INTO :emprec INDICATOR :emprec_ind
FROM employees
WHERE employee_id = :emp_number;
...
The embedded SELECT statement differs slightly from the interactive (SQL*Plus) SELECT statement. Every embedded SQL statement begins with EXEC SQL. The colon (:) precedes every host (C) variable. The returned values of data and indicators (set when the data value is NULL or character columns were truncated) can be stored in structs (such as in the preceding code fragment), in arrays, or in arrays of structs. Multiple result set values are handled very simply in a manner that resembles the case shown, where there is only one result, because of the unique employee number. Use the actual names of columns and tables in embedded SQL.
Either use the default precompiler option values or enter values that give you control over the use of resources, how errors are reported, the formatting of output, and how cursors (which correspond to a particular connection or SQL statement) are managed. Cursors are used when there are multiple result set values.
Enter the options either in a configuration file, on the command line, or inline inside your source code with a special statement that begins with EXEC ORACLE. If there are no errors found, you can compile, link, and run the output source file, like any other C program that you write.
Use the precompiler to create server database access from clients that can be on many different platforms. Pro*C/C++ gives you the freedom to design your own user interfaces and to add database access to existing applications.
Before writing your embedded SQL statements, you can test interactive versions of the SQL in SQL*Plus and then make minor changes to start testing your embedded SQL application.
For the Pro*COBOL precompiler, the host language is COBOL. Some features of the Pro*COBOL precompiler are:
You can invoke stored PL/SQL or Java subprograms. You can improve performance by embedding PL/SQL blocks. These blocks can invoke PL/SQL subprograms written by you or provided in Oracle Database packages.
Precompiler options enable you to define how cursors, errors, syntax-checking, file formats, and so on, are handled.
Using precompiler options, you can check the syntax and semantics of your SQL or PL/SQL statements during precompilation, and at run time.
You can conditionally precompile sections of your code so that they can run in different environments.
Use tables, or group items, or tables of group items as host and indicator variables in your code to improve performance.
You can program how errors and warnings are handled, so that data integrity is guaranteed.
Pro*COBOL supports dynamic SQL, a technique that enables users to input variable values and statement syntax.
Example 13-2 is a code fragment from a COBOL source program that queries the table employees in the schema hr.
Example 13-2 Pro*COBOL Application
...
WORKING-STORAGE SECTION.
*
* DEFINE HOST INPUT AND OUTPUT HOST AND INDICATOR VARIABLES.
* NO DECLARE SECTION NEEDED IF MODE=ORACLE.
*
01 EMP-REC-VARS.
05 EMP-NAME PIC X(10) VARYING.
05 EMP-NUMBER PIC S9(4) COMP VALUE ZERO.
05 SALARY PIC S9(5)V99 COMP-3 VALUE ZERO.
05 COMMISSION PIC S9(5)V99 COMP-3 VALUE ZERO.
05 COMM-IND PIC S9(4) COMP VALUE ZERO.
...
PROCEDURE DIVISION.
...
EXEC SQL
SELECT last_name, salary, commission_pct
INTO :EMP-NAME, :SALARY, :COMMISSION:COMM-IND
FROM employees
WHERE employee_id = :EMP-NUMBER
END-EXEC.
...
The embedded S ELECT statement is only slightly different from an interactive (SQL*Plus) SELECT statement. Every embedded SQL statement begins with EXEC SQL. The colon (:) precedes every host (COBOL) variable. The SQL statement is terminated by END-EXEC. The returned values of data and indicators (set when the data value is NULL or character columns were truncated) can be stored in group items (such as in the preceding code fragment), in tables, or in tables of group items. Multiple result set values are handled very simply in a manner that resembles the case shown, where there is only one result, given the unique employee number. Use the actual names of columns and tables in embedded SQL.
Use the default precompiler option values, or enter values that give you control over the use of resources, how errors are reported, the formatting of output, and how cursors are managed (cursors correspond to a particular connection or SQL statement).
Enter the options in a configuration file, on the command line, or inline inside your source code with a special statement that begins with EXEC ORACLE. If there are no errors found, you can compile, link, and run the output source file, like any other COBOL program that you write.
Use the precompiler to create server database access from clients that can be on many different platforms. Pro*COBOL gives you the freedom to design your own user interfaces and to add database access to existing COBOL applications.
The embedded SQL statements available conform to an ANSI standard, so that you can access data from many databases in a program, including remote servers networked through Oracle Net.
Before writing your embedded SQL statements, you can test interactive versions of the SQL in SQL*Plus and then make minor changes to start testing your embedded SQL application.
The Oracle Call Interface (OCI) and Oracle C++ Call Interface (OCCI) are application programming interfaces (APIs) that enable you to create applications that use native subprogram invocations of a third-generation language to access Oracle Database and control all phases of SQL statement execution. These APIs provide:
Improved performance and scalability through the efficient use of system memory and network connectivity
Consistent interfaces for dynamic session and transaction management in a two-tier client/server or multitier environment
N-tiered authentication
Comprehensive support for application development using Oracle Database objects
Access to external databases
Ability to develop applications that service an increasing number of users and requests without additional hardware investments
OCI lets you manipulate data and schemas in a database using a host programming language, such as C. OCCI is an object-oriented interface suitable for use with C++. These APIs provide a library of standard database access and retrieval functions in the form of a dynamic runtime library (OCILIB) that can be linked in an application at run time. You need not embed SQL or PL/SQL within 3GL programs.
|
See Also: For more information about OCI and OCCI calls: |
Topics:
OCI and OCCI provide significant advantages over other methods of accessing Oracle Database:
More fine-grained control over all aspects of the application design.
High degree of control over program execution.
Use of familiar 3GL programming techniques and application development tools such as browsers and debuggers.
Support of dynamic SQL, method 4.
Availability on the broadest range of platforms of all the Oracle Database programmatic interfaces.
Dynamic bind and define using callbacks.
Describe functionality to expose layers of server metadata.
Asynchronous event notification for registered client applications.
Enhanced array data manipulation language (DML) capability for arrays.
Ability to associate a commit request with an run to reduce round-trips.
Optimization for queries using transparent prefetch buffers to reduce round-trips.
Thread safety, so you do not have to implement mutual exclusion (mutex) locks on OCI and OCCI handles.
The server connection in nonblocking mode means that control returns to the OCI or OCCI code when a call is still running or cannot complete.
Both OCI and OCCI have four kinds of functions:
| Kind of Function | Purpose |
|---|---|
| Relational | To manage database access and process SQL statements |
| Navigational | To manipulate objects retrieved from the database |
| Database mapping and manipulation | To manipulate data attributes of Oracle Database types |
| External subprogram | To write C callbacks from PL/SQL |
OCI and OCCI enable you to develop applications that combine the nonprocedural data access power of SQL with the procedural capabilities of most programming languages, including C and C++. Procedural and nonprocedural languages have these characteristics:
In a nonprocedural language program, the set of data to be operated on is specified, but what operations are performed and how the operations are to be carried out is not specified. The nonprocedural nature of SQL makes it an easy language to learn and to use to perform database transactions. It is also the standard language used to access and manipulate data in modern relational and object-relational database systems.
In a procedural language program, the execution of most statements depends on previous or subsequent statements and on control structures, such as loops or conditional branches, which are not available in SQL. The procedural nature of these languages makes them more complex than SQL, but it also makes them very flexible and powerful.
The combination of both nonprocedural and procedural language elements in an OCI or OCCI program provides easy access to Oracle Database in a structured programming environment.
OCI and OCCI support all SQL data definition, data manipulation, query, and transaction control facilities that are available through Oracle Database. For example, an OCI or OCCI program can run a query against Oracle Database. The queries can require the program to supply data to the database using input (bind) variables, as follows:
SELECT name FROM employees WHERE empno = :empnumber
In the preceding SQL statement, :empnumber is a placeholder for a value to be supplied by the application.
Alternatively, you can use PL/SQL, Oracle's procedural extension to SQL. The applications you develop can be more powerful and flexible than applications written in SQL alone. OCI and OCCI also provide facilities for accessing and manipulating objects in Oracle Database.
As Figure 13-1 shows, you compile and link an OCI or OCCI program in the same way that you compile and link a nondatabase application. There is no need for a separate preprocessing or precompilation step.
Figure 13-1 The OCI or OCCI Development Process
|
Note: To properly link your OCI and OCCI programs, it might be necessary on some platforms to include other libraries, in addition to the OCI and OCCI libraries. Check your Oracle platform-specific documentation for further information about extra libraries that might be required. |
Precompiler applications typically contain less code than equivalent OCI applications, which can help productivity.
Some situations require detailed control of the database and are suited for OCI applications (either pure OCI or a precompiler application with embedded OCI calls):
OCI provides more detailed control over multiplexing and migrating sessions.
OCI provides dynamic bind and define using callbacks that can be used for any arbitrary structure, including lists.
OCI has many calls to handle metadata.
OCI enables asynchronous event notifications to be received by a client application. It provides a means for clients to generate notifications for propagation to other clients.
OCI enables DML statements to use arrays to complete as many iterations as possible before returning any error messages.
OCI calls for special purposes include Advanced Queuing, globalization support, Data Cartridges, and support of the date and time data types.
OCI calls can be embedded in a Pro*C/C++ application.
Oracle Data Provider for .NET (ODP.NET) is an implementation of a data provider for Oracle Database.
ODP.NET uses APIs native to Oracle Database to offer fast and reliable access from any .NET application to database features and data. It also uses and inherits classes and interfaces available in the Microsoft .NET Framework Class Library.
For programmers using Oracle Provider for OLE DB, ADO (ActiveX Data Objects) provides an automation layer that exposes an easy programming model. ADO.NET provides a similar programming model, but without the automation layer, for better performance. More importantly, the ADO.NET model enables native providers such as ODP.NET to expose specific features and data types specific to Oracle Database.
This is a simple C# application that connects to Oracle Database and displays its version number before disconnecting:
using System;
using Oracle.DataAccess.Client;
class Example
{
OracleConnection con;
void Connect()
{
con = new OracleConnection();
con.ConnectionString = "User Id=hr;Password=password;Data Source=oracle";
con.Open();
Console.WriteLine("Connected to Oracle" + con.ServerVersion);
}
void Close()
{
con.Close();
con.Dispose();
}
static void Main()
{
Example example = new Example();
example.Connect();
example.Close();
}
}
|
Note: Additional samples are provided in directoryORACLE_BASE\ORACLE_HOME\ODP.NET\Samples. |
Oracle Provider for OLE DB (OraOLEDB) is an OLE DB data provider that offers high performance and efficient access to Oracle data by OLE DB consumers. In general, this developer's guide assumes that you are using OraOLEDB through OLE DB or ADO.
Oracle Objects for OLE (OO4O) is a product designed to provide easy access to data stored in Oracle Database with any programming or scripting language that supports the Microsoft COM Automation and ActiveX technology. This includes Visual Basic, Visual C++, Visual Basic For Applications (VBA), IIS Active Server Pages (VBScript and JavaScript), and others.
See the OO4O online help for detailed information about using OO4O.
Oracle Objects for OLE consists of these software layers:
OO4O "In-Process" Automation Server
Oracle Data Control
Oracle Objects for OLE C++ Class Library
Figure 13-2 illustrates the OO4O software components.
Topics:
The OO4O Automation Server is a set of COM Automation objects for connecting to Oracle Database, running SQL statements and PL/SQL blocks, and accessing the results.
Unlike other COM-based database connectivity APIs, such as Microsoft ADO, the OO4O Automation Server was developed specifically for use with Oracle Database.
It provides an optimized API for accessing features that are unique to Oracle Database and are otherwise cumbersome or inefficient to use from ODBC or OLE database-specific components.
OO4O provides key features for accessing Oracle Database efficiently and easily in environments ranging from the typical two-tier client/server applications, such as those developed in Visual Basic or Excel, to application servers deployed in multitiered application server environments such as web server applications in Microsoft Internet Information Server (IIS) or Microsoft Transaction Server (MTS).
Features include:
Support for execution of PL/SQL and Java stored subprograms, and PL/SQL anonymous blocks. This includes support for Oracle Database data types used as parameters to stored subprograms, including PL/SQL cursors. See "Support for Oracle LOB and Object Data Types".
Support for scrollable and updatable cursors for easy and efficient access to result sets of queries.
Thread-safe objects and Connection Pool Management Facility for developing efficient web server applications.
Full support for Oracle Database object-relational and LOB data types.
Full support for Advanced Queuing.
Support for array inserts and updates.
Support for Microsoft Transaction Server (MTS).
The Oracle Objects for OLE object model is illustrated in Figure 13-3.
Topics:
An OraSession object manages collections of OraDatabase, OraConnection, and OraDynaset objects used within an application.
Typically, a single OraSession object is created for each application, but you can create named OraSession objects for shared use within and between applications.
The OraSession object is the top-most object for an application. It is the only object created by the CreateObject VB/VBA API and not by an Oracle Objects for OLE method. This code fragment shows how to create an OraSession object:
Dim OraSession as Object
Set OraSession = CreateObject("OracleInProcServer.XOraSession")
OraServer represents a physical network connection to Oracle Database.
The OraServer interface is introduced to expose the connection-multiplexing feature provided in the Oracle Call Interface. After an OraServer object is created, multiple user sessions (OraDatabase) can be attached to it by calling the OpenDatabase method. This feature is particularly useful for application components, such as Internet Information Server (IIS), that use Oracle Objects for OLE in n-tier distributed environments.
The use of connection multiplexing when accessing Oracle Database with a large number of user sessions active can help reduce server processing and resource requirements while improving server scalability.
OraServer is used to share a single connection across multiple OraDatabase objects (multiplexing), whereas each OraDatabase obtained from an OraSession has its own physical connection.
An OraDatabase interface adds additional methods for controlling transactions and creating interfaces representing Oracle Database object types. Attributes of schema objects can be retrieved using the Describe method of the OraDatabase interface.
Before Oracle Database 8g Release 1, an OraDatabase object is created by calling the OpenDatabase method of an OraSession interface. The Oracle Net alias, user name, and password are passed as arguments to this method. As of Oracle Database 8g Release 1, calling this method results in implicit creation of an OraServer object.
An OraDatabase object can also be created using the OpenDatabase method of the OraServer interface.
Transaction control methods are available at the OraDatabase (user session) level. Transactions might be started as Read-Write (default), Serializable, or Read-only. Transaction control methods include:
BeginTrans
CommitTrans
RollbackTrans
For example:
UserSession.BeginTrans(OO4O_TXN_READ_WRITE)
UserSession.ExecuteSQL("delete emp where empno = 1234")
UserSession.CommitTrans
An OraDynaset object permits browsing and updating of data created from a SQL SELECT statement.
The OraDynaset object can be thought of as a cursor, although in actuality several real cursors might be used to implement the semantics of OraDynaset. An OraDynaset object automatically maintains a local cache of data fetched from the server and transparently implements scrollable cursors within the browse data. Large queries might require significant local disk space; application developers are encouraged to refine queries to limit disk usage.
An OraField object represents a single column or data item within a row of a dynaset.
If the current row is being updated, then the OraField object represents the currently updated value, although the value might not have been committed to the database.
Assignment to the Value property of a field is permitted only if a record is being edited (using Edit) or a record is being added (using AddNew). Other attempts to assign data to a field's Value property results in an error.
An OraMetaData object is a collection of OraMDAttribute objects that represent the description information about a particular schema object in the database.
The OraMetaData object can be visualized as a table with three columns:
Metadata Attribute Name
Metadata Attribute Value
Flag specifying whether the Value is another OraMetaData object
The OraMDAttribute objects contained in the OraMetaData object can be accessed by subscripting using ordinal integers or by using the name of the property. Referencing an index that is not in the collection results in the return of a NULL OraMDAttribute object.
An OraParameter object represents a bind variable in a SQL statement or PL/SQL block.
OraParameter objects are created, accessed, and removed indirectly through the OraParameters collection of an OraDatabase object. Each parameter has an identifying name and an associated value. You can automatically bind a parameter to SQL and PL/SQL statements of other objects (as noted in the object descriptions), by using the parameter name as a placeholder in the SQL or PL/SQL statement. Such use of parameters can simplify dynamic queries and increase program performance.
An OraParamArray object represents an array-type bind variable in a SQL statement or PL/SQL block, as opposed to a scalar-type bind variable represented by the OraParameter object.
OraParamArray objects are created, accessed, and removed indirectly through the OraParameters collection of an OraDatabase object. Each OraParamArray object has an identifying name and an associated value.
An OraSQLStmt object represents a single SQL statement. Use the CreateSQL method to create an OraSQLStmt object from an OraDatabase object.
During create and refresh, OraSQLStmt objects automatically bind all relevant, enabled input parameters to the specified SQL statement, using the parameter names as placeholders in the SQL statement. This can improve the performance of SQL statement execution without reparsing the SQL statement.
The OraSQLStmt object can be used later to run the same query using a different value for the :SALARY placeholder. This is done as follows (updateStmt is the OraSQLStmt object here):
OraDatabase.Parameters("SALARY").value = 200000
updateStmt.Parameters("ENAME").value = "KING"
updateStmt.Refresh
An OraAQ object is instantiated by calling the CreateAQ method of the OraDatabase interface. It represents a queue that is present in the database.
Oracle Objects for OLE provides interfaces for accessing Oracle Advanced Queuing (AQ) feature. It makes AQ accessible from popular COM-based development environments such as Visual Basic. For a detailed description of Oracle Advanced Queuing, see Oracle Streams Advanced Queuing User's Guide.
The OraAQMsg object encapsulates the message to be enqueued or dequeued. The message can be of any user-defined or raw type.
For a detailed description of Oracle Advanced Queuing, see Oracle Streams Advanced Queuing User's Guide.
The OraAQAgent object represents a message recipient and is only valid for queues that support multiple consumers. It is a child of OraAQMsg.
An OraAQAgent object can be instantiated by calling the AQAgent method. For example:
Set agent = qMsg.AQAgent(name)
An OraAQAgent object can also be instantiated by calling the AddRecipient method. For example:
Set agent = qMsg.AddRecipient(name, address, protocol).
Oracle Objects for OLE (OO4O) provides full support for accessing and manipulating instances of object data types and LOBs in Oracle Database. Figure 13-4 ill_ustrates the data types supported by OO4O.
Instances of these types can be fetched from the database or passed as input or output variables to SQL statements and PL/SQL blocks, including stored subprograms. All instances are mapped to COM Automation Interfaces that provide methods for dynamic attribute access and manipulation.
Figure 13-4 Supported Oracle Database Data Types
Topics:
The OraBlob and OraClob interfaces in Oracle Objects for OLE provide methods for performing operations on large database objects of data type BLOB, CLOB, and NCLOB. BLOB, CLOB, and NCLOB data types are also referred to here as LOB data types.
LOB data is accessed using Read and the CopyToFile methods.
LOB data is modified using Write, Append, Erase, Trim, Copy, CopyFromFile, and CopyFromBFile methods. Before modifying the content of a LOB column in a row, a row lock must be obtained. If the LOB column is a field of an OraDynaset, object, then the lock is obtained by calling the Edit method.
The OraBFile interface in Oracle Objects for OLE provides methods for performing operations on large database objects of data type BFILE.
BFILE objects are large binary data objects stored in operating system files outside of the database tablespaces.
Oracle Data Control (ODC) is an ActiveX Control that is designed to simplify the exchange of data between Oracle Database and visual controls such edit, text, list, and grid controls in Visual Basic and other development tools that support custom controls.
ODC acts as an agent to handle the flow of information from Oracle Database and a visual data-aware control, such as a grid control, that is bound to it. The data control manages various user interface (UI) tasks such as displaying and editing data. It also runs and manages the results of database queries.
Oracle Data Control is compatible with the Microsoft data control included with Visual Basic. If you are familiar with the Visual Basic data control, learning to use Oracle Data Control is quick and easy. Communication between data-aware controls and a Data Control is governed by a protocol that Microsoft specified.
Oracle Objects for OLE (OO4O) C++ Class Library is a collection of C++ classes that provide programmatic access to the Oracle Object Server. Although the class library is implemented using OLE Automation, neither the OLE development kit nor any OLE development knowledge is necessary to use it. This library helps C++ developers avoid the chore of writing COM client code for accessing the OO4O interfaces.
|
See Also:
|
This chapter describes regular expressions and explains how to use them in database applications.
Topics:
|
See Also:
|
A regular expression specifies a search pattern, using metacharacters (which are, or belong to, operators) and character literals (described in Oracle Database SQL Language Reference).
The search pattern can be complex. For example, this regular expression matches any string that begins with either f or ht, followed by tp, optionally followed by s, followed by the colon (:):
(f|ht)tps?:
The metacharacters (which are also operators) in the preceding example are the parentheses, the pipe symbol (|), and the question mark (?). The character literals are f, ht, tp, s, and the colon (:).
Parentheses group multiple pattern elements into a single element. The pipe symbol (|) indicates a choice between the elements on either side of it, f and ht. The question mark (?) indicates that the preceding element, s, is optional. Thus, the preceding regular expression matches these strings:
http:
https:
ftp:
ftps:
Regular expressions are a powerful text-processing component of the programming languages Java and PERL. For example, a PERL script can read the contents of each HTML file in a directory into a single string variable and then use a regular expression to search that string for URLs. This robust pattern-matching functionality is one reason that many application developers use PERL.
Oracle SQL support for regular expressions lets application developers implement complex pattern-matching logic in the database, which is useful for these reasons:
By centralizing pattern-matching logic in the database, you avoid intensive string processing of SQL results sets by middle-tier applications.
For example, life science customers often rely on PERL to do pattern analysis on bioinformatics data stored in huge databases of DNA and proteins. Previously, finding a match for a protein sequence such as [AG].{4}GK[ST] was handled in the middle tier. The SQL regular expression functions move the processing logic closer to the data, thereby providing a more efficient solution.
By using server-side regular expressions to enforce constraints, you avoid duplicating validation logic on multiple clients.
Oracle SQL supports regular expressions with the pattern-matching condition and functions summarized in Table 3-1. Each pattern matcher searches a given string for a given pattern (described with a regular expression), and each has the pattern-matching options described in Table 3-2. The functions have additional options (for example, the character position at which to start searching the string for the pattern). For details, see Oracle Database SQL Language Reference.
Table 3-1 Oracle SQL Pattern-Matching Condition and Functions
| Name | Description |
|---|---|
|
Condition that can appear in the Example: This WHERE REGEXP_LIKE((hr.employees.first_name, '^Ste(v|ph)en$') | |
|
Function that returns the number of times the given pattern appears in the given string. Example: This function invocation returns the number of times that
REGEXP_COUNT('Albert Einstein', 'e', 7, 'c')
(The returned value is 1, because the | |
|
Function that returns an integer that indicates the starting position of the given pattern in the given string. Alternatively, the integer can indicate the position immediately following the end of the pattern. Example: This function invocation returns the starting position of the first valid email address in the column REGEXP_INSTR(hr.employees.email, '\w+@\w+(\.\w+)+') If the returned value is greater than zero, then the column contains a valid email address. | |
|
Function that returns the string that results from replacing occurrences of the given pattern in the given string with a replacement string. Example: This function invocation puts a space after each character in the column REGEXP_REPLACE(hr.countries.country_name, '(.)', '\1 ') | |
|
Function that is like Example: This function invocation returns
REGEXP_SUBSTR('Oracle 2010', 'O r a c l e', 1, 1, 'x')
|
Table 3-2 describes the pattern-matching options that are available to each pattern matcher in Table 3-1.
Table 3-2 Pattern-Matching Options for Oracle SQL Pattern-Matching Condition and Functions
| Option | Description | Example |
|---|---|---|
|
|
Specifies case-insensitive matching. |
This function invocation returns 3:
REGEXP_COUNT('Albert Einstein', 'e', 'i')
|
|
|
Specifies case-sensitive matching. |
This function invocation returns 2:
REGEXP_COUNT('Albert Einstein', 'e', 'c')
|
|
|
Allows the Dot operator ( |
In this function invocation, the string and search pattern match only because the
REGEXP_SUBSTR('a'||CHR(10)||'d', 'a.d', 1, 1, 'n')
|
|
|
Specifies multiline mode, where a newline character inside a string terminates a line. The string can contain multiple lines. Multiline mode affects POSIX operators Beginning-of-Line Anchor ( |
This function invocation returns
REGEXP_SUBSTR('ab'||CHR(10)||'ac', '^a.', 1, 2, 'm')
|
|
|
Ignores whitespace characters in the search pattern. By default, whitespace characters match themselves. |
This function invocation returns
REGEXP_SUBSTR('abcd', 'a b c d', 1, 1, 'x')
|
Oracle SQL implementation of regular expressions conforms to these standards:
IEEE Portable Operating System Interface (POSIX) standard draft 1003.2/D11.2
Oracle SQL follows exactly the syntax and matching semantics for regular expression operators as defined in the POSIX standard for matching ASCII (English language) data. You can find the POSIX standard draft at this URL:
http://www.opengroup.org/onlinepubs/007908799/xbd/re.html
For more information, see "POSIX Operators in Oracle SQL Regular Expressions".
Unicode Regular Expression Guidelines of the Unicode Consortium
Oracle SQL extends regular expression support beyond the POSIX standard in these ways:
Extends the matching capabilities for multilingual data
For details, see "Oracle SQL Multilingual Extensions to POSIX Standard".
Supports some commonly used PERL regular expression operators that are not included in the POSIX standard but do not conflict with it (for example, character class shortcuts and the nongreedy modifier (?))
For details, see "Oracle SQL PERL-Influenced Extensions to POSIX Standard".
Oracle SQL supports a set of common operators (composed of metacharacters) used in regular expressions.
|
Caution: The interpretation of metacharacters differs between tools that support regular expressions. If you are porting regular expressions from another environment to Oracle Database, ensure that Oracle SQL supports their syntax and interprets them as you expect. |
Topics:
Table 3-3 summarizes the POSIX operators defined in the POSIX standard Extended Regular Expression (ERE) syntax. Oracle SQL follows the exact syntax and matching semantics for these operators as defined in the POSIX standard for matching ASCII (English language) data. Any differences in action between Oracle SQL and the POSIX standard are noted in the Description column.
Table 3-3 POSIX Operators in Oracle SQL Regular Expressions
| Operator Syntax | Names | Description | Examples |
|---|---|---|---|
|
|
Any Character Dot |
Matches any character in the database character set, including the newline character if you specify matching option The Linux, UNIX, and Windows platforms recognize the newline character as the linefeed character ( The Macintosh platforms recognize the newline character as the carriage return character ( Note: In the POSIX standard, this operator matches any English character except NULL and the newline character. |
The expression |
|
|
One or More Plus Quantifier |
Matches one or more occurrences of the preceding subexpression (greedyFoot 1 ). |
The expression |
|
|
Zero or More Star Quantifier |
Matches zero or more occurrences of the preceding subexpression (greedyFootref 1). |
The expression |
|
|
Zero or One Question Mark Quantifier |
Matches zero or one occurrences of the preceding subexpression (greedyFootref 1). |
The expression |
|
|
Interval Exact Count |
Matches exactly |
The expression |
|
|
Interval At-Least Count |
Matches at least |
The expression |
|
|
Interval Between Count |
Matches at least |
The expression |
|
|
Matching Character List |
Matches any single character in the list within the brackets. In the list, all operators except these are treated as literals:
A dash ( Note: In the POSIX standard, a range includes all collation elements between the start and end of the range in the linguistic definition of the current locale. Thus, ranges are linguistic rather than byte value ranges; the semantics of the range expression are independent of the character set. In Oracle Database, the linguistic range is determined by the |
The expression |
|
|
Nonmatching Character List |
Matches any single character not in the list within the brackets. For information about operators and ranges in the character list, see the description of the Matching Character List operator. |
The expression The expression |
|
|
Or |
Matches either alternative. |
The expression |
|
|
Subexpression Grouping |
Treats the expression within the parentheses as a unit. The expression can be a string or a complex expression containing operators. You can refer to a subexpression in a back reference. |
The expression |
|
|
Back Reference |
Matches the nth preceding subexpression, where A back reference lets you search for a repeated string without knowing what it is. For the |
The expression The expression |
|
|
Escape Character |
Treats the subsequent character as a literal. A backslash (\) lets you search for a character that would otherwise be treated as a metacharacter. Use consecutive backslashes ( |
The expression |
|
|
Beginning-of-Line Anchor |
Default mode: Matches the beginning of a string. Multiline mode:Foot 2 Matches the beginning of any line the source string. |
The expression |
|
|
End-of-Line Anchor |
Default mode: Matches the end of a string. Multiline mode:Footref 2 Matches the end of any line the source string. |
The expression |
|
|
POSIX Character Class |
Matches any character in the specified POSIX character class (such as uppercase characters, digits, or punctuation characters). Note: In English regular expressions, range expressions often indicate a character class. For example, |
The expression |
|
|
POSIX Collating Element Operator |
Specifies a collating element defined in the current locale. The This syntax lets you use a multicharacter collating element where otherwise only single-character collating elements are allowed. For example, you can ensure that the collating element |
The expression The expression |
|
|
POSIX Character Equivalence Class |
Matches all characters that belong to the same POSIX character equivalence class as the specified character, in the current locale. This syntax must appear within a character list; that is, it must be nested within the brackets for a character list. Character equivalents depend on how canonical rules are defined for your database locale. For details, see Oracle Database Globalization Support Guide. |
The expression |
Footnote 1 A greedy operator matches as many occurrences as possible while allowing the rest of the match to succeed. To make the operator nongreedy, follow it with the nongreedy modifier (?) (see Table 3-5).
Footnote 2 Specify multiline mode with the pattern-matching option m, described in Table 3-2.
When applied to multilingual data, Oracle SQL POSIX operators extend beyond the matching capabilities specified in the POSIX standard.
Table 3-4 shows, for each POSIX operator, which POSIX standards define its syntax and whether Oracle SQL extends its semantics for handling multilingual data. The POSIX standards are Basic Regular Expression (BRE) and Extended Regular Expression (ERE).
Table 3-4 POSIX Operators and Multilingual Operator Relationships
| Operator | POSIX BRE Syntax | POSIX ERE Syntax | Multilingual Enhancement |
|---|---|---|---|
|
|
Yes |
Yes |
-- |
|
|
Yes |
Yes |
-- |
|
|
-- |
Yes |
-- |
|
|
-- |
Yes |
-- |
|
|
-- |
Yes |
-- |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
-- |
|
|
Yes |
Yes |
-- |
|
|
Yes |
Yes |
-- |
|
|
Yes |
Yes |
-- |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
|
|
Yes |
Yes |
Yes |
Multilingual data might have multibyte characters. Oracle Database lets you enter multibyte characters directly (if you have a direct input method) or use functions to compose them. You cannot use the Unicode hexadecimal encoding value of the form \xxxx. Oracle Database evaluates the characters based on the byte values used to encode the character, not the graphical representation of the character.
Oracle SQL supports some commonly used PERL regular expression operators that are not included in the POSIX standard but do not conflict with it.
Table 3-5 summarizes the PERL-influenced operators that Oracle SQL supports.
|
Caution: PERL character class matching is based on the locale model of the operating system, whereas Oracle SQL regular expressions are based on the language-specific data of the database. In general, you cannot expect a regular expression involving locale data to produce the same results in PERL and Oracle SQL. |
Table 3-5 PERL-Influenced Operators in Oracle SQL Regular Expressions
Footnote 1 A nongreedy operator matches as few occurrences as possible while allowing the rest of the match to succeed. To make the operator greedy, omit the nongreedy modifier (?).
Regular expressions are useful for enforcing constraints—for example, to ensure that phone numbers are entered into the database in a standard format. Example 3-1 creates a contacts table and adds a CHECK constraint to the p_number column to enforce this format model:
(XXX) XXX-XXXX
Example 3-1 Enforcing a Phone Number Format with Regular Expressions
DROP TABLE contacts; CREATE TABLE contacts ( l_name VARCHAR2(30), p_number VARCHAR2(30) CONSTRAINT c_contacts_pnf CHECK (REGEXP_LIKE (p_number, '^\(\d{3}\) \d{3}-\d{4}$')) );
Table 3-6 explains the elements of the regular expression.
Table 3-6 Explanation of the Regular Expression Elements in Example 3-1
| Regular Expression Element | Matches . . . |
|---|---|
|
|
The beginning of the string. |
|
|
A left parenthesis. The backslash ( |
|
|
Exactly three digits. |
|
|
A right parenthesis. The backslash ( |
|
space character |
A space character. |
|
|
Exactly three digits. |
|
|
A hyphen. |
|
|
Exactly four digits. |
|
|
The end of the string. |
Example 3-2 shows some statements that correctly and incorrectly insert phone numbers into the contacts table.
Example 3-2 Inserting Phone Numbers in Correct and Incorrect Formats
These are correct:
INSERT INTO contacts (p_number) VALUES('(650) 555-0100');
INSERT INTO contacts (p_number) VALUES('(215) 555-0100');
These generate CHECK constraint errors:
INSERT INTO contacts (p_number) VALUES('650 555-0100');
INSERT INTO contacts (p_number) VALUES('650 555 0100');
INSERT INTO contacts (p_number) VALUES('650-555-0100');
INSERT INTO contacts (p_number) VALUES('(650)555-0100');
INSERT INTO contacts (p_number) VALUES(' (650) 555-0100');
A back reference (described in Table 3-3) stores the referenced subexpression in a temporary buffer. Therefore, you can use back references to reposition characters, as in Example 3-3. For an explanation of the elements of the regular expression in Example 3-3, see Table 3-7.
Example 3-3 Using Back References to Reposition Characters
Create table and populate it with names in different formats:
DROP TABLE famous_people;
CREATE TABLE famous_people (names VARCHAR2(20));
INSERT INTO famous_people (names) VALUES ('John Quincy Adams');
INSERT INTO famous_people (names) VALUES ('Harry S. Truman');
INSERT INTO famous_people (names) VALUES ('John Adams');
INSERT INTO famous_people (names) VALUES (' John Quincy Adams');
INSERT INTO famous_people (names) VALUES ('John_Quincy_Adams');
SQL*Plus formatting command:
COLUMN "names after regexp" FORMAT A20
For each name in the table whose format is "first middle last", use back references to reposition characters so that the format becomes "last, first middle":
SELECT names "names", REGEXP_REPLACE(names, '^(\S+)\s(\S+)\s(\S+)$', '\3, \1 \2') AS "names after regexp" FROM famous_people ORDER BY "names";
Result:
names names after regexp -------------------- -------------------- John Quincy Adams John Quincy Adams Harry S. Truman Truman, Harry S. John Adams John Adams John Quincy Adams Adams, John Quincy John_Quincy_Adams John_Quincy_Adams 5 rows selected.
Table 3-7 explains the elements of the regular expression.
Table 3-7 Explanation of the Regular Expression Elements in Example 3-3
| Regular Expression Element | Description |
|---|---|
|
|
Matches the beginning of the string. |
|
|
Matches the end of the string. |
|
|
Matches one or more nonspace characters. The parentheses are not escaped so they function as a grouping expression. |
|
|
Matches a whitespace character. |
|
|
Substitutes the first subexpression, that is, the first group of parentheses in the matching pattern. |
|
|
Substitutes the second subexpression, that is, the second group of parentheses in the matching pattern. |
|
|
Substitutes the third subexpression, that is, the third group of parentheses in the matching pattern. |
|
|
Inserts a comma character. |
Oracle Database Advanced Application Developer's Guide explains topics that experienced application developers reference repeatedly. Information in this guide applies to features that work the same on all supported platforms, and does not include system-specific information.
Preface Topics:
Oracle Database Advanced Application Developer's Guide is intended for application developers who are either developing applications or converting applications to run in the Oracle Database environment. This guide is also valuable to anyone who is interested in the development of database applications, such as systems analysts and project managers.
To use this document effectively, you need a working knowledge of:
Application programming
Structured Query Language (SQL)
Object-oriented programming
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
For more information, see these documents in the Oracle Database 11g Release 2 documentation set:
See also:
Oracle PL/SQL Tips and Techniques by Joseph C. Trezzo. Oracle Press, 1999.
Oracle PL/SQL Programming by Steven Feuerstein. 3rd Edition. O'Reilly & Associates, 2002.
Oracle PL/SQL Developer's Workbook by Steven Feuerstein. O'Reilly & Associates, 2000.
Oracle PL/SQL Best Practices by Steven Feuerstein. O'Reilly & Associates, 2001.
This document uses these text conventions:
| Convention | Meaning |
|---|---|
| boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
| italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
Also:
*_view means all static data dictionary views whose names end with view. For example, *_ERRORS means ALL_ERRORS, DBA_ERRORS, and USER_ERRORS. For more information about any static data dictionary view, or about static dictionary views in general, see Oracle Database Reference.
Table names not qualified with schema names are in the sample schema HR. For information about the sample schemas, see Oracle Database Sample Schemas.
This chapter describes some procedural capabilities of Oracle Database for application development.
Topics:
|
See Also:
|
PL/SQL is a modern, block-structured programming language. It provides several features that make developing powerful database applications very convenient. For example, PL/SQL provides procedural constructs, such as loops and conditional statements, that are not available in standard SQL.
You can directly enter SQL data manipulation language (DML) statements inside PL/SQL blocks, and you can use subprograms supplied by Oracle to perform data definition language (DDL) statements.
PL/SQL code runs on the server, so using PL/SQL lets you centralize significant parts of your database applications for increased maintainability and security. It also enables you to achieve a significant reduction of network overhead in client/server applications.
|
Note: Some Oracle tools, such as Oracle Forms, contain a PL/SQL engine that lets you run PL/SQL locally. |
You can even use PL/SQL for some database applications instead of 3GL programs that use embedded SQL or Oracle Call Interface (OCI).
PL/SQL units include:
|
See Also:
|
An anonymous block is a PL/SQL unit that has no name. An anonymous block consists of an optional declarative part, an executable part, and one or more optional exception handlers.
The declarative part declares PL/SQL variables, exceptions, and cursors. The executable part contains PL/SQL code and SQL statements, and can contain nested blocks.
Exception handlers contain code that is invoked when the exception is raised, either as a predefined PL/SQL exception (such as NO_DATA_FOUND or ZERO_DIVIDE) or as an exception that you define.
Anonymous blocks are usually used interactively from a tool, such as SQL*Plus, or in a precompiler, OCI, or SQL*Module application. They are usually used to invoke stored subprograms or to open cursor variables.
The anonymous block in Example 6-1 uses the DBMS_OUTPUT package to print the names of all employees in the HR.EMPLOYEES table who are in department 20.
Example 6-1 Anonymous Block
DECLARE
last_name VARCHAR2(10);
cursor c1 IS
SELECT LAST_NAME
FROM EMPLOYEES
WHERE DEPARTMENT_ID = 20
ORDER BY LAST_NAME;
BEGIN
OPEN c1;
LOOP
FETCH c1 INTO last_name;
EXIT WHEN c1%NOTFOUND;
DBMS_OUTPUT.PUT_LINE(last_name);
END LOOP;
END;
/
Result:
Fay Hartstein
Exceptions let you handle Oracle Database error conditions with PL/SQL program logic, enabling your application to prevent the server from issuing an error that can cause the client application to end. The anonymous block in Example 6-2 handles the predefined Oracle Database exception NO_DATA_FOUND (which results in ORA-01403 if not handled).
Example 6-2 Anonymous Block with Exception Handler for Predefined Error
DECLARE
Emp_number INTEGER := 9999
Emp_name VARCHAR2(10);
BEGIN
SELECT LAST_NAME INTO Emp_name
FROM EMPLOYEES
WHERE EMPLOYEE_ID = Emp_number;
DBMS_OUTPUT.PUT_LINE('Employee name is ' || Emp_name);
EXCEPTION
WHEN NO_DATA_FOUND THEN
DBMS_OUTPUT.PUT_LINE('No such employee: ' || Emp_number);
END;
/
Result:
No such employee: 9999
You can also define your own exceptions; that is, you can declare them in the declaration part of a block and define them in the exception part of the block, as in Example 6-3.
Example 6-3 Anonymous Block with Exception Handler for User-Defined Exception
DECLARE Emp_name VARCHAR2(10); Emp_number INTEGER; Empno_out_of_range EXCEPTION; BEGIN Emp_number := 10001; IF Emp_number > 9999 OR Emp_number < 1000 THEN RAISE Empno_out_of_range; ELSE SELECT LAST_NAME INTO Emp_name FROM EMPLOYEES WHERE EMPLOYEE_ID = Emp_number; DBMS_OUTPUT.PUT_LINE('Employee name is ' || Emp_name); END IF; EXCEPTION WHEN Empno_out_of_range THEN DBMS_OUTPUT.PUT_LINE('Employee number ' || Emp_number || ' is out of range.'); END; /
Result:
Employee number 10001 is out of range.
|
See Also:
|
A stored PL/SQL unit is a subprogram (procedure or function) or package that:
Has a name.
Can take parameters, and can return values.
Is stored in the data dictionary.
Can be invoked by many users.
If a subprogram belongs to a package, it is called a package subprogram; if not, it is called a standalone subprogram.
Topics:
Because a subprogram is stored in the database, it must be named. This distinguishes it from other stored subprograms and makes it possible for applications to invoke it. Each publicly-visible subprogram in a schema must have a unique name, and the name must be a legal PL/SQL identifier.
|
Note: If you plan to invoke a stored subprogram using a stub generated by SQL*Module, then the stored subprogram name must also be a legal identifier in the invoking host 3GL language, such as Ada or C. |
Stored subprograms can take parameters. In the procedure in Example 6-4, the department number is an input parameter that is used when the parameterized cursor c1 is opened.
Example 6-4 Stored Procedure with Parameters
CREATE OR REPLACE PROCEDURE get_emp_names ( dept_num IN NUMBER ) IS emp_name VARCHAR2(10); CURSOR c1 (dept_num NUMBER) IS SELECT LAST_NAME FROM EMPLOYEES WHERE DEPARTMENT_ID = dept_num; BEGIN OPEN c1(dept_num); LOOP FETCH c1 INTO emp_name; EXIT WHEN C1%NOTFOUND; DBMS_OUTPUT.PUT_LINE(emp_name); END LOOP; CLOSE c1; END; /
The formal parameters of a subprogram have three major attributes, described in Table 6-1.
Table 6-1 Attributes of Subprogram Parameters
| Parameter Attribute | Description |
|---|---|
|
Name |
This must be a legal PL/SQL identifier. |
|
Mode |
This indicates whether the parameter is an input-only parameter ( |
|
Data Type |
This is a standard PL/SQL data type. |
Topics:
Parameter modes define the action of formal parameters. You can use the three parameter modes, IN (the default), OUT, and IN OUT, with any subprogram. Avoid using the OUT and IN OUT modes with functions. Good programming practice dictates that a function returns a single value and does not change the values of variables that are not local to the subprogram.
The data type of a formal parameter consists of one of these:
An unconstrained type name, such as NUMBER or VARCHAR2.
A type that is constrained using the %TYPE or %ROWTYPE attributes.
|
Note: Numerically constrained types such asNUMBER(2) or VARCHAR2(20) are not allowed in a parameter list. |
Use the type attributes %TYPE and %ROWTYPE to constrain the parameter. For example, the procedure heading in Example 6-4 can be written as follows:
PROCEDURE get_emp_names(dept_num IN EMPLOYEES.DEPARTMENT_ID%TYPE)
This gives the dept_num parameter the same data type as the DEPARTMENT_ID column in the EMPLOYEES table. The column and table must be available when a declaration using %TYPE (or %ROWTYPE) is elaborated.
Using %TYPE is recommended, because if the type of the column in the table changes, it is not necessary to change the application code.
If the get_emp_names procedure is part of a package, you can use previously-declared public (package) variables to constrain its parameter data types. For example:
dept_number NUMBER(2); ... PROCEDURE get_emp_names(dept_num IN dept_number%TYPE);
Use the %ROWTYPE attribute to create a record that contains all the columns of the specified table. The procedure in Example 6-5 returns all the columns of the EMPLOYEES table in a PL/SQL record for the given employee ID.
Example 6-5 %TYPE and %ROWTYPE Attributes
CREATE OR REPLACE PROCEDURE get_emp_rec ( emp_number IN EMPLOYEES.EMPLOYEE_ID%TYPE, emp_info OUT EMPLOYEES%ROWTYPE ) IS BEGIN SELECT * INTO emp_info FROM EMPLOYEES WHERE EMPLOYEE_ID = emp_number; END; /
Invoke procedure from PL/SQL block:
DECLARE
emp_row EMPLOYEES%ROWTYPE;
BEGIN
get_emp_rec(206, emp_row);
DBMS_OUTPUT.PUT('EMPLOYEE_ID: ' || emp_row.EMPLOYEE_ID);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('FIRST_NAME: ' || emp_row.FIRST_NAME);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('LAST_NAME: ' || emp_row.LAST_NAME);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('EMAIL: ' || emp_row.EMAIL);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('PHONE_NUMBER: ' || emp_row.PHONE_NUMBER);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('HIRE_DATE: ' || emp_row.HIRE_DATE);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('JOB_ID: ' || emp_row.JOB_ID);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('SALARY: ' || emp_row.SALARY);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('COMMISSION_PCT: ' || emp_row.COMMISSION_PCT);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('MANAGER_ID: ' || emp_row.MANAGER_ID);
DBMS_OUTPUT.NEW_LINE;
DBMS_OUTPUT.PUT('DEPARTMENT_ID: ' || emp_row.DEPARTMENT_ID);
DBMS_OUTPUT.NEW_LINE;
END;
/
Result:
EMPLOYEE_ID: 206 FIRST_NAME: William LAST_NAME: Gietz EMAIL: WGIETZ PHONE_NUMBER: 515.123.8181 HIRE_DATE: 07-JUN-02 JOB_ID: AC_ACCOUNT SALARY: 8300 COMMISSION_PCT: MANAGER_ID: 205 DEPARTMENT_ID: 110
Stored functions can return values that are declared using %ROWTYPE. For example:
FUNCTION get_emp_rec (dept_num IN EMPLOYEES.DEPARTMENT_ID%TYPE) RETURN EMPLOYEES%ROWTYPE IS ...
You can pass PL/SQL composite variables (collections and records) as parameters to stored subprograms.
If the subprogram is remote, you must create a redundant loop-back DBLINK, so that when the remote subprogram compiles, the type checker that verifies the source uses the same definition of the user-defined composite variable type as the invoker uses.
Parameters can take initial values. Use either the assignment operator or the DEFAULT keyword to give a parameter an initial value. For example, these are equivalent:
PROCEDURE Get_emp_names (Dept_num IN NUMBER := 20) IS ... PROCEDURE Get_emp_names (Dept_num IN NUMBER DEFAULT) IS ...
When a parameter takes an initial value, it can be omitted from the actual parameter list when you invoke the subprogram. When you do specify the parameter value on the invocation, it overrides the initial value.
|
Note: Unlike in an anonymous PL/SQL block, you do not use the keywordDECLARE before the declarations of variables, cursors, and exceptions in a stored subprogram. In fact, it is an error to use it. |
Use a text editor to write the subprogram. Then, using an interactive tool such as SQL*Plus, load the text file containing the procedure by entering:
@get_emp
This loads the procedure into the current schema from the get_emp.sql file (.sql is the default file extension). The slash (/) after the code is not part of the code, it only activates the loading of the procedure.
|
Caution: When developing a subprogram, it is usually preferable to use the statementCREATE OR REPLACE PROCEDURE or CREATE OR REPLACE FUNCTION. This statement replaces any previous version of that subprogram in the same schema with the newer version, but without warning. |
You can use either the keyword IS or AS after the subprogram parameter list.
|
See Also:
|
Privileges Needed
To create a subprogram, a package specification, or a package body, you must meet these prerequisites:
You must have the CREATE PROCEDURE system privilege to create a subprogram or package in your schema, or the CREATE ANY PROCEDURE system privilege to create a subprogram or package in another user's schema. In either case, the package body must be created in the same schema as the package.
|
Note: To create without errors (to compile the subprogram or package successfully) requires these additional privileges:
|
If the privileges of the owner of a subprogram or package change, then the subprogram must be reauthenticated before it is run. If a necessary privilege to a referenced object is revoked from the owner of the subprogram or package, then the subprogram cannot be run.
The EXECUTE privilege on a subprogram gives a user the right to run a subprogram owned by another user. Privileged users run the subprogram under the security domain of the owner of the subprogram. Therefore, users need not be granted the privileges to the objects referenced by a subprogram. This allows for more disciplined and efficient security strategies with database applications and their users. Furthermore, all subprograms and packages are stored in the data dictionary (in the SYSTEM tablespace). No quota controls the amount of space available to a user who creates subprograms and packages.
|
Note: Package creation requires a sort. The user creating the package must be able to create a sort segment in the temporary tablespace with which the user is associated. |
To alter a subprogram, you must first drop it using the DROP PROCEDURE or DROP FUNCTION statement, then re-create it using the CREATE PROCEDURE or CREATE FUNCTION statement. Alternatively, use the CREATE OR REPLACE PROCEDURE or CREATE OR REPLACE FUNCTION statement, which first drops the subprogram if it exists, then re-creates it as specified.
|
Caution: The subprogram is dropped without warning. |
A standalone subprogram, a standalone function, a package body, or an entire package can be dropped using the SQL statements DROP PROCEDURE, DROP FUNCTION, DROP PACKAGE BODY, and DROP PACKAGE, respectively. A DROP PACKAGE statement drops both the specification and body of a package.
This statement drops the Old_sal_raise procedure in your schema:
DROP PROCEDURE Old_sal_raise;
Privileges Needed
To drop a subprogram or package, the subprogram or package must be in your schema, or you must have the DROP ANY PROCEDURE privilege. An individual subprogram within a package cannot be dropped; the containing package specification and body must be re-created without the subprograms to be dropped.
A PL/SQL subprogram running on an Oracle Database instance can invoke an external subprogram written in a third-generation language (3GL). The 3GL subprogram runs in a separate address space from that of the database.
|
See Also: Chapter 14, "Developing Applications with Multiple Programming Languages," for information about external subprograms |
Using the PL/SQL function result cache can save significant space and time. Each time a result-cached PL/SQL function is invoked with different parameter values, those parameters and their result are stored in the cache. Subsequently, when the same function is invoked with the same parameter values, the result is retrieved from the cache, instead of being recomputed. Because the cache is stored in a shared global area (SGA), it is available to any session that runs your application.
If a database object that was used to compute a cached result is updated, the cached result becomes invalid and must be recomputed.
The best candidates for result-caching are functions that are invoked frequently but depend on information that changes infrequently or never.
For more information about the PL/SQL function result cache, see Oracle Database PL/SQL Language Reference.
A package is a collection of related program objects (for example, subprogram, variables, constants, cursors, and exceptions) stored as a unit in the database.
Using packages is an alternative to creating subprograms as standalone schema objects. Packages have many advantages over standalone subprograms. For example, they:
Let you organize your application development more efficiently.
Let you grant privileges more efficiently.
Let you modify package objects without recompiling dependent schema objects.
Enable Oracle Database to read multiple package objects into memory at once.
Can contain global variables and cursors that are available to all subprograms in the package.
Let you overload subprograms. Overloading a subprogram means creating multiple subprograms with the same name in the same package, each taking arguments of different number or data type.
|
See Also: Oracle Database PL/SQL Language Reference for more information about subprogram name overloading |
The specification part of a package declares the public types, variables, constants, and subprograms that are visible outside the immediate scope of the package. The body of a package defines both the objects declared in the specification and private objects that are not visible to applications outside the package.
Example 6-6 creates a package that contains one stored function and two stored procedures, and then invokes a procedure.
Example 6-6 Creating PL/SQL Package and Invoking Package Subprogram
-- Sequence that package function needs: CREATE SEQUENCE emp_sequence START WITH 8000 INCREMENT BY 10; -- Package specification: CREATE or REPLACE PACKAGE employee_management IS FUNCTION hire_emp ( firstname VARCHAR2, lastname VARCHAR2, email VARCHAR2, phone VARCHAR2, hiredate DATE, job VARCHAR2, sal NUMBER, comm NUMBER, mgr NUMBER, deptno NUMBER ) RETURN NUMBER; PROCEDURE fire_emp( emp_id IN NUMBER ); PROCEDURE sal_raise ( emp_id IN NUMBER, sal_incr IN NUMBER ); END employee_management; / -- Package body: CREATE or REPLACE PACKAGE BODY employee_management IS FUNCTION hire_emp ( firstname VARCHAR2, lastname VARCHAR2, email VARCHAR2, phone VARCHAR2, hiredate DATE, job VARCHAR2, sal NUMBER, comm NUMBER, mgr NUMBER, deptno NUMBER ) RETURN NUMBER IS new_empno NUMBER(10); BEGIN new_empno := emp_sequence.NEXTVAL; INSERT INTO EMPLOYEES ( employee_id, first_name, last_name, email, phone_number, hire_date, job_id, salary, commission_pct, manager_id, department_id ) VALUES ( new_empno, firstname, lastname, email, phone, hiredate, job, sal, comm, mgr, deptno ); RETURN (new_empno); END hire_emp; PROCEDURE fire_emp ( emp_id IN NUMBER ) IS BEGIN DELETE FROM EMPLOYEES WHERE EMPLOYEE_ID = emp_id; IF SQL%NOTFOUND THEN raise_application_error( -20011, 'Invalid Employee Number: ' || TO_CHAR(Emp_id) ); END IF; END fire_emp; PROCEDURE sal_raise ( emp_id IN NUMBER, sal_incr IN NUMBER ) IS BEGIN UPDATE EMPLOYEES SET SALARY = SALARY + sal_incr WHERE EMPLOYEE_ID = emp_id; IF SQL%NOTFOUND THEN raise_application_error( -20011, 'Invalid Employee Number: ' || TO_CHAR(Emp_id) ); END IF; END sal_raise; END employee_management; /
Invoke package procedures:
DECLARE
empno NUMBER(6);
sal NUMBER(6);
temp NUMBER(6);
BEGIN
empno := employee_management.hire_emp(
'John',
'Doe',
'john.doe@company.com',
'555-0100',
'20-SEP-07',
'ST_CLERK',
2500,
0,
100,
20);
DBMS_OUTPUT.PUT_LINE('New employee ID is ' || TO_CHAR(empno));
END;
/
The size limit for PL/SQL stored database objects such as subprograms, triggers, and packages is the size of the Descriptive Intermediate Attributed Notation for Ada (DIANA) code in the shared pool in bytes. The Linux and UNIX limit on the size of the flattened DIANA/code size is 64K but the limit might be 32K on desktop platforms.
The most closely related number that a user can access is the PARSED_SIZE in the static data dictionary view *_OBJECT_SIZE. That gives the size of the DIANA in bytes as stored in the SYS.IDL_xxx$ tables. This is not the size in the shared pool. The size of the DIANA part of PL/SQL code (used during compilation) is significantly larger in the shared pool than it is in the system table.
Each part of a package is created with a different statement. Create the package specification using the CREATE PACKAGE statement. The CREATE PACKAGE statement declares public package objects.
To create a package body, use the CREATE PACKAGE BODY statement. The CREATE PACKAGE BODY statement defines the procedural code of the public subprograms declared in the package specification.
You can also define private, or local, package subprograms, and variables in a package body. These objects can only be accessed by other subprograms in the body of the same package. They are not visible to external users, regardless of the privileges they hold.
It is often more convenient to add the OR REPLACE clause in the CREATE PACKAGE or CREATE PACKAGE BODY statements when you are first developing your application. The effect of this option is to drop the package or the package body without warning. The CREATE statements are:
CREATE OR REPLACE PACKAGE Package_name AS ...
and
CREATE OR REPLACE PACKAGE BODY Package_name AS ...
The body of a package can contain:
Subprograms declared in the package specification.
Definitions of cursors declared in the package specification.
Local subprograms, not declared in the package specification.
Local variables.
Subprograms, cursors, and variables that are declared in the package specification are global. They can be invoked, or used, by external users that have EXECUTE permission for the package or that have EXECUTE ANY PROCEDURE privileges.
When you create the package body, ensure that each subprogram that you define in the body has the same parameters, by name, data type, and mode, as the declaration in the package specification. For functions in the package body, the parameters and the return type must agree in name and type.
The privileges required to create or drop a package specification or package body are the same as those required to create or drop a standalone subprogram. See "Creating Subprograms" and "Dropping Subprograms and Packages".
The names of a package and all public objects in the package must be unique within a given schema. The package specification and its body must have the same name. All package constructs must have unique names within the scope of the package, unless overloading of subprogram names is desired.
Each session that references a package object has its own instance of the corresponding package, including persistent state for any public and private variables, cursors, and constants. If any of the session's instantiated packages (specification or body) are invalidated, then all package instances in the session are invalidated and recompiled. Therefore, the session state is lost for all package instances in the session.
When a package in a given session is invalidated, the session receives ORA-04068 the first time it attempts to use any object of the invalid package instance. The second time a session makes such a package call, the package is reinstantiated for the session without error. However, if you handle this error in your application, be aware of the following:
For optimal performance, Oracle Database returns this error message only when the package state is discarded. When a subprogram in one package invokes a subprogram in another package, the session state is lost for both packages.
If a server session traps ORA-04068, then ORA-04068 is not raised for the client session. Therefore, when the client session attempts to use an object in the package, the package is not reinstantiated. To reinstantiate the package, the client session must either reconnect to the database or recompile the package.
In Example 6-7, the RAISE statement raises the current exception, ORA-04068, which is the cause of the exception being handled, ORA-06508. ORA-04068 is not trapped.
Example 6-7 Raising ORA-04068
PROCEDURE p IS
package_exception EXCEPTION;
PRAGMA EXCEPTION_INIT (package_exception, -6508);
BEGIN
...
EXCEPTION
WHEN package_exception THEN
RAISE;
END;
/
In Example 6-8, the RAISE statement raises the exception ORA-20001 in response to ORA-06508, instead of the current exception, ORA-04068. ORA-04068 is trapped. When this happens, the ORA-04068 error is masked, which stops the package from being reinstantiated.
Example 6-8 Trapping ORA-04068
PROCEDURE p IS
package_exception EXCEPTION;
other_exception EXCEPTION;
PRAGMA EXCEPTION_INIT (package_exception, -6508);
PRAGMA EXCEPTION_INIT (other_exception, -20001);
BEGIN
...
EXCEPTION
WHEN package_exception THEN
...
RAISE other_exception;
END;
/
In most production environments, DDL operations that can cause invalidations are usually performed during inactive working hours; therefore, this situation might not be a problem for end-user applications. However, if package invalidations are common in your system during working hours, then you might want to code your applications to handle this error when package calls are made.
There are many packages provided with Oracle Database, either to extend the functionality of the database or to give PL/SQL access to SQL features. You can invoke these packages from your application.
|
See Also: Oracle Database PL/SQL Packages and Types Reference for an overview of these Oracle Database packages |
Oracle Database uses two engines to run PL/SQL blocks and subprograms. The PL/SQL engine runs procedural statements, while the SQL engine runs SQL statements. During execution, every SQL statement causes a context switch between the two engines, resulting in performance overhead.
Performance can be improved substantially by minimizing the number of context switches required to run a particular block or subprogram. When a SQL statement runs inside a loop that uses collection elements as bind variables, the large number of context switches required by the block can cause poor performance. Collections include:
Varrays
Nested tables
Index-by tables
Host arrays
Binding is the assignment of values to PL/SQL variables in SQL statements. Bulk binding is binding an entire collection at once. Bulk binds pass the entire collection back and forth between the two engines in a single operation.
Typically, using bulk binds improves performance for SQL statements that affect four or more database rows. The more rows affected by a SQL statement, the greater the performance gain from bulk binds.
|
Note: This section provides an overview of bulk binds to help you decide whether to use them in your PL/SQL applications. For detailed information about using bulk binds, including ways to handle exceptions that occur in the middle of a bulk bind operation, see Oracle Database PL/SQL Language Reference.Parallel DML statements are disabled with bulk binds. |
Consider using bulk binds to improve the performance of:
A bulk bind, which uses the FORALL keyword, can improve the performance of INSERT, UPDATE, or DELETE statements that reference collection elements.
The PL/SQL block in Example 6-9 increases the salary for employees whose manager's ID number is 7902, 7698, or 7839, with and without bulk binds. Without bulk bind, PL/SQL sends a SQL statement to the SQL engine for each updated employee, leading to context switches that slow performance.
Example 6-9 DML Statements that Reference Collections
DECLARE TYPE numlist IS VARRAY (100) OF NUMBER; id NUMLIST := NUMLIST(7902, 7698, 7839); BEGIN -- Efficient method, using bulk bind: FORALL i IN id.FIRST..id.LAST UPDATE EMPLOYEES SET SALARY = 1.1 * SALARY WHERE MANAGER_ID = id(i); -- Slower method: FOR i IN id.FIRST..id.LAST LOOP UPDATE EMPLOYEES SET SALARY = 1.1 * SALARY WHERE MANAGER_ID = id(i); END LOOP; END; /
The BULK COLLECT INTO clause can improve the performance of queries that reference collections. You can use BULK COLLECT INTO with tables of scalar values, or tables of %TYPE values.
The PL/SQL block in Example 6-10 queries multiple values into PL/SQL tables, with and without bulk binds. Without bulk bind, PL/SQL sends a SQL statement to the SQL engine for each selected employee, leading to context switches that slow performance.
Example 6-10 SELECT Statements that Reference Collections
DECLARE
TYPE var_tab IS TABLE OF VARCHAR2(20)
INDEX BY PLS_INTEGER;
empno VAR_TAB;
ename VAR_TAB;
counter NUMBER;
CURSOR c IS
SELECT EMPLOYEE_ID, LAST_NAME
FROM EMPLOYEES
WHERE MANAGER_ID = 7698;
BEGIN
-- Efficient method, using bulk bind:
SELECT EMPLOYEE_ID, LAST_NAME BULK COLLECT
INTO empno, ename
FROM EMPLOYEES
WHERE MANAGER_ID = 7698;
-- Slower method:
counter := 1;
FOR rec IN c LOOP
empno(counter) := rec.EMPLOYEE_ID;
ename(counter) := rec.LAST_NAME;
counter := counter + 1;
END LOOP;
END;
/
You can use the FORALL keyword with the BULK COLLECT INTO keywords to improve the performance of FOR loops that reference collections and return DML.
The PL/SQL block in Example 6-11 updates the EMPLOYEES table by computing bonuses for a collection of employees. Then it returns the bonuses in a column called bonus_list_inst. The actions are performed with and without bulk binds. Without bulk bind, PL/SQL sends a SQL statement to the SQL engine for each updated employee, leading to context switches that slow performance.
Example 6-11 FOR Loops that Reference Collections and Return DML
DECLARE TYPE emp_list IS VARRAY(100) OF EMPLOYEES.EMPLOYEE_ID%TYPE; empids emp_list := emp_list(182, 187, 193, 200, 204, 206); TYPE bonus_list IS TABLE OF EMPLOYEES.SALARY%TYPE; bonus_list_inst bonus_list; BEGIN -- Efficient method, using bulk bind: FORALL i IN empids.FIRST..empids.LAST UPDATE EMPLOYEES SET SALARY = 0.1 * SALARY WHERE EMPLOYEE_ID = empids(i) RETURNING SALARY BULK COLLECT INTO bonus_list_inst; -- Slower method: FOR i IN empids.FIRST..empids.LAST LOOP UPDATE EMPLOYEES SET SALARY = 0.1 * SALARY WHERE EMPLOYEE_ID = empids(i) RETURNING SALARY INTO bonus_list_inst(i); END LOOP; END; /
You can speed up PL/SQL subprograms by compiling them into native code residing in shared libraries.
You can use native compilation with both the supplied packages and the subprograms you write yourself. Subprograms compiled this way work in all server environments, such as the shared server configuration (formerly known as multithreaded server) and Oracle Real Application Clusters (Oracle RAC).
This technique is most effective for computation-intensive subprograms that do not spend much time running SQL, because it can do little to speed up SQL statements invoked from these subprograms.
With Java, you can use the ncomp tool to compile your own packages and classes.
|
See Also:
|
A cursor is a static object; a cursor variable is a pointer to a cursor. Because cursor variables are pointers, they can be passed and returned as parameters to subprograms. A cursor variable can also refer to different cursors in its lifetime.
Additional advantages of cursor variables include:
Encapsulation
Queries are centralized in the stored subprogram that opens the cursor variable.
Easy maintenance
If you must change the cursor, then you only make the change in the stored subprogram, not in each application.
Convenient security
The user of the application is the user name used when the application connects to the server. The user must have EXECUTE permission on the stored subprogram that opens the cursor. But, the user need not have READ permission on the tables used in the query. Use this capability to limit access to the columns in the table and access to other stored subprograms.
Topics:
Memory is usually allocated for a cursor variable in the client application using the appropriate ALLOCATE statement. In Pro*C, use the EXEC SQL ALLOCATE cursor_name statement. In OCI, use the Cursor Data Area.
You can also use cursor variables in applications that run entirely in a single server session. You can declare cursor variables in PL/SQL subprograms, open them, and use them as parameters for other PL/SQL subprograms.
This section has these examples of cursor variable usage in PL/SQL:
|
See Also: For additional cursor variable examples that use programmatic interfaces: |
Example 6-12 creates a package that defines a PL/SQL cursor variable type and two procedures, and then invokes the procedures from a PL/SQL block. The first procedure opens a cursor variable using a bind variable in the WHERE clause. The second procedure uses a cursor variable to fetch rows from the EMPLOYEES table.
Example 6-12 Fetching Data with Cursor Variable
CREATE OR REPLACE PACKAGE emp_data AS TYPE emp_val_cv_type IS REF CURSOR RETURN EMPLOYEES%ROWTYPE; PROCEDURE open_emp_cv ( emp_cv IN OUT emp_val_cv_type, dept_number IN EMPLOYEES.DEPARTMENT_ID%TYPE ); PROCEDURE fetch_emp_data ( emp_cv IN emp_val_cv_type, emp_row OUT EMPLOYEES%ROWTYPE ); END emp_data; / CREATE OR REPLACE PACKAGE BODY emp_data AS PROCEDURE open_emp_cv ( emp_cv IN OUT emp_val_cv_type, dept_number IN EMPLOYEES.DEPARTMENT_ID%TYPE ) IS BEGIN OPEN emp_cv FOR SELECT * FROM EMPLOYEES WHERE DEPARTMENT_ID = dept_number ORDER BY last_name; END open_emp_cv; PROCEDURE fetch_emp_data ( emp_cv IN emp_val_cv_type, emp_row OUT EMPLOYEES%ROWTYPE ) IS BEGIN FETCH emp_cv INTO emp_row; END fetch_emp_data; END emp_data; /
Invoke package procedures:
DECLARE emp_curs emp_data.emp_val_cv_type; dept_number EMPLOYEES.DEPARTMENT_ID%TYPE; emp_row EMPLOYEES%ROWTYPE; BEGIN dept_number := 20; -- Open cursor, using variable: emp_data.open_emp_cv(emp_curs, dept_number); -- Fetch and display data: LOOP emp_data.fetch_emp_data(emp_curs, emp_row); EXIT WHEN emp_curs%NOTFOUND; DBMS_OUTPUT.PUT(emp_row.LAST_NAME || ' '); DBMS_OUTPUT.PUT_LINE(emp_row.SALARY); END LOOP; END; /
In Example 6-13, the procedure opens a cursor variable for either the EMPLOYEES table or the DEPARTMENTS table, depending on the value of the p arameter discrim. The anonymous block invokes the procedure to open the cursor variable for the EMPLOYEES table, but fetches from the DEPARTMENTS table, which raises the predefined exception ROWTYPE_MISMATCH.
Example 6-13 Cursor Variable with Discriminator
CREATE OR REPLACE PACKAGE emp_dept_data AS
TYPE cv_type IS REF CURSOR;
PROCEDURE open_cv (
cv IN OUT cv_type,
discrim IN POSITIVE
);
END emp_dept_data;
/
CREATE OR REPLACE PACKAGE BODY emp_dept_data AS
PROCEDURE open_cv (
cv IN OUT cv_type,
discrim IN POSITIVE) IS
BEGIN
IF discrim = 1 THEN
OPEN cv FOR
SELECT * FROM EMPLOYEES ORDER BY employee_id;
ELSIF discrim = 2 THEN
OPEN cv FOR
SELECT * FROM DEPARTMENTS ORDER BY department_id;
END IF;
END open_cv;
END emp_dept_data;
/
Invoke procedure open_cv from anonymous block:
DECLARE emp_rec EMPLOYEES%ROWTYPE; dept_rec DEPARTMENTS%ROWTYPE; cv Emp_dept_data.CV_TYPE; BEGIN emp_dept_data.open_cv(cv, 1); -- Open cv for EMPLOYEES fetch. FETCH cv INTO dept_rec; -- Fetch from DEPARTMENTS. DBMS_OUTPUT.PUT(dept_rec.DEPARTMENT_ID); DBMS_OUTPUT.PUT_LINE(' ' || dept_rec.LOCATION_ID); EXCEPTION WHEN ROWTYPE_MISMATCH THEN BEGIN DBMS_OUTPUT.PUT_LINE ('Row type mismatch, fetching EMPLOYEES data ...'); FETCH cv INTO emp_rec; DBMS_OUTPUT.PUT(emp_rec.DEPARTMENT_ID); DBMS_OUTPUT.PUT_LINE(' ' || emp_rec.LAST_NAME); END; END; /
Result:
Row type mismatch, fetching EMPLOYEES data ...
90 King
To list compile-time errors, query the static data dictionary view *_ERRORS. From these views, you can retrieve original source code. The error text associated with the compilation of a subprogram is updated when the subprogram is replaced, and it is deleted when the subprogram is dropped.
SQL*Plus issues a warning message for compile-time errors, but for more information about them, you must use the command SHOW ERRORS.
|
Note: Before issuing theSHOW ERRORS statement, use the SET LINESIZE statement to get long lines on output. The value 132 is usually a good choice. For example:
SET LINESIZE 132 |
Example 6-14 has two compile-time errors: WHER should be WHERE, and END should be followed by a semicolon. SHOW ERRORS shows the line, column, and description of each error.
Example 6-14 Compile-Time Errors
CREATE OR REPLACE PROCEDURE fire_emp ( emp_id NUMBER ) AS BEGIN DELETE FROM EMPLOYEES WHER EMPLOYEE_ID = Emp_id; END /
Result:
Warning: Procedure created with compilation errors.
Command:
SHOW ERRORS;
Result:
Errors for PROCEDURE FIRE_EMP: LINE/COL ERROR -------- ----------------------------------------------------------------- 5/3 PL/SQL: SQL Statement ignored 6/8 PL/SQL: ORA-00933: SQL command not properly ended 7/3 PLS-00103: Encountered the symbol "end-of-file" when expecting one of the following: ; <an identifier> <a double-quoted delimited-identifier> current delete exists prior <a single-quoted SQL string> The symbol ";" was substituted for "end-of-file" to continue.
|
See Also:
|
Oracle Database allows user-defined errors in PL/SQL code to be handled so that user-specified error numbers and messages are returned to the client application, which can handle the error.
User-specified error messages are returned using the RAISE_APPLICATION_ERROR procedure. For example:
RAISE_APPLICATION_ERROR(error_number, 'text', keep_error_stack)
This procedure stops subprogram execution, rolls back any effects of the subprogram, and returns a user-specified error number and message (unless the error is trapped by an exception handler). error_number must be in the range of -20000 to -20999.
Use error number -20000 as a generic number for messages where it is important to relay information to the user, but having a unique error number is not required. Text must be a character expression, 2 KB or less (longer messages are ignored). To add the error to errors on the stack, set Keep_error_stack to TRUE; to replace the existing errors, set it to FALSE (the default).
The RAISE_APPLICATION_ERROR procedure is often used in exception handlers or in the logic of PL/SQL code. For example, this exception handler selects the string for the associated user-defined error message and invokes the RAISE_APPLICATION_ERROR procedure:
...
WHEN NO_DATA_FOUND THEN
SELECT Error_string INTO Message
FROM Error_table,
V$NLS_PARAMETERS V
WHERE Error_number = -20101 AND Lang = v.value AND
v.parameter = "NLS_LANGUAGE";
Raise_application_error(-20101, Message);
...
Topics:
User-defined exceptions are explicitly defined and raised within the PL/SQL block, to process errors specific to the application. When an exception is raised, the usual execution of the PL/SQL block stops, and an exception handler is invoked. Specific exception handlers can be written to handle any internal or user-defined exception.
Application code can check for a condition that requires special attention using an IF statement. If there is an error condition, then two options are available:
Enter a RAISE statement that names the appropriate exception. A RAISE statement stops the execution of the subprogram, and control passes to an exception handler (if any).
Invoke the RAISE_APPLICATION_ERROR procedure to return a user-specified error number and message.
You can also define an exception handler to handle user-specified error messages. For example, Figure 6-1 shows:
An exception and associated exception handler in a subprogram
A conditional statement that checks for an error (such as transferring funds not available) and enters a user-specified error number and message within a trigger
How user-specified error numbers are returned to the invoking environment (in this case, a subprogram), and how that application can define an exception that corresponds to the user-specified error number
Declare a user-defined exception in a subprogram or package body (private exceptions), or in the specification of a package (public exceptions). Define an exception handler in the body of a subprogram (standalone or package).
Figure 6-1 Exceptions and User-Defined Errors
In database PL/SQL units, an unhandled user-error condition or internal error condition that is not trapped by an appropriate exception handler causes the implicit rollback of the program unit. If the program unit includes a COMMIT statement before the point at which the unhandled exception is observed, then the implicit rollback of the program unit can only be completed back to the previous COMMIT.
Additionally, unhandled exceptions in database-stored PL/SQL units propagate back to client-side applications that invoke the containing program unit. In such an application, only the application program unit invocation is rolled back (not the entire application program unit), because it is submitted to the database as a SQL statement.
If unhandled exceptions in database PL/SQL units are propagated back to database applications, modify the database PL/SQL code to handle the exceptions. Your application can also trap for unhandled exceptions when invoking database program units and handle such errors appropriately.
You can use a trigger or a stored subprogram to create a distributed query. This distributed query is decomposed by the local Oracle Database instance into a corresponding number of remote queries, which are sent to the remote nodes for execution. The remote nodes run the queries and send the results back to the local node. The local node then performs any necessary post-processing and returns the results to the user or application.
If a portion of a distributed statement fails, possibly from a constraint violation, then Oracle Database returns ORA-02055. Subsequent statements, or subprogram invocations, return ORA-02067 until a rollback or a rollback to savepoint is entered.
Design your application to check for any returned error messages that indicates that a portion of the distributed update has failed. If you detect a failure, rollback the entire transaction (or rollback to a savepoint) before allowing the application to proceed.
When a subprogram is run locally or at a remote location, these types of exceptions can occur:
PL/SQL user-defined exceptions, which must be declared using the keyword EXCEPTION
PL/SQL predefined exceptions, such as NO_DATA_FOUND
SQL errors, such as ORA-00900
Application exceptions, which are generated using the RAISE_APPLICATION_ERROR procedure.
When using local subprograms, all of these messages can be trapped by writing an exception handler, such as:
EXCEPTION
WHEN ZERO_DIVIDE THEN
/* Handle the exception */
The WHEN clause requires an exception name. If the exception that is raised does not have a name, such as those generated with RAISE_APPLICATION_ERROR, then one can be assigned using PRAGMA_EXCEPTION_INIT. For example:
DECLARE
...
Null_salary EXCEPTION;
PRAGMA EXCEPTION_INIT(Null_salary, -20101);
BEGIN
...
RAISE_APPLICATION_ERROR(-20101, 'salary is missing');
...
EXCEPTION
WHEN Null_salary THEN
...
When invoking a remote subprogram, exceptions are also handled by creating a local exception handler. The remote subprogram must return an error number to the local invoking subprogram, which then handles the exception, as shown in the previous example. Because PL/SQL user-defined exceptions always return ORA-06510 to the local subprogram, these exceptions cannot be handled. All other remote exceptions can be handled in the same manner as local exceptions.
Compiling a stored subprogram involves fixing any syntax errors in the code. You might need to do additional debugging to ensure that the subprogram works correctly, performs well, and recovers from errors. Such debugging might involve:
Adding extra output statements to verify execution progress and check data values at certain points within the subprogram.
Running a separate debugger to analyze execution in greater detail.
Topics:
PL/Scope is a compiler-driven tool that collects and organizes data about user-defined identifiers from PL/SQL source code. Because PL/Scope is a compiler-driven tool, you use it through interactive development environments (such as SQL Developer and JDeveloper), rather than directly.
PL/Scope enables the development of powerful and effective PL/Scope source code browsers that increase PL/SQL developer productivity by minimizing time spent browsing and understanding source code.
For more information about PL/Scope, see Chapter 7, "Using PL/Scope."
The PL/SQL hierarchical profiler reports the dynamic execution profile of your PL/SQL program, organized by subprogram calls. It accounts for SQL and PL/SQL execution times separately. Each subprogram-level summary in the dynamic execution profile includes information such as number of calls to the subprogram, time spent in the subprogram itself, time spent in the subprogram's subtree (that is, in its descendent subprograms), and detailed parent-children information.
You can browse the generated HTML reports in any browser. The browser's navigational capabilities, combined with well chosen links, provide a powerful way to analyze performance of large applications, improve application performance, and lower development costs.
For a detailed description of PL/SQL hierarchical profiler, see Chapter 8, "Using the PL/SQL Hierarchical Profiler."
Recent releases of Oracle JDeveloper have extensive features for debugging PL/SQL, Java, and multi-language programs. You can get Oracle JDeveloper as part of various Oracle product suites. Often, a more recent release is available as a download at:
http://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.html
You can also debug stored subprograms and triggers using the Oracle package DBMS_OUTPUT. Put PUT and PUT_LINE statements in your code to output the value of variables and expressions to your terminal.
Starting with Oracle Database 10g, a new privilege model applies to debugging PL/SQL and Java code running within the database. This model applies whether you are using Oracle JDeveloper, Oracle Developer, or any of the various third-party PL/SQL or Java development environments, and it affects both the DBMS_DEBUG and DBMS_DEBUG_JDWP APIs.
For a session to connect to a debugger, the effective user at the time of the connect operation must have the DEBUG CONNECT SESSION system privilege. This effective user might be the owner of a DR subprogram involved in making the connect call.
When a debugger becomes connected to a session, the session login user and the enabled session-level roles are fixed as the privilege environment for that debugging connection. Any DEBUG or EXECUTE privileges needed for debugging must be granted to that combination of user and roles.
To be able to display and change Java public variables or variables declared in a PL/SQL package specification, the debugging connection must be granted either EXECUTE or DEBUG privilege on the relevant code.
To be able to either display and change private variables or breakpoint and run code lines step by step, the debugging connection must be granted DEBUG privilege on the relevant code
|
Caution: TheDEBUG privilege allows a debugging session to do anything that the subprogram being debugged could have done if that action had been included in its code. |
In addition to these privilege requirements, the ability to stop on individual code lines and debugger access to variables are allowed only in code compiled with debug information generated. Use the PL/SQL compilation parameter PLSQL_DEBUG and the DEBUG keyword on statements such as ALTER PACKAGE to control whether the PL/SQL compiler includes debug information in its results. If not, variables are not accessible, and neither stepping nor breakpoints stop on code lines. The PL/SQL compiler never generates debug information for code hidden with the PL/SQL wrap utility.
The DEBUG ANY PROCEDURE system privilege is equivalent to the DEBUG privilege granted on all objects in the database. Objects owned by SYS are included if the value of the O7_DICTIONARY_ACCESSIBILITY parameter is TRUE.
A debug role mechanism is available to carry privileges needed for debugging that are not normally enabled in the session. See the documentation on the DBMS_DEBUG and DBMS_DEBUG_JDWP packages for details on how to specify a debug role and any necessary related password.
The JAVADEBUGPRIV role carries the DEBUG CONNECT SESSION and DEBUG ANY PROCEDURE privileges. Grant it only with the care those privileges warrant.
|
Caution: GrantingDEBUG ANY PROCEDURE privilege, or granting DEBUG privilege on any object owned by SYS, means granting complete rights to the database. |
If you are writing code for part of a debugger, you might need to use packages such as DBMS_DEBUG_JDWP or DBMS_DEBUG.
The DBMS_DEBUG_JDWP package, provided starting with Oracle Database 9g Release 2, provides a framework for multi-language debugging that is expected to supersede the DBMS_DEBUG package over time. It is especially useful for programs that combine PL/SQL and Java.
The DBMS_DEBUG package, provided starting with Oracle8i, implements server-side debuggers and provides a way to debug server-side PL/SQL units. Several of the debuggers available, such as Oracle Procedure Builder and various third-party vendor solutions, use this API.
|
See Also:
|
Stored PL/SQL subprograms can be invoked from many different environments. For example:
Interactively, using an Oracle Database tool
From the body of another subprogram
From within an application (such as a SQL*Forms or a precompiler)
From the body of a trigger
Stored PL/SQL functions (but not procedures) can also be invoked from within SQL statements. For details, see "Invoking Stored PL/SQL Functions from SQL Statements".
Topics:
|
See Also:
|
You do not need privileges to invoke:
Standalone subprograms that you own
Subprograms in packages that you own
Public standalone subprograms
Subprograms in public packages
To invoke a standalone or package subprogram owned by another user:
You must have the EXECUTE privilege for the standalone subprogram or for the package containing the subprogram, or you must have the EXECUTE ANY PROCEDURE system privilege.
When running a remote subprogram, you must be granted the EXECUTE privilege or EXECUTE ANY PROCEDURE system privilege directly, not through a role.
You must include the name of the owner in the invocation. For example:
EXECUTE jdoe.Fire_emp (1043); EXECUTE jdoe.Hire_fire.Fire_emp (1043);
If the subprogram is a definer's-rights (DR) subprogram, then it runs with the privileges of the owner. The owner must have all the necessary object privileges for any referenced objects.
If the subprogram is an invoker's-rights (IR) subprogram, then it runs with your privileges. You must have all the necessary object privileges for any referenced objects; that is, all objects accessed by the subprogram through external references that are resolved in your schema. You can hold these privileges either directly or through a role. Roles are enabled unless an IR subprogram is invoked directly or indirectly by a DR subprogram.
You can invoke a subprogram interactively from an Oracle Database tool, such as SQL*Plus. Example 6-15 uses SQL*Plus to create a procedure and then invokes it in two different ways.
Example 6-15 Invoking a Subprogram Interactively with SQL*Plus
CREATE OR REPLACE PROCEDURE salary_raise ( employee EMPLOYEES.EMPLOYEE_ID%TYPE, increase EMPLOYEES.SALARY%TYPE ) IS BEGIN UPDATE EMPLOYEES SET SALARY = SALARY + increase WHERE EMPLOYEE_ID = employee; END; /
Invoke procedure from within PL/SQL block:
BEGIN
salary_raise(205, 200);
END;
/
Result:
PL/SQL procedure successfully completed.
Invoke procedure with EXECUTE statement:
EXECUTE salary_raise(205, 200);
Result:
PL/SQL procedure successfully completed.
Some interactive tools allow you to create session variables, which you can use for the duration of the session. Using SQL*Plus, Example 6-16 creates, uses, and prints a session variable.
Example 6-16 Creating and Using a Session Variable with SQL*Plus
-- Create function for later use: CREATE OR REPLACE FUNCTION get_job_id ( emp_id EMPLOYEES.EMPLOYEE_ID%TYPE ) RETURN EMPLOYEES.JOB_ID%TYPE IS job_id EMPLOYEES.JOB_ID%TYPE; BEGIN SELECT JOB_ID INTO job_id FROM EMPLOYEES WHERE EMPLOYEE_ID = emp_id; RETURN job_id; END; / -- Create session variable: VARIABLE job VARCHAR2(10); -- Run function and store returned value in session variable: EXECUTE :job := get_job_id(204); PL/SQL procedure successfully completed.
SQL*Plus command:
PRINT job;
Result:
JOB -------------------------------- PR_REP
|
See Also:
|
A subprogram or a trigger can invoke another stored subprogram. In Example 6-17, the procedure print_mgr_name invokes the procedure print_emp_name.
Recursive subprogram invocations are allowed (that is, a subprogram can invoke itself).
Example 6-17 Invoking a Subprogram from Within Another Subprogram
-- Create procedure that takes employee's ID and prints employee's name: CREATE OR REPLACE PROCEDURE print_emp_name ( emp_id EMPLOYEES.EMPLOYEE_ID%TYPE ) IS fname EMPLOYEES.FIRST_NAME%TYPE; lname EMPLOYEES.LAST_NAME%TYPE; BEGIN SELECT FIRST_NAME, LAST_NAME INTO fname, lname FROM EMPLOYEES WHERE EMPLOYEE_ID = emp_id; DBMS_OUTPUT.PUT_LINE ( 'Employee #' || emp_id || ': ' || fname || ' ' || lname ); END; / -- Create procedure that takes employee's ID and prints manager's name: CREATE OR REPLACE PROCEDURE print_mgr_name ( emp_id EMPLOYEES.EMPLOYEE_ID%TYPE ) IS mgr_id EMPLOYEES.MANAGER_ID%TYPE; BEGIN SELECT MANAGER_ID INTO mgr_id FROM EMPLOYEES WHERE EMPLOYEE_ID = emp_id; DBMS_OUTPUT.PUT_LINE ( 'Manager of employee #' || emp_id || ' is: ' ); print_emp_name(mgr_id); END; /
Invoke procedures:
BEGIN print_emp_name(200); print_mgr_name(200); END; /
Result:
Employee #200: Jennifer Whalen Manager of employee #200 is: Employee #101: Neena Kochhar
A 3GL database application, such as a precompiler or an OCI application, can invoke a subprogram from within its own code.
Assume that the procedure Fire_emp1 was created as follows:
CREATE OR REPLACE PROCEDURE fire_emp1 (Emp_id NUMBER) AS
BEGIN
DELETE FROM Emp_tab WHERE Empno = Emp_id;
END;
To run a subprogram within the code of a precompiler application, you must use the EXEC call interface. For example, this statement invokes the Fire_emp procedure in the code of a precompiler application:
EXEC SQL EXECUTE
BEGIN
Fire_emp1(:Empnum);
END;
END-EXEC;
|
See Also: Oracle Call Interface Programmer's Guide for information about invoking PL/SQL subprograms from within 3GL applications |
Remote subprograms (standalone and package) can be invoked from within a subprogram, OCI application, or precompiler by specifying the remote subprogram name, a database link, and the parameters for the remote subprogram.
For example, this SQL*Plus statement invokes the procedure fire_emp1, which is located in the database and referenced by the local database link named boston_server:
EXECUTE fire_emp1@boston_server(1043);
You must specify values for all remote subprogram parameters, even if there are defaults. You cannot access remote package variables and constants.
|
Caution:
|
Topics:
|
See Also: "Handling Errors in Remote Subprograms" for information about exception handling when invoking remote subprograms |
You can create a synonym for a remote subprogram name and database link, and then use the synonym to invoke the subprogram. For example:
CREATE SYNONYM synonym1 for fire_emp1@boston_server; EXECUTE synonym1(1043); /
The synonym enables you to invoke the remote subprogram from an Oracle Database tool application, such as a SQL*Forms application, as well from within a subprogram, OCI application, or precompiler.
Synonyms provide both data independence and location transparency. Synonyms permit applications to function without modification regardless of which user owns the object and regardless of which database holds the object. However, synonyms are not a substitute for privileges on database objects. Appropriate privileges must be granted to a user before the user can use the synonym.
Because subprograms defined within a package are not individual objects (the package is the object), synonyms cannot be created for individual subprograms within a package.
If you do not want to use a synonym, you can create a local subprogram to invoke the remote subprogram. For example:
CREATE OR REPLACE PROCEDURE local_procedure (arg IN NUMBER) AS BEGIN fire_emp1@boston_server(arg); END; / DECLARE arg NUMBER; BEGIN local_procedure(arg); END; /
|
See Also:
|
All invocations to remotely stored subprograms are assumed to perform updates; therefore, this type of referencing always requires two-phase commit of that transaction (even if the remote subprogram is read-only). Furthermore, if a transaction that includes a remote subprogram invocation is rolled back, then the work done by the remote subprogram is also rolled back.
A subprogram invoked remotely can usually run a COMMIT, ROLLBACK, or SAVEPOINT statement, the same as a local subprogram. However, there are some differences in action:
If the transaction was originated by a database that is not an Oracle database, as might be the case in XA applications, these operations are not allowed in the remote subprogram.
After doing one of these operations, the remote subprogram cannot start any distributed transactions of its own.
If the remote subprogram does not commit or roll back its work, the commit is done implicitly when the database link is closed. In the meantime, further invocations to the remote subprogram are not allowed because it is still considered to be performing a transaction.
A distributed transaction modifies data on two or more databases. A distributed transaction is possible using a subprogram that includes two or more remote updates that access data on different databases. Statements in the construct are sent to the remote databases, and the execution of the construct succeeds or fails as a unit. If part of a distributed update fails and part succeeds, then a rollback (of the entire transaction or to a savepoint) is required to proceed. Consider this when creating subprograms that perform distributed updates.
|
Caution: Because SQL is a declarative language, rather than an imperative (or procedural) one, you cannot know how many times a function invoked from a SQL statement will run—even if the function is written in PL/SQL, an imperative language.If your application requires that a function be executed a certain number of times, do not invoke that function from a SQL statement. Use a cursor instead. For example, if your application requires that a function be called for each selected row, then open a cursor, select rows from the cursor, and call the function for each row. This guarantees that the number of calls to the function is the number of rows fetched from the cursor. |
To be invoked from a SQL statement, a stored PL/SQL function must be declared either at schema level or in a package specification.
These SQL statements can invoke stored PL/SQL functions:
INSERT
UPDATE
DELETE
SELECT
CALL
(CALL can also invoke a stored PL/SQL procedure.)
To invoke a PL/SQL subprogram from SQL, you must either own or have EXECUTE privileges on the subprogram. To select from a view defined with a PL/SQL function, you must have SELECT privileges on the view. No separate EXECUTE privileges are necessary to select from the view.
For general information about invoking subprograms, including passing parameters, see Oracle Database PL/SQL Language Reference.
Topics:
Invoking PL/SQL subprograms in SQL statements can:
Increase user productivity by extending SQL
Expressiveness of the SQL statement increases where activities are too complex, too awkward, or unavailable with SQL.
Increase query efficiency
Functions used in the WHERE clause of a query can filter data using criteria that must otherwise be evaluated by the application.
Manipulate character strings to represent special data types (for example, latitude, longitude, or temperature).
Provide parallel query execution
If the query is parallelized, then SQL statements in your PL/SQL subprogram might also be run in parallel (using the parallel query option).
A PL/SQL function can appear in a SQL statement wherever a SQL function or an expression can appear in a SQL statement. For example:
Select list of the SELECT statement
Condition of the WHERE or HAVING clause
CONNECT BY, START WITH, ORDER BY, or GROUP BY clause
VALUES clause of the INSERT statement
SET clause of the UPDATE statement
A PL/SQL table function (which returns a collection of rows) can appear in a SELECT statement instead of:
Column name in the SELECT list
Table name in the FROM clause
A PL/SQL function cannot appear in these contexts, which require unchanging definitions:
CHECK constraint clause of a CREATE or ALTER TABLE statement
Default value specification for a column
To be invoked from a SQL expression, a PL/SQL function must satisfy these requirements:
It must be a row function, not a column (group) function; that is, its argument cannot be an entire column.
Its formal parameters must be IN parameters, not OUT or IN OUT parameters.
Its formal parameters and its return value (if any) must have Oracle built-in data types (such as CHAR, DATE, or NUMBER), not PL/SQL data types (such as BOOLEAN, RECORD, or TABLE).
There is an exception to this rule: A formal parameter can have a PL/SQL data type if the corresponding actual parameter is implicitly converted to the data type of the formal parameter (as in Example 6-19).
The function in Example 6-18 satisfies the preceding requirements.
Example 6-18 PL/SQL Function in SQL Expression (Follows Rules)
DROP TABLE payroll; -- in case it exists CREATE TABLE payroll ( srate NUMBER, orate NUMBER, acctno NUMBER ); CREATE OR REPLACE FUNCTION gross_pay ( emp_id IN NUMBER, st_hrs IN NUMBER := 40, ot_hrs IN NUMBER := 0 ) RETURN NUMBER IS st_rate NUMBER; ot_rate NUMBER; BEGIN SELECT srate, orate INTO st_rate, ot_rate FROM payroll WHERE acctno = emp_id; RETURN st_hrs * st_rate + ot_hrs * ot_rate; END gross_pay; /
In Example 6-19, the SQL statement CALL invokes the PL/SQL function f1, whose formal parameter and return value have PL/SQL data type PLS_INTEGER. The CALL statement succeeds because the actual parameter, 2, is implicitly converted to the data type PLS_INTEGER. If the actual parameter had a value outside the range of PLS_INTEGER, the CALL statement would fail.
The purity of a stored subprogram refers to the side effects of that subprogram on database tables or package variables. Side effects can prevent the parallelization of a query, yield order-dependent (and therefore, indeterminate) results, or require that package state be maintained across user sessions. Various side effects are not allowed when a function is invoked from a SQL query or DML statement.
Before Oracle Database 8g Release 1, Oracle Database leveraged the PL/SQL compiler to enforce restrictions during the compilation of a stored subprogram or a SQL statement. As of Oracle Database 8g Release 1, the compile-time restrictions were relaxed, and a smaller set of restrictions are enforced during execution.
This change provides uniform support for stored subprograms written in PL/SQL, Java, and C, and it allows programmers the most flexibility possible.
Topics:
When a new SQL statement is run, checks are made to see if it is logically embedded within the execution of a running SQL statement. This occurs if the statement is run from a trigger or from a subprogram that was in turn invoked from the running SQL statement. In these cases, further checks determine if the new SQL statement is safe in the specific context.
These restrictions are enforced on subprograms:
A subprogram invoked from a query (SELECT statement) or DML statement cannot end the current transaction, create or rollback to a savepoint, or ALTER the system or session.
A subprogram invoked from a query or parallelized DML statement cannot run a DML statement or otherwise modify the database.
A subprogram invoked from a DML statement cannot read or modify the particular table being modified by that DML statement.
These restrictions apply regardless of what mechanism is used to run the SQL statement inside the subprogram or trigger. For example:
They apply to a SQL statement invoked from PL/SQL, whether embedded directly in a subprogram or trigger body, run using the native dynamic mechanism (EXECUTE IMMEDIATE), or run using the DBMS_SQL package.
They apply to statements embedded in Java with SQLJ syntax or run using JDBC.
They apply to statements run with OCI using the callback context from within an "external" C function.
You can avoid these restrictions if the execution of the new SQL statement is not logically embedded in the context of the running statement. PL/SQL autonomous transactions provide one escape (see "Autonomous Transactions" ). Another escape is available using OCI from an external C function, if you create a new connection rather than using the handle available from the OCIExtProcContext argument.
You can use the keywords DETERMINISTIC and PARALLEL_ENABLE in the syntax for declaring a function. These are optimization hints that inform the query optimizer and other software components about:
Functions that need not be invoked redundantly
Functions permitted within a parallelized query or parallelized DML statement
Only functions that are DETERMINISTIC are allowed in function-based indexes and in certain snapshots and materialized views.
A deterministic function depends solely on the values passed into it as arguments and does not reference or modify the contents of package variables or the database or have other side-effects. Such a function produces the same result value for any combination of argument values passed into it.
You place the DETERMINISTIC keyword after the return value type in a declaration of the function. For example:
CREATE OR REPLACE FUNCTION f1 (
p1 NUMBER
) RETURN NUMBER DETERMINISTIC
IS
BEGIN
RETURN p1 * 2;
END;
/
You might place this keyword in these places:
On a function defined in a CREATE FUNCTION statement
In a function declaration in a CREATE PACKAGE statement
On a method declaration in a CREATE TYPE statement
Do not repeat the keyword on the function or method body in a CREATE PACKAGE BODY or CREATE TYPE BODY statement.
Certain performance optimizations occur on invocations of functions that are marked DETERMINISTIC without any other action being required. These features require that any function used with them be declared DETERMINISTIC:
Any user-defined function used in a function-based index.
Any function used in a materialized view, if that view is to qualify for Fast Refresh or is marked ENABLE QUERY REWRITE.
The preceding functions features attempt to use previously calculated results rather than invoking the function when it is possible to do so.
It is good programming practice to make functions that fall into these categories DETERMINISTIC:
Functions used in a WHERE, ORDER BY, or GROUP BY clause
Functions that MAP or ORDER methods of a SQL type
Functions that help determine whether or where a row appears in a result set
Keep these points in mind when you create DETERMINISTIC functions:
The database cannot recognize if the action of the function is indeed deterministic. If the DETERMINISTIC keyword is applied to a function whose action is not truly deterministic, then the result of queries involving that function is unpredictable.
If you change the semantics of a DETERMINISTIC function and recompile it, then existing function-based indexes and materialized views report results for the prior version of the function. Thus, if you change the semantics of a function, you must manually rebuild any dependent function-based indexes and materialized views.
Oracle Database's parallel execution feature divides the work of running a SQL statement across multiple processes. Functions invoked from a SQL statement that is run in parallel might have a separate copy run in each of these processes, with each copy invoked for only the subset of rows that are handled by that process.
Each process has its own copy of package variables. When parallel execution begins, these are initialized based on the information in the package specification and body as if a user is logging into the system; the values in package variables are not copied from the original login session. And changes made to package variables are not automatically propagated between the various sessions or back to the original session. Java STATIC class attributes are similarly initialized and modified independently in each process. Because a function can use package (or Java STATIC) variables to accumulate some value across the various rows it encounters, Oracle Database cannot assume that it is safe to parallelize the execution of all user-defined functions.
For SELECT statements in Oracle Database versions before 8.1.5, the parallel query optimization allowed functions noted as both RNPS and WNPS in a PRAGMA RESTRICT_REFERENCES declaration to run in parallel. Functions defined with CREATE FUNCTION statements had their code implicitly examined to determine if they were pure enough; parallelized execution might occur even though a pragma cannot be specified on these functions.
For DML statements in Oracle Database versions before 8.1.5, the parallelization optimization looked to see if a function was noted as having all four of RNDS, WNDS, RNPS and WNPS specified in a PRAGMA RESTRICT_REFERENCES declaration; those functions that were marked as neither reading nor writing to either the database or package variables could run in parallel. Again, those functions defined with a CREATE FUNCTION statement had their code implicitly examined to determine if they were actually pure enough; parallelized execution might occur even though a pragma cannot be specified on these functions.
Oracle Database versions 8.1.5 and later continue to parallelize those functions that earlier versions recognize as parallelizable. The PARALLEL_ENABLE keyword is the preferred way to mark your code as safe for parallel execution. This keyword is syntactically similar to DETERMINISTIC as described in "Declaring a Function"; it is placed after the return value type in a declaration of the function, as in:
CREATE OR REPLACE FUNCTION f1 (
p1 NUMBER
) RETURN NUMBER PARALLEL_ENABLE
IS
BEGIN
RETURN p1 * 2;
END;
/
A PL/SQL function defined with CREATE FUNCTION might still be run in parallel without any explicit declaration that it is safe to do so, if the system can determine that it neither reads nor writes package variables nor invokes any function that might do so. A Java method or C function is never seen by the system as safe to run in parallel, unless the programmer explicitly indicates PARALLEL_ENABLE on the call specification, or provides a PRAGMA RESTRICT_REFERENCES indicating that the function is sufficiently pure.
An additional runtime restriction is imposed on functions run in parallel as part of a parallelized DML statement. Such a function is not permitted to in turn run a DML statement; it is subject to the same restrictions that are enforced on fun8$ctions that are run inside a query (SELECT) statement.
In Oracle Database versions before 8.1.5 (Oracle8i), programmers used PRAGMA RESTRICT_REFERENCES to assert the purity level of a subprogram. In subsequent versions, use the hints PARALLEL_ENABLE and DETERMINISTIC, instead, to communicate subprogram purity to Oracle Database.
You can remove PRAGMA RESTRICT_REFERENCES from your code. However, this pragma remains available for backward compatibility in these situations:
When it is impossible or impractical to edit existing code to completely remove PRAGMA RESTRICT_REFERENCES.
For example, if subprogram S1 depends on subprogram S2, and you do not remove the pragma from S1, then you might need the pragma in S2 to compile S1.
When replacing PRAGMA RESTRICT_REFERENCES in existing code with hints PARALLEL_ENABLE and DETERMINISTIC would negatively affect the action of new, dependent code. (Use PRAGMA RESTRICT_REFERENCES to preserve the action of the existing code.)
An existing PL/SQL application can thus continue using the pragma even on new functionality, to ease integration with the existing code. Do not use the pragma in a new application.
If you use PRAGMA RESTRICT_REFERENCES, place it in a package specification, not in a package body. It must follow the declaration of a subprogram, but it need not follow immediately. Only one pragma can reference a given subprogram declaration.
To code the PRAGMA RESTRICT_REFERENCES, use this syntax:
PRAGMA RESTRICT_REFERENCES (
Function_name, WNDS [, WNPS] [, RNDS] [, RNPS] [, TRUST] );
Where:
| Option | Description |
|---|---|
WNDS | The subprogram writes no database state (does not modify database tables). |
RNDS | The subprogram reads no database state (does not query database tables). |
WNPS | The subprogram writes no package state (does not change the values of package variables). |
RNPS | The subprogram reads no package state (does not reference the values of package variables) |
TRUST | The other restrictions listed in the pragma are not enforced; they are simply assumed to be true. This allows easy invocation from functions that have RESTRICT_REFERENCES declarations to those that do not. |
You can pass the arguments in any order. If any SQL statement inside the subprogram body violates a rule, then you get an error when the statement is parsed.
In Example 6-20, the function compound_ neither reads nor writes database or package state; therefore, you can assert the maximum purity level. Always assert the highest purity level that a subprogram allows, so that the PL/SQL compiler never rejects the subprogram unnecessarily.
Example 6-20 PRAGMA RESTRICT_REFERENCES
DROP TABLE accounts; -- in case it exists CREATE TABLE accounts ( acctno INTEGER, balance NUMBER ); INSERT INTO accounts (acctno, balance) VALUES (12345, 1000.00); CREATE OR REPLACE PACKAGE finance AS FUNCTION compound_ ( years IN NUMBER, amount IN NUMBER, rate IN NUMBER ) RETURN NUMBER; PRAGMA RESTRICT_REFERENCES (compound_, WNDS, WNPS, RNDS, RNPS); END finance; / CREATE PACKAGE BODY finance AS FUNCTION compound_ ( years IN NUMBER, amount IN NUMBER, rate IN NUMBER ) RETURN NUMBER IS BEGIN RETURN amount * POWER((rate / 100) + 1, years); END compound_; -- No pragma in package body END finance; / DECLARE interest NUMBER; BEGIN SELECT finance.compound_(5, 1000, 6) INTO interest FROM accounts WHERE acctno = 12345; END; /
Topics:
When PRAGMA RESTRICT REFERENCES includes the keyword TRUST, the restrictions listed in the pragma are assumed to be true, and not enforced.
When you invoke a subprogram that is in a section of code that does not use pragmas (such as a Java method), from a section of PL/SQL code that does use pragmas, specify PRAGMA RESTRICT REFERENCES with TRUST for either the invoked subprogram or the invoking subprogram.
In both Example 6-21 and Example 6-22, the PL/SQL function f invokes the Java procedure java_sleep. In Example 6-21, this is possible because java_sleep is declared to be WNDS with TRUST. In Example 6-22, it is possible because f is declared to be WNDS with TRUST, which allows it to invoke any subprogram.
Example 6-21 PRAGMA RESTRICT REFERENCES with TRUST on Invokee
CREATE OR REPLACE PACKAGE p IS PROCEDURE java_sleep (milli_seconds IN NUMBER) AS LANGUAGE JAVA NAME 'java.lang.Thread.sleep(long)'; PRAGMA RESTRICT_REFERENCES(java_sleep,WNDS,TRUST); FUNCTION f (n NUMBER) RETURN NUMBER; END p; / CREATE OR REPLACE PACKAGE BODY p IS FUNCTION f ( n NUMBER ) RETURN NUMBER IS BEGIN java_sleep(n); RETURN n; END f; END p; /
Example 6-22 PRAGMA RESTRICT REFERENCES with TRUST on Invoker
CREATE OR REPLACE PACKAGE p IS PROCEDURE java_sleep (milli_seconds IN NUMBER) AS LANGUAGE JAVA NAME 'java.lang.Thread.sleep(long)'; FUNCTION f (n NUMBER) RETURN NUMBER; PRAGMA RESTRICT_REFERENCES(f,WNDS,TRUST); END p; / CREATE OR REPLACE PACKAGE BODY p IS FUNCTION f ( n NUMBER ) RETURN NUMBER IS BEGIN java_sleep(n); RETURN n; END f; END p; /
Static INSERT, UPDATE, and DELETE statements do not violate RNDS if these statements do not explicitly read any database states, such as columns of a table. However, dynamic INSERT, UPDATE, and DELETE statements always violate RNDS, regardless of whether the statements explicitly read database states.
This INSERT statement violates RNDS if it is executed dynamically, but it does not violate RNDS if it is executed statically.
INSERT INTO my_table values(3, 'BOB');
This UPDATE statement always violates RNDS statically and dynamically, because it explicitly reads the column name of my_table.
UPDATE my_table SET id=777 WHERE name='BOB';
If a subprogram is overloaded, PRAGMA RESTRICT_REFERENCES applies only to the most recently declared version.
In Example 6-23, the pragma applies to the second declaration of valid.
In a data warehousing environment, you might use PL/SQL functions to transform large amounts of data. Perhaps the data is passed through a series of transformations, each performed by a different function. PL/SQL table functions let you perform such transformations without significant memory overhead or the need to store the data in tables between each transformation stage. These functions can accept and return multiple rows, can return rows as they are ready rather than all at once, and can be parallelized.
|
See Also: Oracle Database PL/SQL Language Reference for more information about performing multiple transformations with pipelined table functions |
To analyze a set of rows and compute a result value, you can code your own aggregate function that works the same as a SQL aggregate function like SUM:
Define an ADT that defines these member functions:
ODCIAggregateInitialize
ODCIAggregateIterate
ODCIAggregateMerge
ODCIAggregateTerminate
Code the member functions. In particular, ODCIAggregateIterate accumulates the result as it is invoked for each row that is processed. Store any intermediate results using the attributes of the ADT.
Create the aggregate function, and associate it with the ADT.
Call the aggregate function from SQL queries, DML statements, or other places that you might use the SQL aggregate functions. You can include typical options such as DISTINCT and ALL in the invocation of the aggregate function.
|
See Also: Oracle Database Data Cartridge Developer's Guide for more information about user-defined aggregate functions |
The Identity Code Package is a feature in the Oracle Database that offers tools and techniques to store, retrieve, encode, decode, and translate between various product or identity codes, including Electronic Product Code (EPC), in an Oracle Database. The Identity Code Package provides data types, metadata tables and views, and PL/SQL packages for storing EPC standard RFID tags or new types of RFID tags in a user table.
The Identity Code Package empowers Oracle Database with the knowledge to recognize EPC coding schemes, support efficient storage and component level retrieval of EPC data, and comply with the EPCglobal Tag Data Translation 1.0 (TDT) standard that defines how to decode, encode, and translate between various EPC RFID tag representations.
The Identity Code Package also provides an extensible framework that allows developers to use pre-existing coding schemes with their applications that are not included in the EPC standard and make the Oracle Database adaptable to these older systems and to any evolving identity codes that may some day be part of a future EPC standard.
The Identity Code Package also lets developers create their own identity codes by first registering the encoding category, registering the encoding type, and then registering the components associated with each encoding type.
Topics.
A database object MGD_ID is defined that lets users use EPC standard identity codes and use their own existing identity codes. See "Electronic Product Code (EPC) Concepts" for a brief description of EPC concepts. The MGD_ID object serves as the base code object to which belong certain categories, or types of the RFID tag, such as the EPC category, NASA category, and many other categories. Each category has a set of tag schemes or documents that define tag representation structures and their components. For the EPC category, the metadata needed to define encoding schemes (SGTIN-64, SGTIN-96, GID-96, and so forth) representing different encoding types (defined in the EPC standard v1.1) is loaded by default into the database. Users can define encoding their own categories and schemes as shown in Figure 17-1 and load these into the database as well.
Figure 17-1 RFID Code Categories and Their Schemes
An MGD_ID object contains two attributes, a category_id and a list of components consisting of name-value pairs. When MGD_ID objects are stored, the tag representation must be parsed into these component name-value pairs upon object creation.
EPC standard version 1.1 defines one General Identifier type (GID) that is independent of any known, existing code schemes, five Domain Identifier types that are based on EAN.UCC specifications, and the identity type United States Department of Defense (USDOD). The five EAN.UCC based identity types are the serialized global trade identification number (SGTIN), the serial shipping container code (SSCC), the serialized global location number (SGLN), the global returnable asset identifier (GRAI) and the global individual asset identifier (GIAI).
Except GID, which has only one bit-level encoding, all the other identity types each have two encodings depending on their length: 64-bit and 96-bit. So in total there are thirteen different standard encodings for EPC tags. In addition, tags can be encoded in representations other than binary, such as the tag URI and pure identity representations.
Each EPC encoding has its own structure and organization, see Table 17-1. The EPC encoding structure field names relate to the names in the parameter_list parameter name-value pairs in the Identity Code Package API. For example, for SGTIN-64, the structure field names are Filter Value, Company Prefix Index, Item Reference, and Serial Number.
Table 17-1 General Structure of EPC Encodings
| Encoding Name | Header Length in bits | Field Names (parameter_list name-value pairs) and (length in bits) |
|---|---|---|
|
GID-96 |
8 |
General Manager Number (8), Object Class (24), Serial Number (36) |
|
SGTIN-64 |
2 |
Filter Value (3), Company Prefix Index (14), Item Reference 20), Serial Number (25) |
|
SGTIN-96 |
8 |
Filter Value (3), Partition (3), Company Prefix (20-40), Item Reference (24-4), Serial Number (38) |
|
SSCC-64 |
8 |
Filter Value (3), Company Prefix Index (14), Serial Reference (39) |
|
SSCC-96 |
8 |
Filter Value (3), Partition (3), Company Prefix (20-40), Serial Reference (38-18), Unallocated (24) |
|
SGLN-64 |
8 |
Filter Value (3), Company Prefix Index (14), Location Reference (20), Serial Number (19) |
|
SGLN-96 |
8 |
Filter Value (3), Partition (3), Company Prefix (20-40), Location Reference (21-1), Serial Number (41) |
|
GRAI-64 |
8 |
Filter Value (3), Company Prefix Index (14), Asset Type (20), Serial Number (19) |
|
GRAI-96 |
8 |
Filter Value (3), Partition (3), Company Prefix (20-40), Asset Type (24-4), Serial Number (38) |
|
GIAI-64 |
8 |
Filter Value (3), Company Prefix Index (14), Individual Asset Reference (39) |
|
GIAI-96 |
8 |
Filter Value (3), Partition (3), Company Prefix (20-40), Individual Asset Reference (62-42) |
|
USDOD-64 |
8 |
Filter Value (2), Government Managed Identifier (30), Serial Number (24) |
|
USDOD-96 |
8 |
Filter Value (4), Government Managed Identifier (48), Serial Number (36) |
EPCglobal defines eleven tag schemes (GID-96, SGTIN-64, SGTIN-96, and so forth). Each of these schemes has various representations; today, the most often used are BINARY, TAG_URI, and PURE_IDENTITY. For example, information in an SGTIN-64 can be represented in these ways:
BINARY: 1001100000000000001000001110110001000010000011111110011000110010 PURE_IDENTITY: urn:epc:id:sgtin:0037000.030241.1041970 TAG_URI: urn:epc:tag:sgtin-64:3.0037000.030241.1041970 LEGACY: gtin=00037000302414;serial=1041970 ONS_HOSTNAME: 030241.0037000.sgtin.id.example.com
Some representations contain all information about the tag (BINARY and TAG_URI), while other representations contain only partial information (PURE_IDENTITY). It is therefore possible to translate a tag from its TAG_URI to its PURE_IDENTITY representation, but it is not possible to translate in the other direction without more information being provided, namely the filter value must be supplied.
EPCglobal released a Tag Data Translation 1.0 (TDT) standard that defines how to decode, encode, and translate between various EPC RFID tag representations. Decoding refers to parsing a given representation into field/value pairs, and encoding refers to reconstructing representations from these fields. Translating refers to decoding one representation and instantly encoding it into another.TDT defines this information using a set of XML files, each referred to as a scheme. For example, the SGTIN-64 scheme defines how to decode, encode, and translate between various SGTIN-64 representations, such as binary and pure identity. For details about the EPCglobal TDT schema, see the EPCglobal Tag Data Translation specification.
A key feature of the TDT specification is its ability to define any EPC scheme using the same XML schema. This approach creates a standard way of defining EPC metadata that RFID applications can then use to write their parsers, encoders, and translators. When the application is written according to the TDT specification, it must be able to update its set of EPC tag schemes and modify its action according to the metadata.
The Oracle Database metadata structure is similar, but not identical to the TDT standard. To fit the EPCglobal TDT specification, the Oracle RFID package must be able to ingest any TDT compatible scheme and seamlessly translate it into the generic Oracle Database defined metadata. See the EPC_TO_ORACLE Function in Table 17-4 for more information.
Reconstructing tag representation from fields, or in other words, encoding tag data into predefined representations is easily accomplished using the MGD_ID.format function. Likewise, the decoding of tag representations into MGD_ID objects and then encoding these objects into tag representations is also easily accomplished using the MGDID.translate function. See the FORMAT Member Function and the TRANSLATE Static Function in Table 17-3 for more information.
Because the EPCglobal TDT standard is powerful and highly extensible, the Oracle RFID standard metadata is a close relative of the TDT specification. See "Oracle Database Tag Data Translation Schema" for the actual Oracle Database TDT XML schema. Developers can refer to this Oracle Database TDT XML schema to define their own tag structures.
Figure 17-2 shows the Oracle Database Tag Data Translation Markup Language Schema diagram.
Figure 17-2 Oracle Database Tag Data Translation Markup Language Schema
The top level element in a tag data translation xml is 'scheme'. Each scheme defines various tag encoding representations, or levels. SGTIN-64 and GID-96 are examples of tag encoding schemes, and BINARY or PURE_IDENTITY are examples of levels within these schemes. Each level has a set of options that define how to parse various representations into fields, and rules that define how to derive values for fields that require additional work, such as an external table lookup or the concatenation of other parsed out fields. See the EPCGlobal Tag Translator Specification for more information.
The Identity Code Package provides an extensible framework that supports the current RFID tags with the standard family of EPC bit encodings for the supported encoding types and new and evolving tag encodings that are not included in the current EPC standard.
The Identity Code Package defines these ADTs:
MGD_ID -- defines these (see MGD_ID ADT in Table 17-2 for more information):
Two attributes, category_id and components.
Four MGD_ID constructor functions for constructing identity code type objects to represent RFID tags.
A set of member subprograms for operating on these ADTs.
"Using the Identity Code Package" describes how to use these ADTs and member functions.
"Identity Code Package Types" and "DBMS_MGD_ID_UTL Package" briefly describe the reference information for these ADTs along with a set of utility subprograms. See Oracle Database PL/SQL Packages and Types Reference for detailed reference information.
MGD_ID_COMPONENT — defines two attributes, comp_name, which identifies the name of the component and comp_value, which identifies the components value.
MGD_ID_COMPONENT_VARRAY — defines an array type that can store up to 128 elements of MGD_IDCOMPONENT type, which is used in two constructor functions for creating an identity code type object with a list of components.
The Identity Code Package supports EPC spec v1.1 by supplying the predefined EPC_ENCODING_CATEGORY encoding_category attribute definition with its bit-encoding structures for the supported encoding types. This information is stored as meta information in the supplied encoding metadata views, MGD_USR_ID_CATEGORY, MGD_USR_ID_SCHEME, the read-only views MGD_ID_CATEGORY, MGD_ID_SCHEME, and their underlying tables: MGD_ID_CATEGORY_TAB, MGD_ID_SCHEME_TAB, MGD_ID_XML_VALIDATOR. See these topics and files for more information:
"Electronic Product Code (EPC) Concepts" describes the EPC spec v1.1 product code and its family of coding schemes.
"Identity Code Metadata Tables and Views" describes the structure of the identity code meta tables and views and how metadata are used by the Identity Code Package to interpret the various RFID tags.
The mgdmeta.sql file describes the meta table data for the EPC_ENCODING_CATEGORY categories and each of its specific encoding schemes.
After storing many thousands of RFID tags into the column of MGD_ID column type of your user table, you can improve query performance by creating an index on this column. See these topics for more information:
"Building a Function-Based Index Using the Member Functions of the MGD_ID Column Type" describes how to create a function based index or bitmap function based index using the member functions of the MGD_ID ADT.
The Identity Code Package provides a utility package that consists of various utility subprograms. See this topic for more information:
"Identity Code Package Types" and "DBMS_MGD_ID_UTL Package" describes each of the member subprograms. A proxy utility sets and removes proxy information. A metadata utility gets a category ID, refreshes a tag scheme for a category, removes a tag scheme for a category, and validates a tag scheme. A conversion utility translates standard EPCglobal Tag Data Translation (TDT) files into Oracle Database TDT files.
The Identity Code Package is extensible and lets you create your own identity code types for your new or evolving RFID tags. You can define your identity code types, catagory_id attribute values, and components structures for your own encoding types. See these topics for more information:
"Creating a Category of Identity Codes" describes how to create your own identity codes by first registering the encoding category, and then registering the schemes associated to the encoding category.
"Identity Code Metadata Tables and Views" describes the structure of the identity code meta tables and views and how to register meta information by storing it in the supplied metadata tables and views.
Topics:
Building a Function-Based Index Using the Member Functions of the MGD_ID Column Type
Defining a Category of Identity Codes and Adding Encoding Schemes to an Existing Category
Topics:
You can create tables using MGD_ID as the column type to represent RFID tags, for example:
Example 1. Using the MGD_ID column type:
CREATE TABLE Warehouse_info (
Code MGD_ID,
Arrival_time TIMESTAMP,
Location VARCHAR2(256);
...);
SQL*Plus command:
describe warehouse_info;
Result:
Name Null? Type ----------------------------------------- -------- ---------------------------- CODE NOT NULL MGDSYS.MGD_ID ARRIVAL_TIME TIMESTAMP(6) LOCATION VARCHAR2(256)
There are several ways to construct MGD_ID objects:
If a RFID tag complies to the EPC standard, an MGD_ID object can be created using its category ID and a list of components. For example:
call DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
call DBMS_MGD_ID_UTL.refresh_category('1');
select MGD_ID ('1',
MGD_ID_COMPONENT_VARRAY(
MGD_ID_COMPONENT('companyprefix','0037000'),
MGD_ID_COMPONENT('itemref','030241'),
MGD_ID_COMPONENT('serial','1041970'),
MGD_ID_COMPONENT('schemes','SGTIN-64')
)
) from DUAL;
call DBMS_MGD_ID_UTL.remove_proxy();
@constructor11.sql
.
.
.
MGD_ID ('1', MGD_ID_COMPONENT_VARRAY
(MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('itemref', '030241'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64')))
.
.
.
Use this constructor when there is a list of additional parameters required to create the MGD_ID object. For example:
call DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
call DBMS_MGD_ID_UTL.refresh_category('1');
select MGD_ID('1',
'urn:epc:id:sgtin:0037000.030241.1041970',
'filter=3;scheme=SGTIN-64') from DUAL;
call DBMS_MGD_ID_UTL.remove_proxy();
@constructor22.sql
.
.
.
MGD_ID('1', MGD_ID_COMPONENT_VARRAY(MGD_ID_COMPONENT('filter', '3'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64'),
MGD_ID_COMPONENT('companyprefixlength', '7'),
MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('scheme', 'SGTIN-64'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('itemref', '030241')))
.
.
.
Use this constructor when a category version must be specified along with a category ID and a list of components. For example:
call DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
call DBMS_MGD_ID_UTL.refresh_category
(DBMS_MGD_ID_UTL.get_category_id('EPC', NULL));
select MGD_ID('EPC', NULL,
MGD_ID_COMPONENT_VARRAY(
MGD_ID_COMPONENT('companyprefix','0037000'),
MGD_ID_COMPONENT('itemref','030241'),
MGD_ID_COMPONENT('serial','1041970'),
MGD_ID_COMPONENT('schemes','SGTIN-64')
)
) from DUAL;
call DBMS_MGD_ID_UTL.remove_proxy();
@constructor33.sql
.
.
.
MGD_ID('1', MGD_ID_COMPONENT_VARRAY
(MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('itemref', '030241'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64')
)
)
.
.
.
Use this constructor when the category version and an additional list of parameters is required.
call DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
call DBMS_MGD_ID_UTL.refresh_category
(DBMS_MGD_ID_UTL.get_category_id('EPC', NULL));
select MGD_ID('EPC', NULL,
'urn:epc:id:sgtin:0037000.030241.1041970',
'filter=3;scheme=SGTIN-64') from DUAL;
call DBMS_MGD_ID_UTL.remove_proxy();
@constructor44.sql
.
.
.
MGD_ID('1', MGD_ID_COMPONENT_VARRAY
(MGD_ID_COMPONENT('filter', '3'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64'),
MGD_ID_COMPONENT('companyprefixlength', '7'),
MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('scheme', 'SGTIN-64'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('itemref', '030241')
)
)
.
.
.
This example shows how to populate the WAREHOUSE_INFO table by inserting each MGD_ID object into the table along with the additional column values:
call DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
call DBMS_MGD_ID_UTL.refresh_category
(DBMS_MGD_ID_UTL.get_category_id('EPC', NULL));
INSERT INTO WAREHOUSE_INFO (code, arrival_time, location)
values (MGDSYS.MGD_ID ('EPC',
NULL,
'urn:epc:id:sgtin:0037000.030241.1041970',
null
),
SYSDATE,
'SHELF_123');
INSERT INTO WAREHOUSE_INFO (code, arrival_time, location)
values (MGDSYS.MGD_ID ('EPC',
NULL,
'urn:epc:id:sgtin:0037000.053021.1012353',
null
),
SYSDATE,
'SHELF_456');
INSERT INTO WAREHOUSE_INFO (code, arrival_time, location)
values (MGDSYS.MGD_ID ('EPC',
NULL,
'urn:epc:id:sgtin:0037000.020140.10174832',
null
),
SYSDATE,
'SHELF_1034');
COMMITT;
call DBMS_MGD_ID_UTL.remove_proxy();
There are three ways to query on MGD_ID column type.
Query the MGD_ID column type. Find all items with item reference 030241.
SELECT location, wi.code.get_component('itemref') as itemref,
wi.code.get_component('serial') as serial
FROM warehouse_info wi WHERE wi.code.get_component('itemref') = '030241';
LOCATION |ITEMREF |SERIAL
---------------|----------|----------
SHELF_123 |030241 |1041970
Query using the member functions of the MGD_ID ADT. Select the pure identity representations of all RFID tags in the table.
SELECT wi.code.format(null,'PURE_IDENTITY') as PURE_IDENTITY FROM warehouse_info wi; PURE_IDENTITY ------------------------------------------------------------------------------- urn:epc:id:sgtin:0037000.030241.1041970 urn:epc:id:gid:0037000.053021.1012353 urn:epc:id:sgtin:003700 0.020140.10174832
See "Using the get_component Function with the MGD_ID Object" for more information and see Table 17-3 for a list of member functions.
You can improve the performance of queries based on a certain component of the RFID tags by creating a function-based index that uses the get_component member function or its variation convenience functions. For example:
CREATE INDEX warehouseinfo_idx2
on warehouse_info(code.get_component('itemref'));
You can also improve the performance of queries based on a certain component of the RFID tags by creating a bitmap function based index that uses the get_component member function or its variation convenience functions. For example:
CREATE BITMAP INDEX warehouseinfo_idx3
on warehouse_info(code.get_component('serial'));
The MGD_ID ADT contains member subprograms that operate on these ADTs. See Table 17-2 for MGD_ID_COMPONENT, MGD_ID_COMPONENT_VARRAY, MGD_ID ADT reference information. See the mgdtyp.sql file for the MGD_ID ADT definition and its member subprograms.
Topics:
The get_component function is defined as follows:
MEMBER FUNCTION get_component(component_name IN VARCHAR2) RETURN VARCHAR2 DETERMINISTIC,
Each component in a identity code has a name. It is defined when the code type is registered. See "Defining a Category of Identity Codes and Adding Encoding Schemes to an Existing Category" for more information about how to create a identity code type.
The get_component function takes the name of the component, component_name as a parameter, uses the metadata registered in the metadata table to analyze the identity code, and returns the component with the name component_name.
The get_component function can be used in a SQL query. For example, find the current location of the coded item for the component named itemref; or, in other words find all items with the item reference of 03024. Because the code tag has encoded the "itemref" as a component, you can use this SQL query:
SELECT location,
w.code.get_component('itemref') as itemref,
w.code.get_component('serial') as serial
FROM warehouse_info w
WHERE w.code.get_component('itemref') = '030241';
LOCATION |ITEMREF |SERIAL
---------------|----------|----------
SHELF_123 |030241 |1041970
See Table 17-3 for a list of other member functions.
RFID readers read the bit strings stored in the tags. The tag data and other information, such as the reader ID and the time stamp, first go through an edge server to be processed, normalized, and preliminarily filtered. Then, in many application scenarios, the information must be persistently stored and later on be retrieved. The Oracle Database understands the code structures representations of various EPC tags as described in Table 17-1 because these code representation schemes defined in the EPC Standard are pre-registered. This gives the Oracle Database the ability to understand all the EPC code schemes and parse various tag representations into fields. Users can also register their own coding structures for the identity codes that use other encoding technologies. In this way the system is extensible.
As mentioned in "Identity Concepts", each of the EPCGlobal tag schemes (GID-96, SGTIN-64, SGTIN-96, and so forth) has various representations with the most often used ones being BINARY, TAG_URI, and PURE_IDENTITY.
Some representations contain all the information about the tag (BINARY and TAG_URI), while representations contain only partial information (PURE_IDENTITY). It is therefore possible to translate a tag from it's TAG_URI to it's PURE_IDENTITY representation, but it is not possible to translate in the other direction (PURE_IDENTITY to TAG_URI) without supplying more information, namely the filter value.
One MGD_ID constructor takes in four fields, the category name (such as EPC), the category version, the tag identifier (for EPC, the identifier must be in a representation previously described), and a parameter list for any additional parameters that may be required to parse the tag representation. For example, this code creates an MGD_ID object from its BINARY representation.
SELECT MGD_ID
('EPC',
null,
'1001100000000000001000001110110001000010000011111110011000110010',
null
)
AS NEW_RFID_CODE FROM DUAL;
NEW_RFID_CODE(CATEGORY_ID, COMPONENTS(NAME, VALUE))
--------------------------------------------------------------------------------
MGD_ID ('1',
MGD_ID_COMPONENT_VARRAY(MGD_ID_COMPONENT('filter', '3'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64'),
MGD_ID_COMPONENT('companyprefixlength', '7'),
MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('companyprefixindex', '1'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('itemref', '030241')
)
)
For example, an identical object can be created if the call is done with the TAG_URI representation of the tag as follows with the addition of the value of the filter value:
SELECT MGD_ID ('EPC',
null,
'urn:epc:tag:sgtin-64:3.0037000.030241.1041970',
null
)
as NEW_RFID_CODE FROM DUAL;
NEW_RFID_CODE(CATEGORY_ID, COMPONENTS(NAME, VALUE))
--------------------------------------------------------------------------------
MGD_ID ('1',
MGD_ID_COMPONENT_VARRAY (
( MGD_ID_COMPONENT('filter', '3'),
MGD_ID_COMPONENT('schemes', 'SGTIN-64'),
MGD_ID_COMPONENT('companyprefixlength', '7'),
MGD_ID_COMPONENT('companyprefix', '0037000'),
MGD_ID_COMPONENT('serial', '1041970'),
MGD_ID_COMPONENT('itemref', '030241')
)
)
Another useful feature of the Identity Code package is the ability to encode tag data into predefined representations. For example, a warehouse wants to send certain inventory to a retailer, but first it wants to send an invoice that tells the retailer what inventory to expect. The invoice can be a list of pure identity URIs that the warehouse intends to send. If all the inventory in the WAREHOUSE_INFO table is to be sent, this example constructs the desired URIs:
SELECT wi.code.format (null,'PURE_IDENTITY') as PURE_IDENTITY FROM warehouse_info wi; PURE_IDENTITY -------------------------------------------------------------------------------- urn:epc:id:sgtin:0037000.030241.1041970 urn:epc:id:gid:0037000.053021.1012353 urn:epc:id:sgtin:0037000.020140.10174832
The Identity Code package can decode tag representations into MGD_ID objects and encode these objects into tag representations. These two steps can be combined into one step using the MGD_ID.translate function. Static translation allows for the conversion of an RFID tag from one representation to another. For example:
SELECT MGD_ID.translate ('EPC',
null,
'urn:epc:id:sgtin:0037000.030241.1041970',
'filter=3;scheme=SGTIN-64',
'BINARY'
)
as BINARY FROM DUAL;
BINARY
--------------------------------------------------------------------------------
1001100000000000001000001110110001000010000011111110011000110010
In this example, the binary representation contains more information than the pure identity representation. Specifically, it also contains the filter value and in this case the scheme value must also be specified to distinguish SGTIN-64 from SGTIN-96. Thus, the function call must provide the missing filter parameter information and specify the scheme name in order for translation call to succeed.
Because the EPCglobal TDT standard is powerful and highly extensible, the Oracle Database RFID standard metadata is a close relative of the TDT specification. Thus, the Identity Code package is extensible: You can create your own categories and tag structures using generic metadata. To create a category of identity codes, use the DBMS_MGD_ID_UTIL.create_category function.
For example, suppose you want to create a category called MGD_SAMPLE_CATEGORY, which has two types of tags, a CONTRACTOR_TAG and an EMPLOYEE_TAG. This category and its two metadata schemes might be used within a company that must grant different access privileges to people who are full time employees from those who are contractors, and thus require that their security software be able to identify quickly between the two badge types at an RFID reader. This script creates a category named 'MGD_SAMPLE_CATEGORY', with a 1.0 category version, having an agency name as Oracle, with a URI as http://www.oracle.com/mgd/sample. See "Adding Two Metadata Schemes to a Newly Created Category" for an example.
Next, create an CONTRACTOR_TAG metadata scheme such as:
<?xml version="1.0" encoding="UTF-8"?>
<TagDataTranslation version="0.04" date="2005-04-18T16:05:00Z"
xmlns:xsi="http://www.w3.org/2001/XMLSchema"
xmlns="oracle.mgd.idcode">
<scheme name="CONTRACTOR_TAG" optionKey="1" xmlns="">
<level type="URI" prefixMatch="mycompany.contractor.">
<option optionKey="1" pattern="mycompany.contractor.([0-9]*).([0-9]*)"
grammar="''mycompany.contractor.'' contractorID ''.'' divisionID">
<field seq="1" characterSet="[0-9]*" name="contractorID"/>
<field seq="2" characterSet="[0-9]*" name="divisionID"/>
</option>
</level>
<level type="BINARY" prefixMatch="11">
<option optionKey="1" pattern="11([01]{7})([01]{6})"
grammar="''11'' contractorID divisionID ">
<field seq="1" characterSet="[01]*" name="contractorID"/>
<field seq="2" characterSet="[01]*" name="divisionID"/>
</option>
</level>
</scheme>
</TagDataTranslation>
The CONTRACTOR_TAG scheme contains two encoding levels, or ways in which the tag can be represented. The first level is URI and the second level is BINARY. The URI representation starts with the prefix "mycompany.contractor." and is then followed by two numeric fields separated by a period. The names of the two fields are contractorID and divisionID. The pattern field in the option tag defines the parsing structure of the tag URI representation, and the grammar field defines how to reconstruct the URI representation. The BINARY representation can be understood in a similar fashion. This representation starts with the prefix "01" and is then followed by the same two fields, contractorID and divisionID, this time, in their respective binary formats. Given this XML metadata structure, contractor tags can now be decoded from their URI and BINARY representations and the resulting fields can be re-encoded into one of these representations.
The EMPLOYEE_TAG scheme is defined in a similar fashion and is shown as follows.
<?xml version="1.0" encoding="UTF-8"?>
<TagDataTranslation version="0.04" date="2005-04-18T16:05:00Z"
xmlns:xsi="http://www.w3.org/2001/XMLSchema"
xmlns="oracle.mgd.idcode">
<scheme name="EMPLOYEE_TAG" optionKey="1" xmlns="">
<level type="URI" prefixMatch="mycompany.employee.">
<option optionKey="1" pattern="mycompany.employee.([0-9]*).([0-9]*)"
grammar="''mycompany.employee.'' employeeID ''.'' divisionID">
<field seq="1" characterSet="[0-9]*" name="employeeID"/>
<field seq="2" characterSet="[0-9]*" name="divisionID"/>
</option>
</level>
<level type="BINARY" prefixMatch="01">
<option optionKey="1" pattern="01([01]{7})([01]{6})"
grammar="''01'' employeeID divisionID ">
<field seq="1" characterSet="[01]*" name="employeeID"/>
<field seq="2" characterSet="[01]*" name="divisionID"/>
</option>
</level>
</scheme>
</TagDataTranslation>;
To add these schemes to the category ID previously created, use the DBMS_MGD_ID_UTIL.add_scheme function.
This script creates the MGD_SAMPLE_CATEGORY category, adds a contractor scheme and an employee scheme to the MGD_SAMPLE_CATEGORY category, validates the MGD_SAMPLE_CATEGORY scheme, tests the tag translation of the contractor scheme and the employee scheme, then removes the contractor scheme, tests the tag translation of the contractor scheme and this returns the expected exception for the removed contractor scheme, tests the tag translation of the employee scheme and this returns the expected values, then removes the MGD_SAMPLE_CATEGORY category:
--contents of add_scheme2.sql
SET LINESIZE 160
CALL DBMS_MGD_ID_UTL.set_proxy('www-proxy.us.oracle.com', '80');
---------------------------------------------------------------------
---CREATE CATEGORY, ADD_SCHEME, REMOVE_SCHEME, REMOVE_CATEGORY-------
---------------------------------------------------------------------
DECLARE
amt NUMBER;
buf VARCHAR2(32767);
pos NUMBER;
tdt_xml CLOB;
validate_tdtxml VARCHAR2(1042);
category_id VARCHAR2(256);
BEGIN
-- remove the testing category if it exists
DBMS_MGD_ID_UTL.remove_category('MGD_SAMPLE_CATEGORY', '1.0');
-- create the testing category 'MGD_SAMPLE_CATEGORY', version 1.0
category_id := DBMS_MGD_ID_UTL.CREATE_CATEGORY('MGD_SAMPLE_CATEGORY', '1.0', 'Oracle',
'http://www.oracle.com/mgd/sample');
-- add contractor scheme to the category
DBMS_LOB.CREATETEMPORARY(tdt_xml, true);
DBMS_LOB.OPEN(tdt_xml, DBMS_LOB.LOB_READWRITE);
buf := '<?xml version="1.0" encoding="UTF-8"?>
<TagDataTranslation version="0.04" date="2005-04-18T16:05:00Z"
xmlns:xsi="http://www.w3.org/2001/XMLSchema"
xmlns="oracle.mgd.idcode">
<scheme name="CONTRACTOR_TAG" optionKey="1" xmlns="">
<level type="URI" prefixMatch="mycompany.contractor.">
<option optionKey="1" pattern="mycompany.contractor.([0-9]*).([0-9]*)"
grammar="''mycompany.contractor.'' contractorID ''.'' divisionID">
<field seq="1" characterSet="[0-9]*" name="contractorID"/>
<field seq="2" characterSet="[0-9]*" name="divisionID"/>
</option>
</level>
<level type="BINARY" prefixMatch="11">
<option optionKey="1" pattern="11([01]{7})([01]{6})"
grammar="''11'' contractorID divisionID ">
<field seq="1" characterSet="[01]*" name="contractorID"/>
<field seq="2" characterSet="[01]*" name="divisionID"/>
</option>
</level>
</scheme>
</TagDataTranslation>';
amt := length(buf);
pos := 1;
DBMS_LOB.WRITE(tdt_xml, amt, pos, buf);
DBMS_LOB.CLOSE(tdt_xml);
DBMS_MGD_ID_UTL.ADD_SCHEME(category_id, tdt_xml);
-- add employee scheme to the category
DBMS_LOB.CREATETEMPORARY(tdt_xml, true);
DBMS_LOB.OPEN(tdt_xml, DBMS_LOB.LOB_READWRITE);
buf := '<?xml version="1.0" encoding="UTF-8"?>
<TagDataTranslation version="0.04" date="2005-04-18T16:05:00Z"
xmlns:xsi="http://www.w3.org/2001/XMLSchema"
xmlns="oracle.mgd.idcode">
<scheme name="EMPLOYEE_TAG" optionKey="1" xmlns="">
<level type="URI" prefixMatch="mycompany.employee.">
<option optionKey="1" pattern="mycompany.employee.([0-9]*).([0-9]*)"
grammar="''mycompany.employee.'' employeeID ''.'' divisionID">
<field seq="1" characterSet="[0-9]*" name="employeeID"/>
<field seq="2" characterSet="[0-9]*" name="divisionID"/>
</option>
</level>
<level type="BINARY" prefixMatch="01">
<option optionKey="1" pattern="01([01]{7})([01]{6})"
grammar="''01'' employeeID divisionID ">
<field seq="1" characterSet="[01]*" name="employeeID"/>
<field seq="2" characterSet="[01]*" name="divisionID"/>
</option>
</level>
</scheme>
</TagDataTranslation>';
amt := length(buf);
pos := 1;
DBMS_LOB.WRITE(tdt_xml, amt, pos, buf);
DBMS_LOB.CLOSE(tdt_xml);
DBMS_MGD_ID_UTL.ADD_SCHEME(category_id, tdt_xml);
-- validate the scheme
dbms_output.put_line('Validate the MGD_SAMPLE_CATEGORY Scheme');
validate_tdtxml := DBMS_MGD_ID_UTL.validate_scheme(tdt_xml);
dbms_output.put_line(validate_tdtxml);
dbms_output.put_line('Length of scheme xml is: '||DBMS_LOB.GETLENGTH(tdt_xml));
-- test tag translation of contractor scheme
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'mycompany.contractor.123.45',
NULL, 'BINARY'));
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'111111011101101',
NULL, 'URI'));
-- test tag translation of employee scheme
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'mycompany.employee.123.45',
NULL, 'BINARY'));
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'011111011101101',
NULL, 'URI'));
DBMS_MGD_ID_UTL.REMOVE_SCHEME(category_id, 'CONTRACTOR_TAG');
-- Test tag translation of contractor scheme. Doesn't work any more.
BEGIN
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'mycompany.contractor.123.45',
NULL, 'BINARY'));
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'111111011101101',
NULL, 'URI'));
EXCEPTION
WHEN others THEN
dbms_output.put_line('Contractor tag translation failed: '||SQLERRM);
END;
-- Test tag translation of employee scheme. Still works.
BEGIN
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'mycompany.employee.123.45',
NULL, 'BINARY'));
dbms_output.put_line(
mgd_id.translate('MGD_SAMPLE_CATEGORY', NULL,
'011111011101101',
NULL, 'URI'));
EXCEPTION
WHEN others THEN
dbms_output.put_line('Employee tag translation failed: '||SQLERRM);
END;
-- remove the testing category, which also removes all the associated schemes
DBMS_MGD_ID_UTL.remove_category('MGD_SAMPLE_CATEGORY', '1.0');
END;
/
SHOW ERRORS;
call DBMS_MGD_ID_UTL.remove_proxy();
@add_scheme3.sql
.
.
.
Validate the MGD_SAMPLE_CATEGORY Scheme
EMPLOYEE_TAG;URI,BINARY;divisionID,employeeID
Length of scheme xml is: 933
111111011101101
mycompany.contractor.123.45
011111011101101
mycompany.employee.123.45
Contractor tag translation failed: ORA-55203: Tag data translation level not found
ORA-06512: at "MGDSYS.DBMS_MGD_ID_UTL", line 54
ORA-06512: at "MGDSYS.MGD_ID", line 242
ORA-29532: Java call terminated by uncaught Java
exception: oracle.mgd.idcode.exceptions.TDTLevelNotFound: Matching level not
found for any configured scheme
011111011101101
mycompany.employee.123.45
.
.
.
Table 17-2 describes the Identity Code Package ADTs.
Table 17-2 Identity Code Package ADTs
| ADT Name | Description |
|---|---|
|
|
A data type that specifies the name and value pair attributes that define a component. |
|
A data type that specifies a list of up to 128 components as name-value attribute pairs used in two constructor functions for creating an identity code type object. | |
|
|
Represents an identity code type that specifies the category identifier for the code category for this identity code and its list of components. |
Table 17-3 describes the subprograms in the MGD_ID ADT.
All the values and names passed to the subprograms defined in the MGD_ID ADT are case-insensitive unless otherwise noted. To preserve case, enclose values in double quotation marks.
Table 17-3 MGD_ID ADT Subprograms
| Subprogram | Description |
|---|---|
|
|
Creates an identity code type object, |
|
|
Returns a representation of an identity code given an |
|
|
Returns the value of an |
|
|
Concatenates the |
|
|
Translates one |
Table 17-4 describes the Utility subprograms in the DBMS_MGD_ID_UTL package.
All the values and names passed to the subprograms defined in the MGD_ID ADT are case-insensitive unless otherwise noted. To preserve case, enclose values in double quotation marks.
Table 17-4 DBMS_MGD_ID_UTL Package Utility Subprograms
| Subprogram | Description |
|---|---|
|
|
Adds a tag data translation scheme to an existing category. |
|
|
Creates a category or a version of a category. |
|
|
Converts the EPCglobal tag data translation (TDT) XML to Oracle Database tag data translation XML. |
|
|
Returns the category ID given the category name and the category version. |
|
|
Returns all relevant separated component names separated by semicolon (';') for the specified scheme. |
|
|
Returns a list of semicolon (';') separated encodings (formats) for the specified scheme. |
|
|
Returns an integer representing the current Java trace logging level. |
|
|
Returns an integer representing the current PL/SQL trace logging level. |
|
|
Returns a list of semicolon (';') separated scheme names for the specified category. |
|
|
Returns the Oracle Database tag data translation XML for the specified scheme. |
|
|
Returns the Oracle Database tag data translation schema. |
|
|
Refreshes the metadata information about the Java stack for the specified category. |
|
|
Removes a category including all the related TDT XML. |
|
|
Unsets the host and port of the proxy server. |
|
|
Removes the tag scheme for a category. |
|
|
Sets the Java logging level. |
|
|
Sets the PL/SQL tracing logging level. |
|
|
Sets the host and port of the proxy server for Internet access. |
|
|
Validates the input tag data translation XML against the Oracle Database tag data translation schema. |
This topic describes the structure of identity code metadata tables and views and explains how the metadata are used by the Identity Code Package to interpret the various RFID tags. The creation of these meta tables, views, and triggers is done automatically during the Identity Code Package installation.
Encoding metadata views are used to store encoding categories and schemes. Application developers can insert the meta information of their own identity codes into these views. The MGD_ID ADT is designed to understand the encodings if the metadata for the encodings are stored in the meta tables. If an application developer only uses the encodings defined in the EPC specification v1.1, the developer does not have to worry about the meta tables because product codes specified in EPC spec v1.1 are predefined.
There are two encoding metadata views.
user_mgd_id_category — this view is used to store the encoding category information defined by the session user.
user_mgd_id_scheme — this view is used to store the encoding type information defined by the session user.
In addition, these read-only views are defined for a user to query the system predefined encoding metadata and the metadata defined by the user:
mgd_id_category — this view is used to query the encoding category information defined by the system or the session user
mgd_id_scheme — this view is used to query the encoding type information defined by the system or the session user.
The underlying metadata tables for the preceding views are:
mgd_id_xml_validator
mgd_id_category_tab
mgd_id_scheme_tab
Users other than the Identity Code Package system users cannot operate on these tables. Users must not use the metadata tables directly. They must use the read only views and the metadata functions described in the DBMS_MGD_ID_UTL package.
|
See Also: Oracle Database PL/SQL Packages and Types Reference for information about theDBMS_MGD_ID_UTL package |
Metadata View Definitions
Table 17-5, Table 17-6, Table 17-7, and Table 17-8 describe the metadata view definitions for the MGD_ID_CATEGORY, USER_ID_CATEGORY, MGD_ID_SCHME, and USER_MGD_ID_SCHME respectively as defined in the mgdview.sql file.
Table 17-5 Definition and Description of the MGD_ID_CATEGORY Metadata View
| Column Name | Data Type | Description |
|---|---|---|
|
|
|
Category identifier |
|
|
|
Category name |
|
|
|
Organization that defined the category |
|
|
|
Category version |
|
|
|
URI that describes the category |
Table 17-6 Definition and Description of the USER_MGD_ID_CATEGORY Metadata View
| Column Name | Data Type | Description |
|---|---|---|
|
|
|
Category identifier |
|
|
|
Category name |
|
|
|
Organization that defined the category |
|
|
|
Category version |
|
|
|
URI that describes the category |
Table 17-7 Definition and Description of the MGD_ID_SCHEME Metadata View
| Column Name | Data Type | Description |
|---|---|---|
|
|
|
Category identifier |
|
|
|
Encoding scheme name, for example, SGTIN-96, GID-96, and so forth |
|
|
|
Tag data translation XML for this encoding scheme |
|
|
|
Encodings separated by a comma (,), for example, |
|
|
|
Relevant component names, extracted from each level and then combined. Each is separated by a comma (,). For example, objectclass, generalmanager, serial (for GID-96) |
Table 17-8 Definition and Description of the USER_MGD_ID_SCHEME Metadata View
| Column Name | Data Type | Description |
|---|---|---|
|
|
|
Category identifier |
|
|
|
Encoding scheme name, for example, SGTIN-96, GID-96, and so forth |
|
|
|
Tag data translation XML for this encoding scheme |
|
|
|
Encodings separated by a comma (,), for example, |
|
|
|
Relevant component names, extracted from each level and then combined. Each is separated by a comma (,). For example, objectclass, generalmanager, serial (for GID-96) |
Topics:
Radio Frequency Identification (RFID) technology continues to gain momentum with suppliers, distributors, manufacturers, and retailers for its ability to eliminate line-of-site processes and automate critical supply chain transactions. Electronic Product Code (EPC), an identification scheme for universally identifying objects using RFID tags and other means, is gaining widespread acceptance as an emerging standard. Its capabilities enable companies to reduce warehouse and distribution costs through improved inventory control and extended supply chain visibility.
The standardized EPC Identifier is a metacoding scheme designed to support the needs of various industries. Therefore, the EPC represents a family of coding schemes and a means to make them unique across all possible EPC-compliant tags. EPC Version 1.1 includes these specific coding schemes:
General Identifier (GID)
Serialized version of the EAN.UCC Global Trade Item Number (GTIN)
EAN.UCC Serial Shipping Container Code (SSCC)
EAN.UCC Global Location Number (GLN)
EAN.UCC Global Returnable Asset Identifier (GRAI)
EAN.UCC Global Individual Asset Identifier (GIAI)
RFID applications require the storage of a large volume of EPC data into a database. The efficient use of EPC data also requires that the database recognizes the different coding schemes of EPC data.
EPC is an emerging standard. It does not cover all the numbering schemes used in the various industries and is itself still evolving (the changes from EPC version 1.0 to EPC version 1.1 are significant).
Identity Code Package empowers the Oracle Database with the knowledge to recognize EPC coding schemes. It makes the Oracle Database a database system that not only provides efficient storage and component level retrieval for EPC data, but also has features to support EPC data encoding and decoding, and conversion between bit encoding and URI encoding.
Identity Code Package provides an extensible framework that allows developers to define their own coding schemes that are not included in the EPC standard. This extensibility feature also makes the Oracle Database adaptable to the evolving future EPC standard.
This chapter describes the requirement of storing, retrieving, encoding and decoding various product codes, including EPC, in an Oracle Database and shows how the Identity Code Package solution meets all these requirements by providing data types, metadata tables, and PL/SQL packages for these purposes.
This topic describes these product codes:
The Electronic Product Code™ (EPC™) is an identification scheme for universally identifying physical objects using Radio Frequency Identification (RFID) tags and other means. The standardized EPC data consists of an EPC (or EPC Identifier) that uniquely identifies an individual object, and an optional Filter Value when judged to be necessary to enable effective and efficient reading of the EPC tags. In addition to this standardized data, certain classes of EPC tags allow user-defined data.
The EPC Identifier is a meta-coding scheme designed to support the needs of various industries by accommodating both existing coding schemes where possible and defining schemes where necessary. The various coding schemes are referred to as Domain Identifiers, to indicate that they provide object identification within certain domains such as a particular industry or group of industries. As such, EPC represents a family of coding schemes (or "namespaces") and a means to make them unique across all possible EPC-compliant tags.
The EPCGlobal EPC Data Standards Version 1.1 defines the abstract content of the Electronic Product Code, and its concrete realization in the form of RFID tags, Internet URIs, and other representations. In EPC Version 1.1, the specific coding schemes include a General Identifier (GID), a serialized version of the EAN.UCC Global Trade Item Number (GTIN®), the EAN.UCC Serial Shipping Container Code (SSCC®), the EAN.UCC Global Location Number (GLN®), the EAN.UCC Global Returnable Asset Identifier (GRAI®), and the EAN.UCC Global Individual Asset Identifier (GIAI®).
The EPC pure identity is the identity associated with a specific physical or logical entity, independent of any particular encoding vehicle such as an RF tag, bar code or database field. As such, a pure identity is an abstract name or number used to identify an entity. A pure identity consists of the information required to uniquely identify a specific entity, and no more.
EPC encoding is a pure identity with more information, such as filter value, rendered into a specific syntax (typically consisting of value fields of specific sizes). A given pure identity might have several possible encodings, such as a Barcode Encoding, various Tag Encodings, and various URI Encodings. Encodings may also incorporate additional data besides the identity (such as the Filter Value used in some encodings), in which case the encoding scheme specifies what additional data it can hold.
For example, the Serial Shipping Container Code (SSCC) format as defined by the EAN.UCC System is an example of a pure identity. An SSCC encoded into the EPC- SSCC 96-bit format is an example of an encoding.
EPC encoding on a tag is a string of bits, consisting of a tiered, variable length header followed by a series of numeric fields whose overall length, structure, and function are completely determined by the header value.
The EPC identity URI is a representation of a pure identity as a Uniform Resource Identifier (URI).
The EPC tag URI encoding represents a specific EPC tag bit-level encoding, for example, urn:epc:tag:sgtin-64:3.0652642.800031.400.
The EPC encoding procedure is used to generate an EPC tag bit-level encoding using various information.
A Global Trade Identification Number (GTIN) is used for the unique identification of trade items worldwide within the EAN.UCC system. The Serialized Global Trade Identification Number (SGTIN) is an identity type in EPC standard version1.1. It is based on the EAN.UCC GTIN code defined in the General EAN.UCC Specifications [GenSpec5.0]. A GTIN identifies a particular class of object, such as a particular kind of product or SKU. The combination of GTIN and a unique serial number is called a Serialized GTIN (SGTIN).
The Serial Shipping Container Code (SSCC) is defined by the General EAN.UCC Specifications [GenSpec5.0]. The unique identification of logistics units is achieved in the EAN.UCC system by the use of the SSCC. The SSCC is intended for assignment to individual objects.
The Global Location Number (GLN) is defined by the General EAN.UCC Specifications [GenSpec5.0]. A GLN can represent either a discrete, unique physical location such as a dock door or a warehouse slot, or an aggregate physical location such as an entire warehouse. In addition, a GLN can represent a logical entity such as an organization that performs a business function (for example, placing an order). The combination of GLN and a unique serial number is called a Serialized GLN (SGLN). However, until the EAN.UCC community determines the appropriate way to extend GLN, the serial number field is reserved and must not be used.
A returnable asset is a reusable package or transport equipment of a certain value. Global Returnable Asset Identifier is (GRAI) is defined by the General EAN.UCC Specifications [GenSpec5.0] for the unique identification of a returnable asset.
The Global Individual Asset Identifier (GIAI) is defined by the General EAN.UCC Specifications [GenSpec5.0]. Unlike the GTIN, the GIAI is intended for assignment to individual objects. Global Individual Asset Identifier (GIAI) is used to uniquely identify an entity that is part of the fixed inventory of a company. The GIAI identifies any fixed asset of an organization.
The RFID EPC network is used to identify, track and locate assets. Physical objects are identified by a unique RFID enabled EPC.
The Oracle Database Tag Data Translation Schema is closely related to the EPCglobal TDT schema, however it is not exact. The Oracle Database TDT is shown as follows:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="oracle.mgd.idcode"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tdt="oracle.mgd.idcode" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.0">
<xsd:simpleType name="InputFormatList">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="BINARY"/>
<xsd:enumeration value="STRING"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="LevelTypeList">
<xsd:restriction base="xsd:string">
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="SchemeNameList">
Z <xsd:restriction base="xsd:string">
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ModeList">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="EXTRACT"/>
<xsd:enumeration value="FORMAT"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="CompactionMethodList">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="32-bit"/>
<xsd:enumeration value="16-bit"/>
<xsd:enumeration value="8-bit"/>
<xsd:enumeration value="7-bit"/>
<xsd:enumeration value="6-bit"/>
<xsd:enumeration value="5-bit"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="PadDirectionList">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="LEFT"/>
<xsd:enumeration value="RIGHT"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="Field">
<xsd:attribute name="seq" type="xsd:integer" use="required"/>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="bitLength" type="xsd:integer"/>
<xsd:attribute name="characterSet" type="xsd:string" use="required"/>
<xsd:attribute name="compaction" type="tdt:CompactionMethodList"/>
<xsd:attribute name="compression" type="xsd:string"/>
<xsd:attribute name="padChar" type="xsd:string"/>
<xsd:attribute name="padDir" type="tdt:PadDirectionList"/>
<xsd:attribute name="decimalMinimum" type="xsd:long"/>
<xsd:attribute name="decimalMaximum" type="xsd:long"/>
<xsd:attribute name="length" type="xsd:integer"/>
</xsd:complexType>
<xsd:complexType name="Option">
<xsd:sequence>
<xsd:element name="field" type="tdt:Field" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="optionKey" type="xsd:string" use="required"/>
<xsd:attribute name="pattern" type="xsd:string"/>
<xsd:attribute name="grammar" type="xsd:string" use="required"/>
</xsd:complexType>
<xsd:complexType name="Rule">
<xsd:attribute name="type" type="tdt:ModeList" use="required"/>
<xsd:attribute name="inputFormat" type="tdt:InputFormatList" use="required"/>
<xsd:attribute name="seq" type="xsd:integer" use="required"/>
<xsd:attribute name="newFieldName" type="xsd:string" use="required"/>
<xsd:attribute name="characterSet" type="xsd:string" use="required"/>
<xsd:attribute name="padChar" type="xsd:string"/>
<xsd:attribute name="padDir" type="tdt:PadDirectionList"/>
<xsd:attribute name="decimalMinimum" type="xsd:long"/>
<xsd:attribute name="decimalMaximum" type="xsd:long"/>
<xsd:attribute name="length" type="xsd:string"/>
<xsd:attribute name="function" type="xsd:string" use="required"/>
<xsd:attribute name="tableURI" type="xsd:string"/>
<xsd:attribute name="tableParams" type="xsd:string"/>
<xsd:attribute name="tableXPath" type="xsd:string"/>
<xsd:attribute name="tableSQL" type="xsd:string"/>
</xsd:complexType>
<xsd:complexType name="Level">
<xsd:sequence>
<xsd:element name="option" type="tdt:Option" minOccurs="1"
maxOccurs="unbounded"/>
<xsd:element name="rule" type="tdt:Rule" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="type" type="tdt:LevelTypeList" use="required"/>
<xsd:attribute name="prefixMatch" type="xsd:string"/>
<xsd:attribute name="requiredParsingParameters" type="xsd:string"/>
<xsd:attribute name="requiredFormattingParameters" type="xsd:string"/>
</xsd:complexType>
<xsd:complexType name="Scheme">
<xsd:sequence>
<xsd:element name="level" type="tdt:Level" minOccurs="4" maxOccurs="5"/>
</xsd:sequence>
<xsd:attribute name="name" type="tdt:SchemeNameList" use="required"/>
<xsd:attribute name="optionKey" type="xsd:string" use="required"/>
</xsd:complexType>
<xsd:complexType name="TagDataTranslation">
<xsd:sequence>
<xsd:element name="scheme" type="tdt:Scheme" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="version" type="xsd:string" use="required"/>
<xsd:attribute name="date" type="xsd:dateTime" use="required"/>
</xsd:complexType>
<xsd:element name="TagDataTranslation" type="tdt:TagDataTranslation"/>
</xsd:schema>
~O`o |ӧO`_ ߿|ȏ`>?}/ &Lp ?} &$_ &L0a &4_>'|__>~/|˧o?/߿|˧_| / ?O`>/| &L8 ,h 2l| `>o@_(߿߿|_}_Ǐ_ (0 ?}O` ߿__
''|/||/|`>_ /߿}O` o`>?O` & O_ 0a &L0a
O`O`_O`Ǐ`O` A}/>}˗߿|/|˗ | _|_'p " O_ <0
:|1ĉ+Z>È#F1bĈcE~0 #F1bĈ#FxP ?1bĈa>1bh>È#FaD#F1"A}0bĈ@} |ӷ/ | /?}/_>#F'Ӈ>~1bĈq`O`/'0?~/߿|O`>~aĈD~0 #F1/_A}
__|_'p "Lp!Æ?} >|ÇO`?}O`>O ?~+_| '0Ç >|P!?} Ç >|p`_o`|O>O߾ '0Ç >|P!?} Ç >|p`>~˗O>~/_|˧O ?/ |O`>{Ç "=|Ç >|Ç >|Ç >|Ç >C=?} HO@
DPB
>QD-^LO ƃaĈ#F1bĈ"?}#F1bĈ#Ɗa< F1bĈ#F+O@
,? 4xaB 6tbD)VxQ!@,h`A$XA .dC%NXE5nG!E:ϟ~F 9rȑ# b|F 9rȑ# Ob|F 9rȑ##b|F 9rȑ#'a|F 9rȑ#+a|F 9rȑ#/Oa|F 9rȑ#3a|F 9rȑ#7`|F 9rȑ#;`|F 9rȑ#?O`|F 9rȑ#C_}#G 9rȑ#˷oȑ#G 9r~9rȑ#G / }O@
DPB
>QD-^ذ_}1cƌ3f̘1cƌ GP_>3f̘1cƌ3f̘_}1cƌ3f̘1cƌۇP_>3f̘1cƌ3fX_}
1cƌ3f̘1cƌP_>3f̘1cƌ3f_}1cƌ3f̘1cF탨/3f̘1cƌ3ZoD}e̘1cƌ3f̘b|(/cƌ3f̘1cƌgQ_3f̘1cƌ3J#3f̘1cƌ3f(2(2(2(2(
;;PKvC C PK |%A OEBPS/img/adfns108.gifR
GIF89a ???999@@@///```OOO000 ooo ___rrrరpppPPP***UUUֺ Ȼ:::GGG>>>...ݵ<<< ! , pH,ȤQk:ШtJZvzI& L.wynsx`8~Dzh3!1qwh7en7[fGI
GCG G 8FBB
9 C
cB[ʨEE
0ۆA?WP0ݱNޅG@ 8(D ήk ݄ 8X"0g)i'^/
@h@Er`*B0`NByZh֜xs D6CA'|5GRL 0 \S5Q d Б'i@*R dpaN@T 20x Cc-' 2UϜRAf( ,j눯I 7ƇNhx8
=]*`
1a Jv3> *Ӄ_ 9VG>FO=Q DB(RNEᆮ00rD P(*<:4H
㏝DLYc% J <2dRq$HN>G[HeVFeh> ) p)g U
E rnD yQx`F$@O\CDG >QrpS
e
Ag u-3 J
\+_2
(h Sp W@ adp00a,3 RSp p`CiPBaIUl0 vQk e0xqٓ N Fi3?N5Qh4iAh91@p q9Qj$I{ aZjhC & ?fp>*X
0v*6* `4 `pU B <w PI!m P`Z:q& ᭆ
P
P@@ @ ]PjR瘎؎.b=P0,P9C ,qǶ p
N i
i0NR@x:A? @.JPdA`
3W5G{SP Ӑ 4 m )
! B$@
ϋs;0ҭ9ڄvHxZ# ۚ` ZPh > R
@
^ G` 'p P
.P RP3 1xp> n*Z¸/P1"26
xp u+ Tп:
s .`)\+,ihk qpQ
0f.p
ա#Hܪ^P8z,xgBx+(K2` `[ѩ
m@.*Z ; T@:
R ?!Lep j*`Fx = )z# @*WvE 5xь@ր
1W
} hZ0 }0 P { ְ!:
0
Pq
b K$b
N@ǰ
d,0
smҋᗀyR` .%u?) yxJ( ,0MxxB@ 7:0p=x텿=k=&Q
\`PX
F6t@[F`R P@. /@[ v`tNZȑXpFM l` V P
;P ` C\ }@
z,pZ@ [p c B}xŝ >`.0 ʆ b` I@ro@p@ ] QPJq?
p+VVW V pl+ɒIı8@ =0>ؑ+ z@qPT ^swuz; 4ƀJ
\ ZEcne !t03E @ `p4 !
l5nx7 K@
PhP *
/0$ ̰ L $f`
b ~
(n ` 0 n D P$ m 0 >i ~˽6eZ
4 \`be^PU )
s
0,5p
w^x <B.0 Q
0. >c`
pV[' y@M3P`8p 9cK #,0#㔵 - 1 ߚ|1v)O
Z v3
0`
@: 40 ODU/ZJz0nYNJAO0m k`_@ pp И aA .d/
%NXE`ĨR v)@ -y'Y sp3=5Z YIǿ41vpNE\s?0 h8 h[q ,8w"G,h!M63̾4 Ĵ& JS+*Qx9?1FQs. 81& # A&(.Qv+>o+"Xmt"'!909 j
tU]Tݙ%>,?paƞ A1l$(\``da BG
a&mpCbNl!) BdS8>PqLIJ !m脚,*@ D1H4Q5 b86v('ɍCxsL#"T:sM☁ bsN< >#3'FހeD
@ ";3p7 `' FHXGbФ\ HtrI$'N^)2׃lV
:@K7 u";9Y*I 'bA JQcf~8gp / vc| CQ"bp.@ T0H_2dY
Y 781 a%5? 2d]}W<4bvY{6(
0 "D0>zP 6"kO*
^m$R tP_8 6 ㆗ A&: )g)p!.@o ;X}f3יg͟sЏ @D
*A
z $["#lA$_6$
]$(`Xgg ~B g
)d g&:) [#a qqc:dkMQ{E`b'A 0?6
@m(Y
>Ё!
b I bHB 2!T!!@
TD# IT"ڀQ@]QbdFqE A8 D(0hȆB\`X ǿ-#f_0F H>0|H <$)YI! D
IO~ғI ҋEH ?HȢ /$AFE H@ 4F
iRN6sZ"WsH&R T`ЁQZua?n9. 0IL 3 !0! XO 5OM{1 5P ,
rl5H b jQL|C@ ,D!<_J:. UH W`%~$` ,A
"JE
0 EH (1"ҡD |&N SӬݔriBPDNv |+*B4N@ `Fܠ F&d@
]l4yu5Ю7#]!QB} GP ԧtPMuS*Uwa%1FuDY/b: % зc۲ .
_1AZ"j W:B PQ DC ÂZlЀТ F
*cĂ +zC6#
P@-!:#۸byd ?@`d # !x4S*=SP |!p^'{'ZJa`0 9 %
a
t B` T a
?, "ؠ !f$ E(
(l Indexes are optional structures, associated with tables and clusters, which allow SQL queries to execute more quickly. Just as the index in this document helps you locate information faster than if there were no index, an Oracle Database index provides a faster access path to table data. You can use indexes without rewriting any queries. Your results are the same, but you see them more quickly. This chapter supplements this information: The explanation of indexes and index-organized tables in Oracle Database Concepts The information about managing indexes in Oracle Database Administrator's Guide The explanation of how indexes and clusters can enhance or degrade performance in Oracle Database Performance Tuning Guide Topics: Here is a summary of the guidelines for managing indexes. For details, see Oracle Database Administrator's Guide: Create indexes after inserting table data Index the correct tables and columns Order index columns for performance Limit the number of indexes for each table Drop indexes that are no longer needed Understand deferred segment creation Estimate index size and set storage parameters Specify the tablespace for each index Consider parallelizing index creation Consider creating indexes with Understand when to use unusable or invisible indexes Consider costs and benefits of coalescing or rebuilding indexes Consider cost before disabling or dropping constraints Oracle Database Administrator's Guide has this information about managing indexes: A domain index (also called an application domain index) is a customized index specific to an application that was implemented using a data cartridge (for example, a search engine or geographic information system). For information about domain indexes, see Oracle Database Concepts. See Also: A function-based index computes the value of an expression that involves one or more columns and stores it in the index. The index expression can be an arithmetic expression or an expression that contains a SQL function, PL/SQL function, package function, or C callout. Function-based indexes also support linguistic sorts based on collation keys, efficient linguistic collation of SQL statements, and case-insensitive sorts. A function-based index improves the performance of queries that use the index expression (especially if the expression is computationally intensive). However, the database must also evaluate the index expression to process statements that do not use it. The optimizer can use function-based indexes only for cost-based optimization, while it can use indexes on columns for both cost-based and rule-based optimization. Note: A function-based index cannot contain the value Oracle Database treats descending indexes as if they were function-based indexes (for more information, see Oracle Database SQL Language Reference). Topics: See Also: Oracle Database Concepts for additional conceptual information about function-based indexes Oracle Database Administrator's Guide for information about creating function-based indexes Oracle Database Globalization Support Guide for information about function-based linguistic indexes Oracle Database Concepts for more information about how the optimizer uses function-based indexes Oracle Database Performance Tuning Guide for information about using function-based indexes for performance A function-based index has these advantages: A function-based index increases the number of situations where the database can perform an index range scan (described in Oracle Database Concepts) instead of a full index scan (described in Oracle Database Concepts). An index range scan typically has a fast response time when the Oracle Database represents the index expression as a virtual column, on which the A function-based index precomputes and stores the value of an expression. Queries can get the value of the expression from the index instead of computing it. The more queries that need the value, and the more computationally intensive the index expression, the more the index improves application performance. (See Example 4-1.) You can create a function-based index on an object column or The index expression can be the invocation of a method that returns an object type. For more information, see Oracle Database Object-Relational Developer's Guide. (See Example 4-2 and the example in Oracle Database SQL Language Reference.) A function-based index lets you perform more powerful sorts. The index expression can invoke the SQL functions A function-based index has these disadvantages: The optimizer can use a function-based index only for cost-based optimization, not for rule-based optimization. The cost-based optimizer uses statistics stored in the dictionary. To gather statistics for a function-based index, invoke either The database does not use a function-based index until you analyze the index itself and the table on which it is defined. To analyze the index and the table on which the index is defined, invoke either The database does not use function-based indexes when doing You must ensure that any schema-level or package-level PL/SQL function that the index expression invokes is deterministic (that is, that the function always return the same result for the same input). You must declare the function as If you change the semantics of a If the index expression is a function invocation, then the function return type cannot be constrained. Because you cannot constrain the function return type with The index expression cannot invoke an aggregate function (described in Oracle Database SQL Language Reference). A bitmapped function-based index cannot be a descending index (see Oracle Database SQL Language Reference). The data type of the index expression cannot be That is, you cannot index an expression of unknown length. However, you can index a known-length substring of that expression. For example: See Also: Oracle Database SQL Language Reference for notes on function-based indexes Oracle Database SQL Language Reference for restrictions on function-based indexes Oracle Database PL/SQL Language Reference for information about the Example 4-1, "Function-Based Index for Precomputing Arithmetic Expression" Example 4-3, "Function-Based Index for Faster Case-Insensitive Searches" Example 4-4, "Function-Based Index for Language-Dependent Sorting" Note: Example 4-1 creates a table with columns Example 4-1 Function-Based Index for Precomputing Arithmetic Expression Create table on which to create index: Create index: This query can use an index range scan instead of a full index scan: In Example 4-2, assume that the object type Example 4-2 Function-Based Indexes on Object Column Create table with object column: Create deterministic function with parameter of type Create first function-based index: Use index expression in query: Result: Create second function-based (and composite) index: Use index expression and indexed column in query: Result: Example 4-3 creates an index that allows faster case-insensitive searches in the Example 4-3 Function-Based Index for Faster Case-Insensitive Searches Create index: Use index expression in query: Result: Example 4-4 creates a table with one column, Example 4-4 Function-Based Index for Language-Dependent Sorting Create table on which to create index: Create index: Select all table columns, ordered by This chapter explains how to develop PL/SQL web applications, which let you make your database available on the intranet. Topics: Typically, a web application written in PL/SQL is a set of stored subprograms that interact with web browsers through HTTP. A set of interlinked, dynamically generated HTML pages forms the user interface of a web application. The program flow of a PL/SQL web application is similar to that in a CGI PERL script. Developers often use CGI scripts to produce web pages dynamically, but such scripts are often not optimal for accessing the database. Delivering web content with PL/SQL stored subprograms provides the power and flexibility of database processing. For example, you can use data manipulation language (DML) statements, dynamic SQL statements, and cursors. You also eliminate the process overhead of forking a new CGI process to handle each HTTP request. Figure 9-1 illustrates the generic process for a PL/SQL web application. You can implement a web browser-based application entirely in PL/SQL with these Oracle Database components: The PL/SQL gateway enables a web browser to invoke a PL/SQL stored subprogram through an HTTP listener. The gateway is a platform on which PL/SQL users develop and deploy PL/SQL web applications. The Some advantages of using You can run it in a firewall environment in which the Oracle HTTP Server runs on a firewall-facing host while the database is hosted behind a firewall. You cannot use this configuration with the embedded gateway. The embedded gateway does not support You can use an embedded version of the PL/SQL gateway that runs in the XML DB HTTP Listener in the database. It provides the core features of Some advantages of using the embedded gateway over You can invoke PL/SQL web applications such as Application Express without installing Oracle HTTP Server, thereby simplifying installation, configuration, and administration of PL/SQL based web applications. You use the same configuration approach that is used to deliver content from Oracle XML DB in response to FTP and HTTP requests. This set of PL/SQL packages is a generic interface that enables you to use stored subprograms invoked by In response to a browser request, a PL/SQL subprogram updates or retrieves data from Oracle Database according to the user input. It then generates an HTTP response to the browser, typically in the form of a file download or HTML to be displayed. The PL/SQL Web Toolkit API enables stored subprograms to perform actions such as: Obtain information about an HTTP request Generate HTTP headers such as content-type and mime-type Set browser cookies Generate HTML pages Table 9-1 describes commonly used PL/SQL Web Toolkit packages. Table 9-1 Commonly Used Packages in the PL/SQL Web Toolkit Function versions of the subprograms in the Subprograms that generate HTML tags. For example, the procedure Subprograms that enable the PL/SQL gateway cache feature to improve performance of your PL/SQL web application. You can use this package to enable expires-based and validation-based caching with the PL/SQL gateway file system. Subprograms that send and retrieve HTTP cookies to and from a client web browser. Cookies are strings a browser uses to maintain state between HTTP calls. State can be maintained throughout a client session or longer if a cookie expiration date is included. The authorize function used by cookies. Subprograms that obtain the coordinates where a user clicked an image. Use this package when you have an image map whose destination links invoke a PL/SQL gateway. Subprograms that impose database optimistic locking strategies to prevent lost updates. Lost updates can otherwise occur if a user selects, and then attempts to update, a row whose values were changed in the meantime by another user. Subprograms that perform string matching and string manipulation with regular expressions. Subprograms used by the PL/SQL gateway for authenticating requests. Subprograms used by package These types of utility subprograms: Dynamic SQL utilities to produce pages with dynamically generated SQL code. HTML utilities to retrieve the values of CGI environment variables and perform URL redirects. Date utilities for correct date-handling. Date values are simple strings in HTML, but must be properly treated as an Oracle Database data type. Subprograms that download documents from a document repository that you define using the DAD configuration. See Also: As explained in detail in the Oracle HTTP Server mod_plsql User's Guide, See Also: Oracle HTTP Server mod_plsql User's Guide to learn how to configure and use Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server for information about the The embedded gateway functions very similar to the Topics: Figure 9-2 illustrates the process by which the embedded gateway handles client HTTP requests. Figure 9-2 Processing Client Requests with Embedded PL/SQL Gateway The explanation of the steps in Figure 9-2 is as follows: The Oracle XML DB HTTP Listener receives a request from a client browser to request to invoke a PL/SQL subprogram. The subprogram can either be written directly in PL/SQL or indirectly generated when a PL/SQL Server Page is uploaded to the database and compiled. The XML DB HTTP Listener routes the request to the embedded PL/SQL gateway as specified in its virtual-path mapping configuration. The embedded gateway uses the HTTP request information and the gateway configuration to determine which database account to use for authentication. The embedded gateway prepares the call parameters and invokes the PL/SQL subprogram in the application. The PL/SQL subprogram generates an HTML page out of relational data and the PL/SQL Web Toolkit accessed from the database. The application sends the page to the embedded gateway. The embedded gateway sends the page to the XML DB HTTP Listener. The XML DB HTTP Listener sends the page to the client browser. Unlike Configure general HTTP listener settings through the XML DB interface (for instructions, see Oracle XML DB Developer's Guide). Configure the HTTP listener either by using Oracle Enterprise Manager or by editing the The embedded gateway requires these components: XML DB HTTP Listener PL/SQL Web Toolkit The embedded PL/SQL gateway is installed as part of Oracle XML DB. If you are using a preconfigured database created during an installation or by the Database Configuration Assistant (DBCA), then Oracle XML DB is installed and configured. For information about manually adding Oracle XML DB to an existing database, see Oracle XML DB Developer's Guide. The PL/SQL Web Toolkit is part of the standard installation of the database, so no supplementary installation is necessary. You configure The configuration interface to the embedded gateway is the PL/SQL package Topics: As in The database account to use for authentication The subprogram to use for uploading and downloading documents In the embedded PL/SQL gateway, a DAD is represented as a servlet in the XML DB HTTP Listener configuration. Each DAD attribute maps to an XML element in the configuration file Use the Create a DAD with the Set DAD attributes with the All DAD attributes are optional. If you do not specify an attribute, it has its initial value. Table 9-2 lists the embedded PL/SQL gateway attributes and the corresponding Table 9-2 Mapping Between mod_plsql and Embedded PL/SQL Gateway DAD Attributes No String No Enumeration of On, Off No Enumeration of Basic, SingleSignOn, GlobalOwa, CustomOwa, PerPackageOwa No String Yes Unsigned integer Yes Unsigned integer Yes String No Unsigned integer No String No String No String No String No String No Enumeration of ApacheStyle, ModplsqlStyle, DebugStyle Yes String No Unsigned integer No Enumeration of InfoDebug No String No Unsigned integer No String No Enumeration of On, Off No String No String No String No String No Enumeration of StatelessWithResetPackageState, StatelessWithFastRestPackageState, StatelessWithPreservePackageState No Enumeration of Char, Raw No String The default values of the DAD attributes are sufficient for most users of the embedded gateway. Like the DAD attributes, the global configuration parameters are optional. Table 9-3 describes the Table 9-3 Mapping Between mod_plsql and Embedded PL/SQL Gateway Global Attributes No Unsigned integer No Unsigned integer See Also: Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server for detailed descriptions of the Oracle Database PL/SQL Packages and Types Reference to learn about the Oracle XML DB Developer's Guide for an account of the Because it uses the XML DB authentication schemes, the embedded gateway handles database authentication differently from Note: Use the Topics: Static authentication is for the To configure static authentication, follow these steps: Log on to the database as an XML DB administrator (that is, a user with the Create the DAD. For example, this procedure creates a DAD invoked For this step, you need the The DAD attribute Assign the DAD the privileges of the database user specified in the previous step. This authorization enables end users to invoke procedures and access document tables through the embedded PL/SQL gateway with the privileges of the authorized account. For example: Alternatively, you can log off as the user with Note: Unlike Note: Dynamic authentication is for the In dynamic authentication, a database user does not have to authorize the embedded gateway to use its privileges to access database objects. Instead, browser users must supply the database authentication information through the HTTP Basic Authentication scheme. The action of the embedded gateway depends on whether the To set up dynamic authentication, follow these steps: Log on to the database as a an XML DB administrator (that is, a user with the Create the DAD. For example, this procedure creates a DAD invoked Optionally, set the DAD attribute The attribute WARNING: Passwords sent through the HTTP Basic Authentication scheme are not encrypted. Configure the embedded gateway to use the HTTPS protocol to protect the passwords sent by the browser clients. Anonymous authentication is for the To set up anonymous authentication, follow these steps: Log on to the database as an XML DB administrator, that is, a user with the Create the DAD. For example, this procedure creates a DAD invoked Set the DAD attribute Both You need not authorize the embedded gateway to use If you know the name of a DAD, then the authentication mode for this DAD depends on these factors: Does the DAD exist? Is the Is the DAD authorized to use the privilege of the Is the Table 9-4 shows how the answers to the preceding questions determine the authentication mode. Table 9-4 Authentication Possibilities for a DAD Yes Yes Yes Static Yes Yes No Dynamic restricted Yes No Does not matter Dynamic Yes Yes (to Does not matter Anonymous No N/A For example, assume that you create a DAD named The Example 9-1 does this: Creates a DAD with static authentication for database user Creates a DAD with dynamic authentication that is not restricted to any user. Creates a DAD with dynamic authentication that is restricted to the Example 9-1 Creating and Configuring DADs The creation and authorization of a DAD are independent; therefore you can: Authorize a DAD that does not exist (it can be created later) Authorize a DAD for which you are not the user (however, the authorization does not take effect until the DAD Example 9-2 creates a DAD with static authentication for database user Instead of authorizing that DAD, the database user Although the user might have done this by mistake, no error occurs, because the nonexistent DAD might be created later. The database user No error occurs, but the authorization does not take effect until the DAD Example 9-2 Authorizing DADs to be Created or Changed Later Example 9-3 creates a PL/SQL procedure, Example 9-3 Determining the Authentication Mode for a DAD Assume that you have run the script in Example 9-1 to create and configure various DADs. The output is: The anonymous block in Example 9-4 reports the authentication modes of all registered DADs. It invokes the Example 9-4 Showing the Authentication Mode for All DADs If you have run the script in Example 9-1 to create and configure various DADs, the output of Example 9-4 is: The anonymous block in Example 9-5 reports DAD authorizations that are not in effect. A DAD authorization is not in effect in either of these situations: The user who authorizes the DAD is not the user specified by the The user authorizes a DAD that does not exist Example 9-5 Showing DAD Authorizations that Are Not in Effect If you have run the script in Example 9-2 to create and configure various DADs, the output of Example 9-5 (reformatted to fit on the page) is: When you are connected to the database as a user with system privileges, this script helps you examine the configuration of the embedded PL/SQL gateway: Example 9-6 shows the output of the Example 9-6 epgstat.sql Script Output for Example 9-1 Command to run script: Result: The basic steps for invoking PL/SQL subprograms through the embedded PL/SQL gateway are the same as for the The placeholder These topics documented in Oracle HTTP Server mod_plsql User's Guide apply equally to the embedded gateway: Transaction mode Supported data types Parameter-passing scheme File upload and download support Path-aliasing Common Gateway Interface (CGI) environment variables The embedded gateway shares the same protection mechanism with The Dynamic HTML caching System monitoring Authentication modes other than Basic For information about authentication modes, see Oracle HTTP Server mod_plsql User's Guide. This section illustrates how to write a simple application that queries the To write and run the program follow these steps: Log on to the database as a user with Log on to the database as an XML DB administrator, that is, a user with the To determine which users and roles were granted the Create the DAD. For example, this procedure creates a DAD invoked Set the DAD attribute The attribute Grant Log off as the XML DB administrator and log on to the database as the database user whose privileges must be used by the DAD (for example, Authorize the embedded PL/SQL gateway to invoke procedures and access document tables through the DAD. For example: Create a sample PL/SQL stored procedure invoked Ensure that the Oracle Net listener can accept HTTP requests. You can determine the status of the listener on Linux and UNIX by running this command at the system prompt: Output (reformatted from a single line to multiple lines from page size constraints): If you do not see the HTTP service started, then you can add these lines to your initialization parameter file (replacing Run the For example, if your host is The web browser returns an HTML page with a table that includes the first and last name of every employee in the Traditionally, PL/SQL web applications use function calls to generate each HTML tag for output. These functions are part of the PL/SQL Web Toolkit packages that come with Oracle Database. Example 9-7 shows how to generate a simple HTML page by calling the Example 9-7 Using HTP Functions to Generate HTML Tags An alternative to making function calls that correspond to each tag is to use the Example 9-8 Using HTP.PRINT to Generate HTML Tags Chapter 10, "Developing PL/SQL Server Pages (PSP)," describes an additional method for delivering using PL/SQL to generate HTML content. PL/SQL server pages enables you to build on your knowledge of HTML tags and avoid learning a new set of function calls. In an application written as a set of PL/SQL server pages, you can still use functions from the PL/SQL Web Toolkit to: Simplify the processing involved in displaying tables Store persistent data (cookies) Work with CGI protocol internals To be useful in a wide variety of situations, a web application must be interactive enough to allow user choices. To keep the attention of impatient web surfers, streamline the interaction so that users can specify these choices very simply, without excessive decision-making or data entry. The main methods of passing parameters to PL/SQL web applications are: Using HTML form tags. The user fills in a form on one web page, and all the data and choices are transmitted to a stored subprogram when the user clicks the Hard-coded in the URL. The user clicks on a link, and a set of predefined parameters are transmitted to a stored subprogram. Typically, you include separate links on your web page for all the choices that the user might want. Topics: List boxes and drop-down lists are implemented with the HTML tag Use a list box for a large number of choices or to allow multiple selections. List boxes are good for showing items in alphabetical order so that users can find an item quickly without reading all the choices. Use a drop-down list in these situations: There are a small number of choices Screen space is limited. Choices are in an unusual order. The drop-down captures the attention of first-time users and makes them read the items. If you keep the choices and order consistent, then users can memorize the motion of selecting an item from the drop-down list, allowing them to make selections quickly as they gain experience. Example 9-9 shows a simple drop-down list. Options pass either a null value (if none of the options in a group is checked), or the value specified on the option that is checked. To specify a default value for a set of options, you can include the Check boxes need special handling, because your stored subprogram might receive a null value, a single value, or multiple values: All the check boxes with the same If one check box in a group is checked, the stored subprogram receives a single If multiple check boxes in a group are checked, the stored subprogram receives a parameter with the PL/SQL type Entry fields require the most validation, because a user might enter data in the wrong format, out of range, and so on. If possible, validate the data on the client side using a client-side JavaScript function, and format it correctly for the user or prompt them to enter it again. For example: You might prevent the user from entering alphabetic characters in a numeric entry field, or from entering characters after reaching a length limit. You might silently remove spaces and dashes from a credit card number if the stored subprogram expects the value in that format. You might inform the user immediately when they type a number that is too large, so that they can retype it. Because you cannot always rely on such validation to succeed, code the stored subprograms to deal with these cases anyway. Rather than forcing the user to use the For sensitive information such as passwords, a special form of the entry field, The procedure in Example 9-10 accepts two strings as input. The first time the procedure is invoked, the user sees a simple form prompting for the input values. When the user submits the information, the same procedure is invoked again to check if the input is correct. If the input is OK, the procedure processes it. If not, the procedure prompts for input, filling in the original values for the user. Example 9-10 Passing Entry-Field Parameters from an HTML Form One technique for passing information through a sequence of stored subprograms, without requiring the user to specify the same choices each time, is to include hidden parameters in the form that invokes a stored subprogram. The first stored subprogram places information, such as a user name, into the HTML form that it generates. The value of the hidden parameter is passed to the next stored subprogram, as if the user had entered it through a option or entry field. Other techniques for passing information from one stored subprogram to another include: Sending a "cookie" containing the persistent information to the browser. The browser then sends this same information back to the server when accessing other web pages from the same site. Cookies are set and retrieved through the HTTP headers that are transferred between the browser and the web server before the HTML text of each web page. Storing the information in the database itself, where later stored subprograms can retrieve it. This technique involves some extra overhead on the database server, and you must still find a way to keep track of each user as multiple users access the server at the same time. You can use an HTML form to choose a file on a client system, and transfer it to the server. A stored subprogram can insert the file into the database as a The PL/SQL Web Toolkit and the PL/SQL gateway have the notion of a "document table" that holds uploaded files. See Also: By default, an HTML form must have a You can have multiple forms on the same page, each with its own form elements and Using JavaScript or other scripting languages, you can eliminate the Submit button and have the form submitted in response to some other action, such as selecting from a drop-down list. This technique is best when the user only makes a single selection, and the confirmation step of the When an HTML form is submitted, your stored subprogram receives null parameters for any form elements that are not filled in. For example, null parameters can result from an empty entry field, a set of check boxes, options, or list items with none checked, or a Regardless of any validation you do on the client side, always code stored subprograms to handle the possibility that some parameters are null: Specify an initial value in all parameter declarations, to prevent an exception when the stored subprogram is invoked with a missing form parameter. You can set the initial value to zero for numeric values (when that makes sense), and to Before using an input parameter value that has the initial value Make the subprogram generate sensible results even when not all input parameters are specified. You might leave some sections out of a report, or display a text string or image in a report to indicate where parameters were not specified. Provide a way to fill in the missing values and run the stored subprogram again, directly from the results page. For example, include a link that invokes the same stored subprogram with an additional parameter, or display the original form with its values filled in as part of the output. Web applications are particularly concerned with the idea of state, the set of data that is current at a particular moment in time. It is easy to lose state information when switching from one web page to another, which might result in asking the user to make the same choices over and over. You can pass state information between dynamic web pages using HTML forms. The information is passed as a set of name-value pairs, which are turned into stored subprogram parameters for you. If the user has to make multiple selections, or one selection from many choices, or it is important to avoid an accidental selection, use an HTML form. After the user makes and reviews all the choices, they confirm the choices with the If the user is only considering one or two choices, or the decision points are scattered throughout the web page, you can save the user from hunting around for the An alternative way to main state information is to use Oracle Application Server and its See Also: Oracle provides packages that allow PL/SQL subprograms to perform these network operations: Internet Protocol version 6 (IPv6) Support As of Oracle Database 11g Release 2, PL/SQL network utility packages support IPv6 addresses. The package interfaces have not changed: Any interface parameter that expects a network host accepts an IPv6 address in string form, and any interface that returns an IP address can return an IPv6 address. However, applications that use network addresses might need small changes, and recompilation, to accommodate IPv6 addresses. An IPv6 address has 128 bits, while an IPv4 address has only 32 bits. In a URL, an IPv6 address must be enclosed in brackets. For example: See Also: Oracle Database Net Services Administrator's Guide for detailed information about IPv6 support in Oracle Database Oracle Database PL/SQL Packages and Types Reference for information about IPv6 support in specific PL/SQL network utility packages Using the Example 9-11 Sending Email from PL/SQL See Also: Using the See Also: Using the See Also: Using the Retrieve the contents of an HTTP URL The contents are usually in the form of HTML-tagged text, but might be any kind of file that can be downloaded from a web server (for example, plain text or a JPEG image). Control HTTP session details (such as headers, cookies, redirects, proxy servers, IDs and passwords for protected sites, and CGI parameters) Speed up multiple accesses to the same web site, using HTTP 1.1 persistent connections A PL/SQL subprogram can construct and interpret URLs for use with the The PL/SQL procedure in Example 9-12 uses the Example 9-12 Retrieving HTTP URL Contents from PL/SQL This block shows examples of calls to the procedure in Example 9-12, but the URLs are for nonexistent pages. Substitute URLs from your own web server. See Also: Oracle Database PL/SQL Packages and Types Reference for detailed information about the Oracle Database PL/SQL Packages and Types Reference for detailed information about Using packages supplied by Oracle, and the Documentation for these packages is not part of the database documentation library. The location of the documentation depends on your application server. To get started with these packages, look at their subprogram names and parameters using the SQL*Plus This chapter explains what application developers must know about how Oracle Database processes SQL statements. Before reading this chapter, read the basic information about SQL processing in Oracle Database Concepts. Topics: This topic explains what happens during each stage of processing the execution of a SQL statement, using a DML statement as an example. Assume that you are using a Pro*C program to increase the salary for all employees in a department. The program has connected to Oracle Database and you are connected to the HR schema, which owns the The program provides a value for the bind variable placeholder Stages of SQL Statement Processing Open or create a cursor. A program interface call opens or creates a cursor, in expectation of a SQL statement. Most applications create the cursor implicitly (automatically). Precompiler programs can create the cursor either implicitly or explicitly. Parse the statement. The user process passes the SQL statement to Oracle Database, which loads a parsed representation of the statement into the shared SQL area. Oracle Database can catch many errors during parsing. Determine if the statement is a query. If the statement is a query, describe its results. Note: Oracle Database determines the characteristics (data types, lengths, and names) of the result. If the statement is a query, define its output. You specify the location, size, and data type of variables defined to receive each fetched value. These variables are called define variables. Oracle Database performs data type conversion if necessary. Bind any variables. Oracle Database has determined the meaning of the SQL statement but does not have enough information to run it. Oracle Database needs values for any bind variable placeholders in the statement. In the example, Oracle Database needs a value for A program must specify the location (memory address) of the value. End users of applications may be unaware that they are specifying values for bind variable placeholders, because the Oracle Database utility can prompt them for the values. Because the program specifies the location of the value (that is, binds by reference), it need not rebind the variable before rerunning the statement, even if the value changes. Each time Oracle Database runs the statement, it gets the value of the variable from its address. You must also specify a data type and length for each value (unless they are implied or defaulted) if Oracle Database must perform data type conversion. See Also: (Optional) Parallelize the statement. Oracle Database can parallelize queries and some data definition language (DDL) operations (for example, index creation, creating a table with a subquery, and operations on partitions). Parallelization causes multiple server processes to perform the work of the SQL statement so that it can complete faster. Run the statement. Oracle Database runs the statement. If the statement is a query or an For some statements, you can specify multiple executions to be performed. This is called array processing. Given n number of executions, the bind and define locations are assumed to be the beginning of an array of size n. If the statement is a query, fetch its rows. Oracle Database selects rows and, if the query has an Close the cursor. Oracle Database closes the cursor. Shared SQL Areas Oracle Database automatically detects when applications send similar SQL statements to the database. The SQL area used to process the first occurrence of the statement is shared—that is, used for processing subsequent occurrences of that same statement. Therefore, only one shared SQL area exists for a unique statement. Because shared SQL areas are shared memory areas, any Oracle Database process can use a shared SQL area. The sharing of SQL areas reduces memory use on the database server, thereby increasing system throughput. In determining whether statements are similar or identical, Oracle Database compares both SQL statements issued directly by users and applications and recursive SQL statements issued internally by DDL statements. Topics: Typically, deciding how to group operations in transactions is the concern of application designers who use programming interfaces to Oracle Database. When deciding how to group transactions: Define transactions such that work is accomplished in logical units and data remains consistent. Ensure that data in all referenced tables is in a consistent state before the transaction begins and after it ends. Ensure that each transaction consists only of the SQL statements or PL/SQL blocks that comprise one consistent change to the data. For example, suppose that you write a web application that enables users to transfer funds between accounts. The transaction must include the debit to one account, executed by one SQL statement, and the credit to another account, executed by another SQL statement. Both statements must fail or succeed as a unit of work; one statement must not be committed without the other. Do not include unrelated actions, such as a deposit to one account, in the transaction. As an application developer, you must try to improve performance. Consider using these performance enhancement techniques when designing and writing your application: For each transaction: If you can use a single SQL statement, then do so. If you cannot use a single SQL statement but you can use PL/SQL, then use as little PL/SQL as possible. For information about PL/SQL, see Part II, "PL/SQL for Application Developers". If you cannot use PL/SQL (because it cannot do what you must do; for example, send email), then use Java. If you cannot use Java (for example, if it is too slow) or you have existing third-generation language (3GL) code, then use an external C subprogram. For information about using Java and C in your application, see Chapter 14, "Developing Applications with Multiple Programming Languages." Establish standards for writing SQL statements so that you can take advantage of shared SQL areas. Oracle Database recognizes identical SQL statements and enables them to share memory areas, reducing memory usage on the database server and increasing system throughput. Collect statistics that Oracle Database can use to implement a cost-based approach to SQL statement optimization, and use additional hints to the optimizer as needed. To collect most statistics, use the To collect statistics unrelated to the cost-based optimizer (such as information about free list blocks), use the SQL statement For more information about hints, see Oracle Database SQL Language Reference. Before beginning a transaction, invoke Increase user productivity and query efficiency by including user-written PL/SQL functions in SQL expressions. For details, see "Invoking Stored PL/SQL Functions from SQL Statements". To commit a transaction, use the The When a transaction updates Oracle Database, it generates a corresponding redo entry. Oracle Database buffers the redo entry to the redo log until the transaction completes. When the transaction commits, the log writer process (LGWR) writes redo records to disk for the buffered redo entries of all changes in the transaction. By default, Oracle Database writes the redo entries to disk before the call returns to the client. This action causes a latency in the commit, because the application must wait for the redo entries to be persistent on disk. Oracle Database lets you change the handling of commit redo to fit the needs of your application. If your application requires very high transaction throughput and you are willing to trade commit durability for lower commit latency, then you can change the default Table 1-1 describes the Caution: Table 1-1 COMMIT Statement Options To change the Note: If your application uses Oracle Call Interface (OCI), then you can modify redo action by setting these flags in the Caution: See Also: The specification of the The database host fails, which causes the database to lose redo entries that were buffered but not yet written to the online redo logs. A file I/O problem prevents LGWR from writing buffered redo entries to disk. If the redo logs are not multiplexed, then the commit is lost. To roll back an entire transaction, or to roll back part of a transaction to a savepoint, use the The To roll back to a savepoint defined in the current transaction, use the To define a savepoint in a transaction, use the Creating a savepoint with the same identifier as an earlier savepoint deletes the earlier savepoint. After creating a savepoint, you can roll back to it. An active savepoint is one that was created after the last Table 1-2 shows a series of SQL statements that illustrates the use of Table 1-2 Use of COMMIT, SAVEPOINT, and ROLLBACK First savepoint of this transaction First DML statement of this transaction Second savepoint of this transaction Second DML statement of this transaction Third savepoint of this transaction Third DML statement of this transaction ORA-01086 New DML statement in this transaction Commits all actions performed by the first DML statement (the All other statements (the second and the third statements) of the transaction were rolled back before the By default, Oracle Database guarantees statement-level read consistency, but not transaction-level read consistency. With statement-level read consistency, queries in a statement produce consistent data for the duration of the statement, not reflecting changes by other statements. With transaction-level read consistency (repeatable reads), queries in the transaction produce consistent data for the duration of the transaction, not reflecting changes by other transactions. To ensure transaction-level read consistency for a transaction that does not include DML statements, specify that the transaction is read-only. The queries in a read-only transaction see only changes committed before the transaction began, so query results are consistent for the duration of the transaction. A read-only transaction provides transaction-level read consistency without acquiring additional data locks. Therefore, while the read-only transaction is querying data, other transactions can query and update the same data. A read-only transaction begins with this statement: Only DDL statements can precede the See Also: Long-running queries sometimes fail because undo information required for consistent read (CR) operations is no longer available. This situation occurs when active transactions overwrite committed undo blocks. Automatic undo management lets your database administrator (DBA) explicitly control how long the database retains undo information, using the parameter See Also: PL/SQL implicitly declares a cursor for all SQL data manipulation statements, including queries that return only one row. For queries that return multiple rows, you can explicitly declare a cursor to process the rows individually. You can think of a cursor as a name for a specific private SQL area. A PL/SQL cursor variable lets you retrieve multiple rows from a stored subprogram. You can pass cursor variables as parameters in your 3GL application. For more information about cursor variables, see Oracle Database PL/SQL Language Reference. Most Oracle Database users rely on the automatic cursor handling of the database utilities, but programmatic interfaces offer application designers more control over cursors. In application development, a cursor is a named resource available to a program, which can be specifically used for parsing SQL statements embedded within the application. Topics: The number of cursors that a session can have open simultaneously is determined by: The amount of memory available to the session The value of the initialization parameter Explicitly creating cursors for precompiler programs has advantages in tuning those applications. For example, increasing the number of cursors can reduce the frequency of parsing and improve performance. If you know how many cursors might be required at a given time, you can open that many cursors simultaneously. After each stage of execution, the cursor retains enough information about the SQL statement to reexecute the statement without starting over, if no other SQL statement was associated with that cursor. The statement can be reexecuted without including the parse stage. By opening several cursors, the parsed representation of several SQL statements can be saved. Repeated execution of the same SQL statements can thus begin at the describe, define, bind, or run step, saving the repeated cost of opening cursors and parsing. To understand the performance characteristics of a cursor, the DBA can use the Execution of a cursor puts the results of the query into a set of rows called the result set. A scrollable cursor is one whose result rows need not be fetched in forward sequential order. For a scrollable cursor, interfaces exist to fetch previously fetched rows, to fetch the nth row in the result set, and to fetch the nth row from the current position in the result set. See Also: Closing a cursor makes its information inaccessible and deallocates the memory that it uses. After a cursor opens, it does not close until the user program terminates its connection to the server. An OCI program or precompiler application that follows good programming practice explicitly closes open cursors during program execution. If the program terminates without closing an open cursor, then that cursor closes implicitly. Canceling a cursor frees resources from the current fetch.The information in the associated private area is lost but the cursor remains open, parsed, and associated with its bind variables. Note: See Also: Oracle Database has default locking mechanisms that ensure data concurrency, data integrity, and statement-level read consistency. However, you can override these mechanisms by locking tables explicitly. Locking tables explicitly is useful in situations such as these: A transaction in your application needs exclusive access to a resource, so that the transaction does not have to wait for other transactions to complete. Your application needs transaction-level read consistency (repeatable reads). For other ways to ensure transaction-level read consistency, see "Ensuring Repeatable Reads with Read-Only Transactions") and "Using Serializable Transactions for Concurrency Control". To override default locking at the transaction level, use any of these SQL statements: Locks acquired by these statements are released after the transaction is committed or rolled back. See Also: The initialization parameter Caution: Topics: No special privileges are required to acquire any type of table lock on a table in your own schema. To acquire a table lock on a table in another schema, you must have either the A transaction explicitly acquires the specified table locks when a You can specify several tables or views to lock in the same mode; however, only a single lock mode can be specified for each Note: In the If you do not want to wait, specify either You acquire the table lock only if it is immediately available; otherwise, an error notifies you that the lock is not available now. To wait up to n seconds to acquire the table lock, specify If the table lock is still unavailable after n seconds, an error notifies you that the lock is not available now. To wait indefinitely to acquire the lock, specify neither The database waits indefinitely until the table is available, locks it, and returns control to you. When the database is running DDL statements concurrently with DML statements, a timeout or deadlock can sometimes result. The database detects such timeouts and deadlocks and returns an error. Topics: Your transaction must prevent another transaction from acquiring an intervening share, share row, or exclusive table lock for a table before your transaction can update that table. If another transaction acquires an intervening share, share row, or exclusive table lock, no other transactions can update the table until the locking transaction commits or rolls back. Your transaction must prevent a table from being altered or dropped before your transaction can modify that table. Your transaction only queries the table, and requires a consistent set of the table data for the duration of the transaction. You can hold up other transactions that try to update the locked table, until all transactions that hold Other transactions might acquire concurrent Caution: Scenario: Tables Solution: Lock the Example 1-1 LOCK TABLE with SHARE MODE You might use a Your transaction requires both transaction-level read consistency for the specified table and the ability to update the locked table. You do not care if other transactions acquire explicit row locks (using You only want a single transaction to have this action. You might use an Your transaction requires immediate update access to the locked table. When your transaction holds an exclusive table lock, other transactions cannot lock specific rows in the locked table. Your transaction also ensures transaction-level read consistency for the locked table until the transaction is committed or rolled back. You are not concerned about low levels of data concurrency, making transactions that request exclusive table locks wait in line to update the table sequentially. If you let Oracle Database control table locking, your application needs less programming logic, but also has less control than if you manage the table locks yourself. Issuing the statement See Also: Oracle Database SQL Language Reference for information about the Oracle Database SQL Language Reference for information about the Change the settings for these parameters only when an instance is shut down. If multiple instances are accessing a single database, then all instances must use the same setting for these parameters. You can override default locking with a You can use a If a Each row in the return set of a Note: This can cause a deadlock between sessions querying the table concurrently with DML statements when rows are locked in a nonsequential order. To prevent such deadlocks, design your application so that concurrent DML statements on the table do not affect the return set of the query. If this is not feasible, you might want to serialize queries in your application. By default, the Table 1-3 shows how Oracle Database maintains data concurrency, integrity, and consistency when the Note: Table 1-3 Examples of Concurrency Under Explicit Locking 1 2 (Exclusive DDL lock not possible because Transaction 1 has table locked.) 3 4 (Waits because Transaction 2 locked same rows.) 5 6 (Releases row locks.) 7 8 9 10 11 12 13 14 15 (Waits because Transaction 1 locked same rows.) 16 17 (Conflicting locks were released.) 18 19 20 21 22 23 24 (Waits because Transaction 1 has conflicting table lock.) 25 26 (Conflicting table lock released.) 27 28 29 30 31 32 33 34 35 (Waits because Transaction 1 has conflicting table lock.) (Waits because Transaction 2 locked same rows.) 36 (Deadlock.) 37 38 39 40 41 42 43 44 45 46 (Waits because Transaction 1 has conflicting table lock.) 47 48 49 (Transaction 1 released conflicting lock.) 50 51 52 (Transaction 1 does not see uncommitted data.) 53 54 (Same result even after Transaction 2 commits.) 55 56 (Sees committed data.) 57 Your applications can use Oracle Lock Management services (user locks) by invoking subprograms the See Also: Topics: User locks can help: Provide exclusive access to a device, such as a terminal Provide application-level enforcement of read locks Detect when a lock is released and clean up after the application Synchronize applications and enforce sequential processing Example 1-2 shows how the Pro*COBOL precompiler uses locks to ensure that there are no conflicts when multiple people must access a single device. Example 1-2 How the Pro*COBOL Precompiler Uses Locks Table 1-4 describes the Oracle Database facilities that display locking information for ongoing transactions within an instance. Table 1-4 Ways to Display Locking Information Oracle Enterprise Manager Database Control The Database Locks page shows user locks, all database locks, or locks that are blocking other users or applications. For more information, see Oracle Database 2 Day + Real Application Clusters Guide. Performance Monitoring Data Dictionary Views The By default, Oracle Database permits concurrently running transactions to modify, add, or delete rows in the same table, and in the same data block. When transaction A changes a table, the changes are invisible to concurrently running transactions until transaction A commits them. If transaction A tries to update or delete a row that transaction B has locked (by issuing a DML or However, some rare applications require serializable transactions. Serializable transactions run concurrently in serialized mode. In serialized mode, concurrent transactions can make only the database changes that they could make if they were running serially (that is, one at a time). If a serialized transaction tries to change data that another transaction changed after the serialized transaction began, then error ORA-08177 occurs. When a serializable transaction fails with ORA-08177, the application can take any of these actions: Commit the work executed to that point. Run additional, different, statements, perhaps after rolling back to a prior savepoint in the transaction. Roll back the transaction and then rerun it. The transaction gets a transaction snapshot and the operation is likely to succeed. Tip: Note: Topics: The ANSI/ISO SQL standard defines three kinds of transaction interaction: The kinds of interactions that a transaction can have is determined by its isolation level. The ANSI/ISO SQL standard defines four transaction isolation levels. Table 1-5 shows what kind of interactions are possible at each isolation level. Table 1-5 ANSI/ISO SQL Isolation Levels and Possible Transaction Interactions Possible Possible Possible Not possible Possible Possible Not possible Not possible Possible Not possible Not possible Not possible Table 1-6 shows which ANSI/ISO SQL transaction isolation levels Oracle Database provides. Table 1-6 ANSI/ISO SQL Isolation Levels Provided by Oracle Database No. Oracle Database never permits "dirty reads." Some other database products use this undesirable technique to improve thoughput, but it is not required for high throughput with Oracle Database. Yes, by default. In fact, because an Oracle Database query sees only data that was committed at the beginning of the query (the snapshot time), Oracle Database offers more consistency than the ANSI/ISO SQL standard for Yes, if you set the transaction isolation level to Yes, if you set the transaction isolation level to Figure 1-1 shows how an arbitrary transaction (that is, one that is either Figure 1-1 Interaction Between Serializable Transaction and Another Transaction To set the transaction isolation level for every transaction in your session, use the To set the transaction isolation level for a specific transaction, use the Note: Because Oracle Database does not use read locks, even in In Figure 1-2, transactions A and B (which are either The query by transaction A does not prevent transaction B from deleting the parent row, and the query by transaction B does not prevent transaction A from inserting child rows. Therefore, this can happen: Transaction A queries the parent table and finds the specified parent row. Transaction B queries the child table and finds no child rows for the specified parent row. Having found the specified parent row, transaction A inserts the corresponding child rows into the child table. Having found no child rows for the specified parent row, transaction B deletes the specified parent row from the parent table. Now the child rows that transaction A inserted in step 3 have no parent row. The preceding result can occur even if both A and B are Ensuring that data queried by one transaction is not concurrently changed or deleted by another requires more transaction isolation than the ANSI/ISO SQL standard Transaction A can use a For information about the Transaction B can prevent transaction A from finding the parent row (thereby preventing A from inserting the child rows) by reversing the order of its processing steps. That is, transaction B can: Delete the parent row. Query the child table. If the deleted parent row has child rows in the child table, then roll back the deletion of the parent row. Alternatively, you can enforce referential integrity with a trigger. Instead of having transaction A query the parent table, define on the child table a row-level Queries the parent table with a Rejects the insertion of the child rows if the parent row does not exist. See Also: A trigger runs SQL statements in the context of the triggering statement (that is, the triggering and triggered statements see the database in the same state). Therefore, if a Oracle Database provides two transaction isolation levels, Topics: An operation (query or transaction) is transaction set consistent if all of its read operations return data written by the same set of committed transactions. When an operation is not transaction set consistent, some of its read operations reflect the changes of one set of transactions and others reflect the changes of other sets of transactions; that is, the operation sees the database in a state that reflects no single set of committed transactions. Topics: Oracle Database transactions with Oracle Database transactions with In other database systems, a single query with In read-locking systems, at the cost of preventing concurrent updates, the The choice of transaction isolation level depends on performance and consistency needs and application coding requirements. There is a trade-off between concurrency (transaction throughput) and consistency. Consider the application and workload when choosing isolation levels for its transactions. Different transactions can have different isolation levels. For environments with many concurrent users rapidly submitting transactions, consider expected transaction arrival rate, response time demands, and required degree of consistency. As explained in "Serializable Transactions and Referential Integrity" reads do not block writes in either Table 1-7 summarizes the similarities and differences between Table 1-7 Comparison of READ COMMITTED and SERIALIZABLE Transactions Dirty write Not Possible Not Possible Dirty read Not Possible Not Possible Unrepeatable read Possible Not Possible Phantom read Possible Not Possible Compliant with ANSI/ISO SQL 92 Yes Yes Read snapshot time Statement Transaction Transaction set consistency Statement level Transaction level Row-level locking Yes Yes Readers block writers No No Writers block readers No No Different-row writers block writers No No Same-row writers block writers Yes Yes Waits for blocking transaction Yes Yes Subject to "cannot serialize access" error No Yes Error after blocking transaction terminates No No Error after blocking transaction commits No Yes An autonomous transaction (AT) is an independent transaction started by another transaction, the main transaction (MT). An autonomous transaction lets you suspend the main transaction, do SQL operations, commit or roll back those operations, and then resume the main transaction. For example, in a stock purchase transaction, you might want to commit customer information regardless of whether the purchase succeeds. Or, you might want to log error messages to a debug table even if the transaction rolls back. Autonomous transactions enable you to do such tasks. An autonomous transaction runs within an autonomous scope; that is, within the scope of an autonomous routine—a routine that you mark with the Figure 1-3 shows how control flows from the main transaction (MT) to an autonomous transaction (AT) and back again. As you can see, the autonomous transaction can commit multiple transactions (AT1 and AT2) before control returns to the main transaction. When you enter the executable section of an autonomous transaction, the main transaction suspends. When you exit the transaction, the main transaction resumes. More characteristics of autonomous transactions: The changes an autonomous transaction effects do not depend on the state or the eventual disposition of the main transaction. For example: An autonomous transaction does not see changes made by the main transaction. When an autonomous transaction commits or rolls back, it does not affect the outcome of the main transaction. The changes an autonomous transaction effects are visible to other transactions as soon as that autonomous transaction commits. Therefore, users can access the updated information without having to wait for the main transaction to commit. Autonomous transactions can start other autonomous transactions. Figure 1-4 shows some possible sequences that autonomous transactions can follow. Figure 1-4 Possible Sequences of Autonomous Transactions Topics: See Also: As these examples show, there are four possible outcomes when you use autonomous and main transactions (see Table 1-8). There is no dependency between the outcome of an autonomous transaction and that of a main transaction. Table 1-8 Possible Transaction Outcomes Commits Commits Commits Rolls back Rolls back Commits Rolls back Rolls back Figure 1-5 shows an example of a customer ordering a product. The customer information (such as name, address, phone) is committed to a customer information table—even though the sale does not go through. In this example, a customer tries to withdraw money from a bank account. In the process, a main transaction invokes one of two autonomous transaction scopes (AT Scope 1 or AT Scope 2). The possible scenarios for this transaction are: There are sufficient funds to cover the withdrawal, so the bank releases the funds (see Figure 1-6). Figure 1-6 Bank Withdrawal—Sufficient Funds There are insufficient funds to cover the withdrawal, but the customer has overdraft protection, so the bank releases the funds (see Figure 1-7). Figure 1-7 Bank Withdrawal—Insufficient Funds with Overdraft Protection There are insufficient funds to cover the withdrawal and the customer does not have overdraft protection, so the bank withholds the requested funds (see Figure 1-8). Figure 1-8 Bank Withdrawal—Insufficient Funds Without Overdraft Protection To define an autonomous transaction, use In Example 1-3, the function Example 1-3 Marking a Package Subprogram as Autonomous See Also: When a long-running transaction is interrupted by a storage allocation error, the application can suspend the statement that encountered the problem, correct the problem, and then resume executing the statement. This capability, called resumable storage allocation, avoids time-consuming rollbacks. It also makes it unnecessary to split the operation into smaller pieces and write code to track its progress. See Also: Topics: Queries, DML statements, and some DDL statements have resumable storage allocation after these kinds of errors: Out-of-space errors, such as ORA-01653. Space-limit errors, such as ORA-01628. Space-quota errors, such as ORA-01536. Resumable storage allocation is possible whether the operation is performed directly by a SQL statement or within SQL*Loader, a stored subprogram, an anonymous PL/SQL block, or an OCI call such as In dictionary-managed tablespaces, you cannot resume an index- or table-creating operation that encounters the limit for rollback segments or the maximum number of extents. You must use locally managed tablespaces and automatic undo management in combination with resumable storage allocation. When a statement in an application is suspended because of a storage allocation error, the application does not receive an error code. Therefore, either the application must use an After the problem is corrected (usually by the DBA), the suspended statement automatically resumes execution. If the timeout period expires before the problem is corrected, then the statement raises a Topics: In the application, an To reduce the chance of out-of-space errors within the trigger itself, declare the trigger as an autonomous transaction. As an autonomous transaction, the trigger uses a rollback segment in the For general information about triggers, see Oracle Database PL/SQL Language Reference. The trigger in Example 1-4 handles storage errors within the database. For some kinds of errors, the trigger terminates the statement and alerts the DBA, using e-mail. For other errors, which might be temporary, the trigger specifies that the statement waits for eight hours before resuming, expecting the storage problem to be fixed by then. To run this example, you must connect to the database as Example 1-4 AFTER SUSPEND Trigger Handles Suspended Storage Allocation If the application does not use an The DBA can get additional information from the dynamic performance view This graphic shows the MGD_ID base code object as the uppermost box, the RFID code categories beneath it (labeled as boxes EPC, NASA, and others), then beneath these code category boxes, the respective scheme boxes. So beneath the EPC category box are the scheme boxes labeled SGTIN-64, SGTIN-96, and GID-96 and beneath the NASA category box are the scheme boxes labeled NASA-T1 and NASA-T2. Each level of boxes in the hierarchy is connected with downward pointing arrows to indicate their relationship. MTx generates a transaction ID. Tx1.1 inserts the transaction ID into the audit table and commits. MTx validates the balance on the account. Tx2.1 updates the audit table using the transaction ID generated earlier, then commits. MTx releases the funds. MT Scope ends. This figure shows 5 boxes with 6 lines connecting them: An arrow from a Publisher (Agent) box to a Topic (Subject Channel) box A "receive notification/message" arrow from the Topic to a Subscriber (Agent) box A "register" arrow from the Subscriber to the Topic A "subscribe" arrow from the Subscriber to the Topic A line between the Topic box and a Subscriptions box A line between the Topic box and a Rules box This figure shows an exception and an associated exception handler. A trigger uses a conditional statement that checks for an error condition and raises an application error. The user-defined error code and message are returned to the error handler. This program returns the error number 20101 to the invoking environment (the preceding program). MT Scope begins the main transaction, MTx inserts the buy order into a table. MTx invokes the autonomous transaction scope (AT Scope). When AT Scope begins, MT Scope suspends. ATx updates the audit table with customer information. MTx seeks to validate the order, finds that the selected item is unavailable, and therefore rolls back the main transaction. This graphic shows how a middle-tier application uses Continuous Query Notification. The steps of the process are described in the following text. MTx discovers that there are insufficient funds to cover the withdrawal. It finds that the customer has overdraft protection and sets a flag to the appropriate value. Tx2.1 updates the audit table. MTx releases the funds. MT Scope ends. This illustration shows the OO4O software components (layers). The first layer contains the Data Aware ActiveX Controls. The second layer consists of C++ Class Libraries and Oracle Data Control Automation Controllers (VB< Excel, ASP). The third layer contains the COM/DCOM. The fourth layer contains the OO40 In-Process Automation Server. The fifth layer contains the Oracle Client Libraries (OCI, CORE, NLS). The last layer contains the Oracle Database. This graphic depicts an Oracle Database that uses the embedded PL/SQL gateway to process client requests. The steps of the process are described in the following text. A main transaction scope (MT Scope) begins the main transaction, MTx. MTx invokes the first autonomous transaction scope (AT Scope1). MTx suspends. AT Scope 1 begins the transaction Tx1.1. AT Scope 1 commits or rolls back Tx1.1, then ends MTx resumes. MTx invokes AT Scope 2. MT suspends, passing control to AT Scope 2, which initially is performing queries. AT Scope 2 then begins Tx2.1 by, say, doing an update. AT Scope 2 commits or rolls back Tx2.1. Later, AT Scope 2 begins a second transaction, Tx2.2, then commits or rolls it back. AT Scope 2 performs a few queries, then ends, passing control back to MTx. MTx invokes AT Scope 3. MTx suspends, AT Scope 3 begins. AT Scope 3 begins Tx3.1, which in turn, invokes AT Scope 4. Tx3.1 suspends, AT Scope 4 begins. AT Scope 4 begins Tx4.1, commits or rolls it back, then ends. AT Scope 3 resumes. AT Scope 3 commits or rolls back Tx3.1, then ends. MTx resumes. MT Scope commits or rolls back MTx, then ends. This figure shows: A cylinder representing Oracle Database disk storage, containing a PL/SQL subprogram and a Java method A box representing an Oracle Server process execution, containing the PL/SQL Interpreter, the Java Virtual Machine, and the SQL Engine Two boxes representing an External Process Execution: one containing DLL and the other containing an external C process Interactions are shown using arrows between these objects: a double arrow between the database cylinder and the Oracle Server Process Execution box, a double arrow between this box and the External C Process box, and an arrow directed from the DLL box to the External C Process box. This figure shows 6 boxes with 7 lines connecting them: A "TX Interface" double arrow between a Transaction Manager box and an Application Program box An "XA Interface" double arrow between the Transaction Manager and a Resource Manager box A double arrow between the Application Program and the Resource Manager An "XA Interface" double arrow between the Transaction Manager and a Resource box A "Native Interface" double arrow between the Application Program and the Resource An arrow from the Resource to a box called Other A line between the Resource Manager and an Oracle (Database) box This illustration shows the Source Files being processed by the Host Language Compiler, which produces object files. The object files are next linked by the host linker, with the OCI Library, which outputs the application executable. The application can then communicate with the Oracle Server. This illustration shows a time line for two transactions, Transaction A (arbitrary) and Transaction B (serializable). Transaction A issues an update that is too recent for Transaction B to see. Transaction B changes the other row in the same block, and sees its own changes. Transaction A creates a possible "phantom row." Uncommitted changes are invisible to Transaction B, so Transaction A commits, making changes visible to transactions that begin later. Transaction B makes changes after Transaction A commits. Transaction B can see its own changes, but not the committed changes of Transaction A, so the attempt to update the row fails, after which Transaction B rolls back and retries. This illustration shows Transaction A and Transaction B. Transaction A has a read operation followed by an insert operation. Transaction B has a read operation followed by a delete operation. The read issued by Transaction A does not prevent Transaction B from deleting the parent row, and Transaction B's query for child rows does not prevent Transaction A from inserting child rows. MTx discovers that there are insufficient funds to cover the withdrawal. It finds that the customer does not have overdraft protection and sets a flag to the appropriate value. Tx2.1 updates the audit table. MTx Scope rolls back MTx, denying the releases of funds. MT Scope ends. This illustration shows the OO4O software components (layers). The first layer contains the Data Aware ActiveX Controls. The second layer consists of C++ Class Libraries and Oracle Data Control Automation Controllers (VB< Excel, ASP). The third layer contains the COM/DCOM. The fourth layer contains the OO40 In-Process Automation Server. The fifth layer contains the Oracle Client Libraries (OCI, CORE, NLS). The last layer contains the Oracle Database. This figure shows that user sessions can spawn multiple threads to the multithreaded agent process, to make calls to DLLs. It shows two user sessions as boxes composed of an Oracle Server and an HS. There are arrows from each of the user sessions to dispatcher threads in an agent process - one thread per user session. There are arrows from each of the dispatcher threads to task threads, also within the agent process. One of the task threads is shown handling requests from both user sessions (through both dispatcher threads). There are arrows from each of the task threads to a collection of DLLs (outside the agent process). Referenced or parent table (DEPTNO is its primary key): Dependent or child table (DEPTNO is a foreign key; values in dependent table must match a value in unique key or primary key of referenced table): This row violates the referential constraint because "50" is not present in the referenced table's primary key; therefore, the row is now allowed in the table. This row is allowed in the table because a null value is entered in the DEPTNO column; however, if a not null constraint is also defined for this column, this row is not allowed. The process includes these steps: A user visits a Web page, follows a hypertext link, or submits data in a form, which causes the browser to send a HTTP request for a URL to an HTTP server. The HTTP server calls a stored subprogram on an Oracle Database according to the data encoded in the URL. The data in the URL takes the form of parameters to be passed to the stored subprogram. The stored subprogram invokes subprograms in the PL/SQL Web Toolkit. Typically, subprograms such as The subprograms pass the dynamically generated page to the Web server. The Web server delivers the page to the client. UNIQUE is a constraint that means no row can duplicate a value in the constraint's column.) This row violates the UNIQUE key constraint, because SALES is already present in another row; therefore, it is not allowed in the table. This row is allowed because a NULL value is entered for the DNAME column; however, if a NOT NULL constraint is defined on the DNAME column, this row is not allowed. This figure shows OO4O objects and their relations. The relations are as follows: From OraServer to OraSession From OraDatabase to both OraServer and OraSession From each of OraDynaset, OraMetaData, OraParameters, OraSQLStmt, and OraAQ to OraDatabase From multiple OraField objects to OraDynaset From multiple OraMDAttribute objects to OraMetaData From multiple OraParameter and OraParamArray objects to OraParameters from OraAQMsg to OraAQ This graphic shows the TDT markup language schema beginning with the upper most box labeled IDCodeTranslator. The text that follows describes this schema. This graphic illustrates an OracleAS Web Cache interacting with Web servers through HTTP and HTTPS, and with Oracle Database through Oracle Net. This figure shows how control flows from a main transaction (MT) to an autonomous transaction (AT) and back again. The autonomous transaction commits two transactions, AT1 and AT2, before control returns to the main transaction. When control enters the executable section of the autonomous transaction (BEGIN), the main transaction suspends. When control exits the autonomous transaction (END), the main transaction resumes. COMMIT and ROLLBACK statements in an autonomous transaction end the active transaction, but they do not end the autonomous transaction. This appendix explains what the multithreaded Topics: This section explains how the multithreaded Topics: By default, an This architecture can consume an unnecessarily large amount of system resources. For example, suppose that several thousand user sessions simultaneously spawn The Oracle Database shared server architecture assumes that even when several thousand user sessions are open, only a small percentage of these connections are active at any given time. In shared server mode, there is a pool of shared server processes. User sessions connect to dispatcher processes that place the requested tasks in a queue. The tasks are picked up by the first available shared server processes. The number of shared server processes is usually less that the number of user sessions. The multithreaded One multithreaded Each Oracle Net listener that is running on a system listens for incoming connection requests for a set of SIDs. If the SID in an incoming Oracle Net connect string is an SID for which the listener is listening, then that listener processes the connection. Further, if a multithreaded In the architecture for multithreaded A single monitor thread. The monitor thread is responsible for: Maintaining communication with the listener Monitoring the load on the process Starting and stopping threads when required Several dispatcher threads. The dispatcher threads are responsible for: Handling communication with the Oracle Database Passing task requests to the task threads Several task threads. The task threads handle requests from the Oracle Database processes. Figure A-1 illustrates the architecture of the multithreaded All requests from a user session get handled by the same dispatcher thread. For example, dispatcher 1 handles communication with user session 1, and dispatcher 2 handles communication with user session 2. This is the case for the lifetime of the session. The individual requests can be serviced by different task threads. For example, task thread 1 can handle the request from user session 1, and later handle the request from user session 2. See Also: Figure A-1 Multithreaded extproc Agent Architecture These three thread types roughly correspond to the Oracle Database multithreaded server PMON, dispatcher, and shared server processes, respectively. Note: These topics explain each type of thread in more detail: See Also: When the agent control utility Creates the dispatcher and task threads. Registers the dispatcher threads with all the listeners that are handling connections to this Monitors the other threads and sends load information about the dispatcher threads to all the listener processes handling connections to this Continues to monitor each of the threads it has created. Dispatcher threads perform these functions: Accept incoming connections and task requests from Oracle Database servers. Place incoming requests on a queue for a task thread to pick up. Send results of a request back to the server that issued the request. Note: Task threads perform these functions: Pick up requests from a queue. Perform the necessary operations. Place the results on a queue for a dispatcher to pick up. One multithreaded A multithreaded Before starting Example A-1 Setting Configuration Parameters and Starting agtctl You can use Topics: You can start and stop Table A-1 Agent Control Utility (agtctl) Commands Starts a multithreaded Stops a multithreaded Sets a configuration parameter for a multithreaded Causes a parameter to revert to its default value Displays the value of a configuration parameter Deletes the entry for a particular SID from the control file Exits shell mode Lists available commands These commands can be issued in one of two ways: You can issue commands from the UNIX or DOS shell. This mode is called single-line command mode. You can enter The syntax and parameters for Note: All commands are case-sensitive. The If the multithreaded This section describes the use of Set the configuration parameters for a multithreaded Use the Syntax Example Use the Syntax Example Use the Normal (default) Immediate Abort Without talking to the multithreaded Syntax Example To examine the value of a configuration parameter, use the Syntax Example You can reset a configuration parameter to its default value using the Syntax Example The Syntax Example In shell mode, start This results in the prompt Set the name of the agent SID by entering: All subsequent commands are assumed to be for the specified SID until the You can set the language for error messages as follows: The commands themselves are the same as those for the single-line command mode. To exit shell mode, enter The following examples use shell mode commands. This example sets a value for the Table A-2 describes and gives the defaults of the configuration parameters for the agent control utility. Table A-2 Configuration Parameters for agtctl Maximum number of dispatchers 1 Number of dispatchers listening on TCP (the rest are using IPC) 0 Maximum number of task threads 2 Maximum number of sessions for each task thread 5 Address on which the listener is listening (needed for registration) Note: Address the agent uses to communicate with the listener. This is the address on which the agent listens for all communication, including shutdown messages from Notes: || indicates that max_dispatchers, tcp_dispatchers, max_task_threads, and max_sessions To improve performance, you might need to change the values of some or all of the parameters You can calculate the optimum values of Where: ( There is no formula for computing the optimum value of You must fine-tune these parameter settings, based on the capability of your hardware, and ensure that the concurrent threads do not exhaust your operating system. The value of Example Suppose: The maximum number of sessions that can be connected to The maximum number of sessions that can be connected to (The maximum number of sessions that can be connected to The maximum number of connections that the system can support for each dispatcher ( The maximum number of sessions for each task thread ( The optimum values for these parameters are: That is, optimally: The maximum number of dispatchers is seven. Four of the seven dispatchers are listening on TCP/IP, and the remaining three are listening on IPC. The maximum number of task threads is 33. listener_address and shutdown_address The values of the configuration parameters For example, this value of See Also: This chapter explains how to use Oracle Flashback Technology in database applications. Topics: Oracle Flashback Technology is a group of Oracle Database features that let you view past states of database objects or to return database objects to a previous state without using point-in-time media recovery. With flashback features, you can: Perform queries that return past data Perform queries that return metadata that shows a detailed history of changes to the database Recover tables or rows to a previous point in time Automatically track and archive transactional data changes Roll back a transaction and its dependent transactions while the database remains online Oracle Flashback features use the Automatic Undo Management (AUM) system to obtain metadata and historical data for transactions. They rely on undo data, which are records of the effects of individual transactions. For example, if a user runs an Undo data is persistent and survives a database shutdown. By using flashback features, you can use undo data to query past data or recover from logical damage. Besides using it in flashback features, Oracle Database uses undo data to perform these actions: Roll back active transactions Recover terminated transactions by using database or process recovery Provide read consistency for SQL queries Topics: For additional general information about flashback features, see Oracle Database Concepts In application development, you can use these flashback features to report historical data or undo erroneous changes. (You can also use these features interactively as a database user or administrator.) Oracle Flashback Query Use this feature to retrieve data for an earlier time that you specify with the Oracle Flashback Version Query Use this feature to retrieve metadata and historical data for a specific time interval (for example, to view all the rows of a table that ever existed during a given time interval). Metadata for each row version includes start and end time, type of change operation, and identity of the transaction that created the row version. To create an Oracle Flashback Version Query, use the Oracle Flashback Transaction Query Use this feature to retrieve metadata and historical data for a given transaction or for all transactions in a given time interval. To perform an Oracle Flashback Transaction Query, select from the static data dictionary view Typically, you use Oracle Flashback Transaction Query with an Oracle Flashback Version Query that provides the transaction IDs for the rows of interest (see "Using Oracle Flashback Transaction Query with Oracle Flashback Version Query"). DBMS_FLASHBACK Package Use this feature to set the internal Oracle Database clock to an earlier time so that you can examine data that was current at that time, or to roll back a transaction and its dependent transactions while the database remains online (see Flashback Transaction). For more information, see "Using DBMS_FLASHBACK Package". Flashback Transaction Use Flashback Transaction to roll back a transaction and its dependent transactions while the database remains online. This recovery operation uses undo data to create and run the corresponding compensating transactions that return the affected data to its original state. (Flashback Transaction is part of Flashback Data Archive (Oracle Total Recall) Use Flashback Data Archive to automatically track and archive both regular queries and Oracle Flashback Query, ensuring SQL-level access to the versions of database objects without getting a snapshot-too-old error. For more information, see "Using Flashback Data Archive (Oracle Total Recall)". These flashback features are primarily for data recovery. Typically, you use these features only as a database administrator. This chapter focuses on the "Application Development Features". For more information about the database administration features, see Oracle Database Administrator's Guide and the Oracle Database Backup and Recovery User's Guide. Oracle Flashback Table Use this feature to restore a table to its state at a previous point in time. You can restore a table while the database is on line, undoing changes to only the specified table. Oracle Flashback Drop Use this feature to recover a dropped table. This feature reverses the effects of a Oracle Flashback Database Use this feature to quickly return the database to an earlier point in time, by undoing all of the changes that have taken place since then. This is fast, because you do not have to restore database backups. Before you can use flashback features in your application, you or your database administrator must perform the configuration tasks described in these topics: Configuring Your Database for Oracle Flashback Transaction Query Enabling Oracle Flashback Operations on Specific LOB Columns To configure your database for Automatic Undo Management (AUM), you or your database administrator must: Create an undo tablespace with enough space to keep the required data for flashback operations. The more often users update the data, the more space is required. The database administrator usually calculates the space requirement. Enable AUM, as explained in Oracle Database Administrator's Guide. Set these database initialization parameters: For a fixed-size undo tablespace, Oracle Database automatically tunes the system to give the undo tablespace the best possible undo retention. For an automatically extensible undo tablespace, Oracle Database retains undo data longer than the longest query duration and the low threshold of undo retention specified by the Note: Setting Specify the See Also: To configure your database for the Oracle Flashback Transaction Query feature, you or your database administrator must: Ensure that Oracle Database is running with version 10.0 compatibility. Enable supplemental logging: To configure your database for the Flashback Transaction feature, you or your database administrator must: With the database mounted but not open, enable Open at least one archive log: If not done, enable minimal and primary key supplemental logging: If you want to track foreign key dependencies, enable foreign key supplemental logging: Note: To enable flashback operations on specific LOB columns of a table, use the Because undo data for LOB columns can be voluminous, you must define which LOB columns to use with flashback operations. See Also: You or your database administrator must grant privileges to users, roles, or applications that must use these flashback features. For information about the For Oracle Flashback Query and Oracle Flashback Version Query To allow access to specific objects during queries, grant To allow queries on all tables, grant the For Oracle Flashback Transaction Query Grant the To allow execution of undo SQL code retrieved by an Oracle Flashback Transaction Query, grant For DBMS_FLASHBACK Package To allow access to the features in the For Flashback Data Archive (Oracle Total Recall) To allow a specific user to enable Flashback Data Archive on tables, using a specific Flashback Data Archive, grant the To allow execution of these statements, grant the To grant the To create a default Flashback Data Archive, using either the To disable Flashback Data Archive for a table that has been enabled for Flashback Data Archive, you must either be logged on as To use Oracle Flashback Query, use a Uses of Oracle Flashback Query include: Recovering lost data or undoing incorrect, committed changes. For example, if you mistakenly delete or update rows, and then commit them, you can immediately undo the mistake. Comparing current data with the corresponding data at an earlier time. For example, you can run a daily report that shows the change in data from yesterday. You can compare individual rows of table data or find intersections or unions of sets of rows. Checking the state of transactional data at a particular time. For example, you can verify the account balance of a certain day. Simplifying application design by removing the need to store some kinds of temporal data. Oracle Flashback Query lets you retrieve past data directly from the database. Applying packaged applications, such as report generation tools, to past data. Providing self-service error correction for an application, thereby enabling users to undo and correct their errors. Topics: For more information about the Suppose that you discover at 12:30 PM that the row for employee Chung was deleted from the Example 12-1 retrieves the state of the record for Example 12-1 Retrieving a Lost Row with Oracle Flashback Query Example 12-2 restores Chung's information to the You can specify or omit the Note: You can use the To use the result of Oracle Flashback Query in a DDL or DML statement that affects the current state of the database, use an If a possible 3-second error (maximum) is important to Oracle Flashback Query in your application, use an SCN instead of a time stamp. See "General Guidelines for Oracle Flashback Technology". You can create a view that refers to past data by using the If you specify a relative time by subtracting from the current time on the database host, the past time is recalculated for each query. For example: You can use the You can store the results by preceding Oracle Flashback Query with a Use Oracle Flashback Version Query to retrieve the different versions of specific rows that existed during a given time interval. A row version is created whenever a Specify Oracle Flashback Version Query using the where Oracle Flashback Version Query returns a table with a row for each version of the row that existed at any time during the specified time interval. Each row in the table includes pseudocolumns of metadata about the row version, described in Table 12-1. This information can reveal when and how a particular change (perhaps erroneous) occurred to your database. Table 12-1 Oracle Flashback Version Query Row Data Pseudocolumns Starting System Change Number (SCN) or If this pseudocolumn is SCN or If this pseudocolumn is Identifier of the transaction that created the row version. Operation performed by the transaction: For user updates of an index key, Oracle Flashback Version Query might treat an A given row version is valid starting at its time Here is a typical use of Oracle Flashback Version Query: You can use See Also: Use Oracle Flashback Transaction Query to retrieve metadata and historical data for a given transaction or for all transactions in a given time interval. Oracle Flashback Transaction Query queries the static data dictionary view The column This statement queries the This statement uses Oracle Flashback Version Query as a subquery to associate each row version with the Note: See Also: Oracle Database Backup and Recovery User's Guide. for information about how a database administrator can use Flashback Table to restore an entire table, rather than individual rows Oracle Database Administrator's Guide for information about how a database administrator can use Flashback Table to restore an entire table, rather than individual rows In this example, a database administrator does this: Now Next, a transaction reinserts The database administrator detects the application error and must diagnose the problem. The database administrator issues this query to retrieve versions of the rows in the Results are similar to: The results table rows are in descending chronological order. The third row corresponds to the version of the row in the table The database administrator identifies transaction Results are similar to: To make the result of the next query easier to read, the database administrator uses these SQL*Plus commands: To see the details of the erroneous transaction and all subsequent transactions, the database administrator performs this query: Results are similar to: Note: Result is similar to: The most recent Note: Topics: Your application examines a row of data and records the corresponding If the package subprogram changed the row, then Your application queries again to obtain the new row data and When a VPD policy is added to a table, it is no longer possible to select the Create a function that returns a row SCN, as in Example 12-3. In the policy predicate function, add a predicate that stores the row SCN in the context that the function uses while processing rows. For example: Use the function to fetch the row. For example: Example 12-3 Function that Can Return Row SCN from Table that has VPD The The You must have the To use the Specify a past time by invoking either Perform regular queries (that is, queries without special flashback-feature syntax such as The database is queried at the specified past time. Return to the present by invoking You must invoke To use a cursor to store the results of queries, open the cursor before invoking Perform Compare current data with the past data. After invoking You can invoke See Also: Oracle Database PL/SQL Packages and Types Reference for details of the The The transactions being rolled back are subject to these restrictions: They cannot have performed DDL operations that changed the logical structure of database tables. They cannot use Large Object (LOB) Data Types: They cannot use features that LogMiner does not support. The features that LogMiner supports depends on the value of the Flashback Transaction inherits SQL data type support from LogMiner. Therefore, if LogMiner fails due to an unsupported SQL data type in a the transaction, Flashback Transaction fails too. Some data types, though supported by LogMiner, do not generate undo information as part of operations that modify columns of such types. Therefore, Flashback Transaction does not support tables containing these data types. These include tables with BLOB, CLOB and XML type. See Also: Oracle Data Guard Concepts and Administration for information about data type and DDL support on a logical standby database Oracle Database SQL Language Reference for information about LOB data types Oracle Database Utilities for information about LogMiner Oracle Database Administrator's Guide for information about the Topics: In the context of Flashback Transaction, transaction 2 can depend on transaction 1 in any of these ways: Transaction 1 changes a row of a table, and later transaction 2 changes the same row. A table has a primary key constraint on column c. In a row of the table, column c has the value v. Transaction 1 deletes that row, and later transaction 2 inserts a row into the same table, assigning the value v to column c. In table b, column b1 has a foreign key constraint on column a1 of table a. Transaction 1 changes a value in a1, and later transaction 2 changes a value in b1. The parameters of the Number of transactions to be backed out List of transactions to be backed out, identified either by name or by XID Time hint, if you identify transactions by name Specify a time that is earlier than any transaction started. Backout option from Table 12-2 For the syntax of the Table 12-2 Flashback TRANSACTION_BACKOUT Options Backs out specified transactions and all dependent transactions in a post-order fashion (that is, children are backed out before parents are backed out). Without Default. Backs out specified transactions, which are expected to have no dependent transactions. First dependent transactions causes an error and appears in Backs out specified transactions, ignoring dependent transactions. Server runs undo SQL statements for specified transactions in reverse order of commit times. If no constraints break and you are satisfied with the result, you can commit the changes; otherwise, you can roll them back. Backs out changes to nonconflicting rows of the specified transactions. Database remains consistent, but transaction atomicity is lost. To see the reports that The static data dictionary view The static data dictionary view A Flashback Data Archive provides the ability to track and store transactional changes to a table over its lifetime. A Flashback Data Archive is useful for compliance with record stage policies and audit reports. A Flashback Data Archive consists of one or more tablespaces or parts thereof. You can have multiple Flashback Data Archives. If you are logged on as By default, flashback archiving is off for any table. You can enable flashback archiving for a table if all of these conditions are true: You have the The table is neither nested, clustered, temporary, remote, or external. The table contains neither After flashback archiving is enabled for a table, you can disable it only if you either have the When choosing a Flashback Data Archive for a specific table, consider the data retention requirements for the table and the retention times of the Flashback Data Archives on which you have the Topics: See Also: Create a Flashback Data Archive with the Name of the Flashback Data Archive Name of the first tablespace of the Flashback Data Archive (Optional) Maximum amount of space that the Flashback Data Archive can use in the first tablespace The default is unlimited. Unless your space quota on the first tablespace is also unlimited, you must specify this value; otherwise, error ORA-55621 occurs. Retention time (number of days that Flashback Data Archive data for the table is guaranteed to be stored) If you are logged on as Examples Create a default Flashback Data Archive named Create a Flashback Data Archive named For more information about the With the Change the retention time of a Flashback Data Archive Purge some or all of its data Add, modify, and remove tablespaces Note: If you are logged on as Examples Make Flashback Data Archive To Flashback Data Archive To Flashback Data Archive Change the maximum space that Flashback Data Archive Allow Flashback Data Archive Change the retention time for Flashback Data Archive Remove tablespace (Tablespace Purge all historical data from Flashback Data Archive Purge all historical data older than one day from Flashback Data Archive Purge all historical data older than SCN 728969 from Flashback Data Archive For more information about the Drop a Flashback Data Archive with the Example Remove Flashback Data Archive For more information about the By default, the system has no default Flashback Data Archive. If you are logged on as Specify the name of an existing Flashback Data Archive in the If Include The default Flashback Data Archive for the system is the default Flashback Data Archive for every user who does not have his or her own default Flashback Data Archive. See Also: Oracle Database SQL Language Reference for more information about the Oracle Database SQL Language Reference for more information about the By default, flashback archiving is disabled for any table. You can enable flashback archiving for a table if you have the To enable flashback archiving for a table, include the If you enable flashback archiving for a table, but AUM is disabled, error ORA-55614 occurs when you try to modify the table. If a table has flashback archiving enabled, and you try to enable it again with a different Flashback Data Archive, an error occurs. After flashback archiving is enabled for a table, you can disable it only if you either have the See Also: Examples Create table Create table Enable flashback archiving for the table Enable flashback archiving for the table Disable flashback archiving for the table Flashback Data Archive supports many DDL statements, including some that alter the table definition or move data. For example: Adds, drops, renames, or modifies a column Adds, drops, or renames a constraint Drops or truncates a partition or subpartition operation Some DDL statements cause error ORA-55610 when used on a table enabled for Flashback Data Archive. For example: If you must use unsupported DDL statements on a table enabled for Flashback Data Archive, use the See Also: Oracle Database SQL Language Reference for information about the Oracle Database SQL Language Reference for information about the Oracle Database SQL Language Reference for information about the Oracle Database SQL Language Reference for information about the Oracle Database PL/SQL Packages and Types Reference for information about the Table 12-3 lists and briefly describes the static data dictionary views that you can query for information about Flashback Data Archive files. Table 12-3 Static Data Dictionary Views for Flashback Data Archive Files Displays information about Flashback Data Archive files. Displays tablespaces of Flashback Data Archive files. Displays information about tables that are enabled for Data Flashback Archive files. See Also: Oracle Database Reference for detailed information about Oracle Database Reference for detailed information about Oracle Database Reference for detailed information about Scenario: Using Flashback Data Archive to Enforce Digital Shredding Scenario: Using Flashback Data Archive to Access Historical Data Your company wants to "shred" (delete) historical data changes to the When history data from transactions on You want to be able to retrieve the inventory of all items at the beginning of the year from the table Create a default Flashback Data Archive named Enable Flashback Data Archive for the tables To retrieve the inventory of all items at the beginning of the year 2007, use this query: To retrieve the stock price for each symbol in your portfolio at the close of business on July 23, 2007, use this query: You want users to be able to generate reports from the table Create a default Flashback Data Archive named Enable Flashback Data Archive for the table Lisa wants a report on the performance of her investments at the close of business on December 31, 2006. She uses this query: A medical insurance company must audit a medical clinic. The medical insurance company has its claims in the table The company enables Flashback Data Archive for the table On May 1, 2007, clients were charged the wrong amounts for some diagnoses and tests. To see the records as of May 1, 2007, the company uses this query: An end user recovers from erroneous transactions that were previously committed in the database. The undo data for the erroneous transactions is no longer available, but because the required historical information is available in the Flashback Data Archive, Flashback Query works seamlessly. Lisa manages a software development group whose product sales are doing well. On November 3, 2007, she decides to give all her level-three employees who have more than two years of experience a salary increase of 10% and a promotion to level four. Lisa asks her HR representative, Bob, to make the changes. Using the HR web application, Bob updates the At first, Bob thinks he cannot return the employee table to its prior state without going to the backups. Then he remembers that the First, he verifies that no other transaction modified the Next, Bob uses these statements to return the Bob then reexecutes the update that Lisa had requested. Use the Use Oracle Flashback Query, Oracle Flashback Version Query, or Oracle Flashback Transaction Query for SQL code that you write, for convenience. An Oracle Flashback Query, for example, is flexible enough to do comparisons and store results in a single query. To obtain an SCN to use later with a flashback feature, use To compute or retrieve a past time to use in a query, use a function return value as a time stamp or SCN argument. For example, add or subtract an Use Oracle Flashback Query, Oracle Flashback Version Query, and Oracle Flashback Transaction Query locally or remotely. An example of a remote Oracle Flashback Query is: To ensure database consistency, always perform a Remember that all flashback processing uses the current session settings, such as national language and character set, not the settings that were in effect at the time being queried. Remember that DDLs that alter the structure of a table (such as drop/modify column, move table, drop partition, truncate table/partition, and add constraint) invalidate any existing undo data for the table. If you try to retrieve data from a time before such a DDL executed, error ORA-01466 occurs. DDL operations that alter the storage attributes of a table (such as To query past data at a precise time, use an SCN. If you use a time stamp, the actual time queried might be up to 3 seconds earlier than the time you specify. Oracle Database uses SCNs internally and maps them to time stamps at a granularity of 3 seconds. For example, suppose that the SCN values 1000 and 1005 are mapped to the time stamps 8:41 AM and 8:46 AM, respectively. A query for a time between 8:41:00 and 8:45:59 AM is mapped to SCN 1000; an Oracle Flashback Query for 8:46 AM is mapped to SCN 1005. Therefore, if you specify a time that is slightly after a DDL operation (such as a table creation) Oracle Database might use an SCN that is just before the DDL operation, causing error ORA-01466. You cannot retrieve past data from a dynamic performance ( You can perform queries on past data in static data dictionary views, such as Use the Minimize the amount of undo data that must be accessed. Use queries to select small sets of past data using indexes, not to scan entire tables. If you must scan a full table, add a parallel hint to the query. The performance cost in I/O is the cost of paging in data and undo blocks that are not in the buffer cache. The performance cost in CPU use is the cost of applying undo information to affected data blocks. When operating on changes in the recent past, flashback operations are CPU-bound. For Oracle Flashback Version Query, use index structures. Oracle Database keeps undo data for index changes and data changes. Performance of index lookup-based Oracle Flashback Version Query is an order of magnitude faster than the full table scans that are otherwise needed. In an Oracle Flashback Transaction Query, the A Oracle Flashback Query against a materialized view does not take advantage of query rewrite optimization. You can use the PL/SQL hierarchical profiler to identify bottlenecks and performance-tuning opportunities in PL/SQL applications. The profiler reports the dynamic execution profile of a PL/SQL program organized by function calls, and accounts for SQL and PL/SQL execution times separately. No special source or compile-time preparation is required; any PL/SQL program can be profiled. This chapter describes the PL/SQL hierarchical profiler and explains how to use it to collect and analyze profile data for a PL/SQL program. Topics: Nonhierarchical (flat) profilers record the time that a program spends within each subprogram—the function time or self time of each subprogram. Function time is helpful, but often inadequate. For example, it is helpful to know that a program spends 40% of its time in the subprogram The PL/SQL hierarchical profiler: Reports the dynamic execution profile of your PL/SQL program, organized by subprogram calls Accounts for SQL and PL/SQL execution times separately Requires no special source or compile-time preparation Stores results in database tables (hierarchical profiler tables) for custom report generation by integrated development environment (IDE) tools (such as SQL Developer and third-party tools) Provides subprogram-level execution summary information, such as: Number of calls to the subprogram Time spent in the subprogram itself (function time or self time) Time spent in the subprogram itself and in its descendent subprograms (subtree time) Detailed parent-children information, for example: All callers of a given subprogram (parents) All subprograms that a given subprogram called (children) How much time was spent in subprogram x when called from y How many calls to subprogram x were from y The PL/SQL hierarchical profiler is implemented by the Data collection The data collection component is an intrinsic part of the PL/SQL Virtual Machine. The Analyzer The analyzer component processes the raw profiler output and stores the results in hierarchical profiler tables. Note: To collect profile data from your PL/SQL program for the PL/SQL hierarchical profiler, follow these steps: Ensure that you have these privileges: Use the Run your PL/SQL program long enough to get adequate code coverage. To get the most accurate measurements of elapsed time, avoid unrelated activity on the system on which your PL/SQL program is running. Use the For more information about Consider this PL/SQL procedure, The SQL script in Example 8-1 profiles the execution of the PL/SQL procedure Example 8-1 Profiling a PL/SQL Procedure Note: To run the SQL script in Example 8-1, you must have For more information about using directory objects, see Oracle Database SecureFiles and Large Objects Developer's Guide. Raw profiler output is intended to be processed by the analyzer component of the PL/SQL hierarchical profiler. However, even without such processing, it provides a simple function-level trace of the program. This topic explains how to understand raw profiler output. Note: The SQL script in Example 8-1 wrote this raw profiler output to the file Table 8-1 Raw Profiler Output File Indicators Call to a subprogram (call event) Return from a subprogram (return event) Elapsed time between preceding and following events Comment Call events ( Each call event ( Namespace to which the called subprogram belongs Name of the PL/SQL module in which the called subprogram is defined Type of the PL/SQL module in which the called subprogram is defined Name of the called subprogram This name might be one of the "Special Function Names". Hexadecimal value that represents an MD5 hash of the signature of the called subprogram The Line number at which the called subprogram is defined in the PL/SQL module PL/SQL hierarchical profiler does not measure time spent at individual lines within modules, but you can use line numbers to identify the source locations of subprograms in the module (as IDE/Tools do) and to distinguish between overloaded subprograms. For example, consider this entry in the preceding example of raw profiler output: The components of the preceding entry have these meanings: Note: When a call to a The subprograms that the PL/SQL hierarchical profiler tracks are classified into the namespaces PLSQL and SQL, as follows: Namespace PLSQL includes: PL/SQL subprogram calls PL/SQL triggers PL/SQL anonymous blocks Remote subprogram calls Package initialization blocks Namespace SQL includes SQL statements executed from PL/SQL, such as queries, data manipulation language (DML) statements, data definition language (DDL) statements, and native dynamic SQL statements PL/SQL hierarchical profiler tracks certain operations as if they were functions with the names and namespaces shown in Table 8-2. Table 8-2 Function Names of Operations that the PL/SQL Hierarchical Profiler Tracks Call to PL/SQL Virtual Machine PL/SQL PL/SQL anonymous block PL/SQL Package initialization block PL/SQL Static SQL statement at line SQL Dynamic SQL statement at line SQL SQL SQL The analyzer component of the PL/SQL hierarchical profiler, Table 8-3 PL/SQL Hierarchical Profiler Database Tables Top-level information for this run of Information for each subprogram profiled in this run of Parent-child information for each subprogram profiled in this run of Topics: Note: To create the hierarchical profiler tables in Table 8-3 and the other data structures required for persistently storing profile data, follow these steps: Run the script This script creates both the hierarchical profiler tables in Table 8-3 and the other data structures required for persistently storing profile data. Note: Ensure that you have these privileges: Use the PL/SQL API (For an example of a raw profiler output file, see For more information about Use the hierarchical profiler tables to generate custom reports. The anonymous block in Example 8-2: Invokes the function Analyzes the profile data in the raw profiler output file Returns a unique identifier that you can use to query the hierarchical profiler tables in Table 8-3. (By querying these hierarchical profiler tables, you can produce customized reports.) Stores the unique identifier in the variable These topics explain how to use the hierarchical profiler tables in Table 8-3: Table 8-4 describes the columns of the hierarchical profiler table The primary key for the hierarchical profiler table Table 8-4 DBMSHP_RUNS Table Columns Unique identifier for this run of Time stamp for this run of Comment that you provided for this run of Total elapsed time for this run of Table 8-5 describes the columns of the hierarchical profiler table The primary key for the hierarchical profiler table Table 8-5 DBMSHP_FUNCTION_INFO Table Columns References Symbol identifier for subprogram (unique for this run of Owner of module in which each subprogram is defined (for example, Module in which subprogram is defined (for example, Type of module in which subprogram is defined (for example, Name of subprogram (not necessarily a function) (for example, This name might be one of the "Special Function Names". For subprogram A recursive call to function Line number in Hash code for signature of subprogram (unique for this run of Namespace of subprogram. For details, see "Namespaces of Tracked Subprograms". Elapsed time, in microseconds, for subprogram, including time spent in descendant subprograms. Elapsed time, in microseconds, for subprogram, excluding time spent in descendant subprograms. Number of calls to subprogram. Table 8-6 describes the columns of the hierarchical profiler table Table 8-6 DBMSHP_PARENT_CHILD_INFO Table Columns References Parent symbol ID. Child symbol ID. Elapsed time, in microseconds, for Elapsed time, in microseconds, for Number of calls to Overloaded subprograms are different subprograms with the same name (see Oracle Database PL/SQL Language Reference). Suppose that a program declares three subprograms named In the profile data for two different runs, the The hierarchical profiler tables for the PL/SQL procedure Example 8-3 DBMSHP_RUNS Table for Sample PL/SQL Procedure Example 8-4 DBMSHP_FUNCTION_INFO Table for Sample PL/SQL Procedure Example 8-5 DBMSHP_PARENT_CHILD_INFO Table for Sample PL/SQL Procedure Consider the third row of the table For an example of a call to Example 8-6 creates a package, creates a procedure that invokes subprograms in the package, profiles the procedure, and uses Example 8-6 Invoking DBMS_HPROF.analyze with Options The You can browse the generated HTML reports in any browser. The browser's navigational capabilities, combined with well chosen links, provide a powerful way to analyze performance of large applications, improve application performance, and lower development costs. Topics: The command to run the Each Suppose that your raw profiler output file, To generate a PL/SQL hierarchical profiler HTML report from a single raw profiler output file, use these commands: The preceding Topics: The first page of an HTML report from a single raw profiler output file includes summary information and hyperlinks to other pages of the report. Sample First Page PL/SQL Elapsed Time (microsecs) Analysis 2831 microsecs (elapsed time) & 12 function calls The PL/SQL Hierarchical Profiler produces a collection of reports that present information derived from the profiler output log in a variety of formats. These reports have been found to be the most generally useful as starting points for browsing: Function Elapsed Time (microsecs) Data sorted by Total Subtree Elapsed Time (microsecs) Function Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) In addition, the following reports are also available: Function Elapsed Time (microsecs) Data sorted by Function Name Function Elapsed Time (microsecs) Data sorted by Total Descendants Elapsed Time (microsecs) Function Elapsed Time (microsecs) Data sorted by Total Function Call Count Function Elapsed Time (microsecs) Data sorted by Mean Subtree Elapsed Time (microsecs) Function Elapsed Time (microsecs) Data sorted by Mean Function Elapsed Time (microsecs) Function Elapsed Time (microsecs) Data sorted by Mean Descendants Elapsed Time (microsecs) Module Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Module Elapsed Time (microsecs) Data sorted by Module Name Module Elapsed Time (microsecs) Data sorted by Total Function Call Count Namespace Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Namespace Elapsed Time (microsecs) Data sorted by Namespace Namespace Elapsed Time (microsecs) Data sorted by Total Function Call Count Parents and Children Elapsed Time (microsecs) Data The function-level reports provide a flat view of the profile information. Each function-level report includes this information for each function: Function time (time spent in the function itself, also called "self time") Descendants time (time spent in the descendants of the function) Subtree time (time spent in the subtree of the function—function time plus descendants time) Number of calls to the function Function name The function name is hyperlinked to the Parents and Children Report for the function. Each function-level report is sorted on a particular attribute; for example, function time or subtree time. This sample report is sorted in descending order of the total subtree elapsed time for the function, which is why information in the Subtree and Ind% columns is in bold type: Sample Report Function Elapsed Time (microsecs) Data sorted by Total Subtree Elapsed Time (microsecs) 2831 microsecs (elapsed time) & 12 function calls Each module-level report includes this information for each module (for example, package or type): Module time (time spent in the module—sum of the function times of all functions in the module) Number of calls to functions in the module Each module-level report is sorted on a particular attribute; for example, module time or module name. This sample report is sorted by module time, which is why information in the Module, Ind%, and Cum% columns is in bold type: Sample Report Module Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) 166878 microsecs (elapsed time) & 1099 function calls Each namespace-level report includes this information for each namespace: Namespace time (time spent in the namespace—sum of the function times of all functions in the namespace) Number of calls to functions in the namespace Each namespace-level report is sorted on a particular attribute; for example, namespace time or number of calls to functions in the namespace. This sample report is sorted by function time, which is why information in the Function, Ind%, and Cum% columns is in bold type: Sample Report Namespace Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) 166878 microsecs (elapsed time) & 1099 function calls For each function tracked by the profiler, the Parents and Children Report provides information about parents (functions that call it) and children (functions that it calls). For each parent, the report gives the function's execution profile (subtree time, function time, descendants time, and number of calls). For each child, the report gives the execution profile for the child when called from this function (but not when called from other functions). The execution profile for a function includes the same information for that function as a function-level report includes for each function (for details, see "Function-Level Reports"). This Sample Report is a fragment of a Parents and Children Report that corresponds to a function named There are two calls to the function The total subtree time for the function is 166,860 microseconds—11,713 microseconds (7.0%) in the function itself and 155,147 microseconds (93.0%) in its descendants. After the row "Parents" are the execution profile rows for the two parents of The first parent execution profile row, for The subtree time for The function time for After the row "Children" are the execution profile rows for the children of The third child execution profile row, for The subtree time, function time and descendants time for Of the total descendants time for Sample Report HR.P.UPLOAD (Line 3) To generate a PL/SQL hierarchical profiler HTML difference report from two raw profiler output files, use these commands: The preceding Topics: Difference reports use these conventions: In a report title, Delta means difference, or change. A positive value indicates that the number increased (regressed) from the first run to the second run. A negative value for a difference indicates that the number decreased (improved) from the first run to the second run. The symbol The first page of an HTML difference report from two raw profiler output files includes summary information and hyperlinks to other pages of the report. Sample First Page PL/SQL Elapsed Time (microsecs) Analysis – Summary Page This analysis finds a net regression of 2709589 microsecs (elapsed time) or 80% (3393719 versus 6103308). Here is a summary of the 7 most important individual function regressions and improvements: Regressions: 3399382 microsecs (elapsed time) Improvements: 689793 microsecs (elapsed time) The PL/SQL Timing Analyzer produces a collection of reports that present information derived from the profiler's output logs in a variety of formats. The following reports have been found to be the most generally useful as starting points for browsing: Function Elapsed Time (microsecs) Data for Performance Regressions Function Elapsed Time (microsecs) Data for Performance Improvements In addition, the following reports are also available: Function Elapsed Time (microsecs) Data sorted by Function Name Function Elapsed Time (microsecs) Data sorted by Total Subtree Elapsed Time (microsecs) Delta Function Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Delta Function Elapsed Time (microsecs) Data sorted by Total Descendants Elapsed Time (microsecs) Delta Function Elapsed Time (microsecs) Data sorted by Total Function Call Count Delta Module Elapsed Time (microsecs) Data sorted by Module Name Module Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Delta Module Elapsed Time (microsecs) Data sorted by Total Function Call Count Delta Namespace Elapsed Time (microsecs) Data sorted by Namespace Namespace Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Namespace Elapsed Time (microsecs) Data sorted by Total Function Call Count File Elapsed Time (microsecs) Data Comparison with Parents and Children Each function-level difference report includes, for each function, the change in these values from the first run to the second run: Function time (time spent in the function itself, also called "self time") Descendants time (time spent in the descendants of the function) Subtree time (time spent in the subtree of the function—function time plus descendants time) Number of calls to the function Mean function time The mean function time is the function time divided by number of calls to the function. Function name The function name is hyperlinked to the Parents and Children Difference Report for the function. The report in Sample Report 1 shows the difference information for all functions that performed better in the first run than they did in the second run. Note that: For For Sample Report 1 Function Elapsed Time (microsecs) Data for Performance Regressions The report in Sample Report 2 shows the difference information for all functions that performed better in the second run than they did in the first run. Sample Report 2 Function Elapsed Time (microsecs) Data for Performance Improvements The report in Sample Report 3 summarizes the difference information for all functions. Sample Report 3 Function Elapsed Time (microsecs) Data sorted by Total Function Call Count Delta Each module-level report includes, for each module, the change in these values from the first run to the second run: Module time (time spent in the module—sum of the function times of all functions in the module) Number of calls to functions in the module Sample Report Module Elapsed Time (microsecs) Data sorted by Total Function Elapsed Time (microsecs) Delta Each namespace-level report includes, for each namespace, the change in these values from the first run to the second run: Namespace time (time spent in the namespace—sum of the function times of all functions in the namespace) Number of calls to functions in the namespace Sample Report Namespace Elapsed Time (microsecs) Data sorted by Namespace The Parents and Children Difference Report for a function shows changes in the execution profiles of these from the first run to the second run: Parents (functions that call the function) Children (functions that the function calls) Execution profiles for children include only information from when this function calls them, not for when other functions call them. The execution profile for a function includes this information: Function time (time spent in the function itself, also called "self time") Descendants time (time spent in the descendants of the function) Subtree time (time spent in the subtree of the function—function time plus descendants time) Number of calls to the function Function name The sample report is a fragment of a Parents and Children Difference Report that corresponds to a function named The first row, a summary of the difference between the first and second runs, shows regression: function time increased by 1,094,099 microseconds (probably because the function was called five more times). The "Parents" rows show that The "Children" rows show that Sample Report HR.P.X (Line 11) The Parents and Children Difference Report for a function is accompanied by a Function Comparison Report, which shows the execution profile of the function for the first and second runs and the difference between them. This example is the Function Comparison Report for the function Sample Report Elapsed Time (microsecs) for HR.P.X (Line 11) (20.1% of total regression) Edition-based redefinition enables you to upgrade the database component of an application while it is in use, thereby minimizing or eliminating down time. To upgrade an application while it is in use, you copy the database objects that comprise the application and redefine the copied objects in isolation. Your changes do not affect users of the application—they continue to run the unchanged application. When you are sure that your changes are correct, you make the upgraded application available to all users. Using edition-based redefinition means using one or more of its component features. The features you use, and the down time, depend on these factors: What kind of database objects you redefine How available the database objects must be to users while you are redefining them Whether you make the upgraded application available to some users while others continue to use the older version of the application You always use the edition feature to copy the database objects and redefine the copied objects in isolation; that is why the procedure that this chapter describes for upgrading applications online is called edition-based redefinition. If the object type of every object you will redefine is editionable (defined in "Editionable and Noneditionable Schema Object Types"), the edition is the only feature you use. Table is not an editionable type. If you change the structure of one or more tables, you also use the editioning view feature. If other users must be able to change data in the tables while you are changing their structure, you also use forward crossedition triggers. If the pre- and post-upgrade applications will be in ordinary use at the same time (hot rollover), you also use reverse crossedition triggers. Crossedition triggers are not a permanent part of the application—you drop them when all users are using the post-upgrade application. Topics: Editions are nonschema objects; as such, they do not have owners. Editions are created in a single namespace, and multiple editions can coexist in the database. The database must have at least one edition. Every newly created or upgraded Oracle Database starts with one edition named Topics: An editioned object is a schema object that has both an editionable type and an editions-enabled owner. (A schema object that has an editionable type but not an editions-enabled owner is potentially editioned.) An edition can have its own copy of an editioned object, in which case only the copy is visible to the edition. A noneditioned object is a schema object that has a noneditionable type. An edition cannot have its own copy of a noneditioned object. A noneditioned object is identical in, and visible to, all editions. An editioned object is uniquely identified by its You can display the You need not know the Topics: These schema objects types are editionable: All PL/SQL object types: All other schema object types are noneditionable. Table is an example of an noneditionable type. A schema object of an editionable type is editioned if its owner is editions-enabled; otherwise, it is potentially editioned. A schema object of a noneditionable type is always noneditioned, even if its owner is editions-enabled. A table is an example of an noneditioned object. Note: A noneditioned object cannot depend on an editioned object. For example: A function-based index cannot depend on an editioned function. A table cannot have a column of a user-defined data type (collection or ADT) whose owner is editions-enabled. A noneditioned subprogram cannot have a static reference to a subprogram whose owner is editions-enabled. For the reason for this rule, see "Actualizing Referenced Objects". An ADT cannot be both editioned and evolved. For information about type evolution, see Oracle Database Object-Relational Developer's Guide. An editioned object cannot be the starting or ending point of a The only editioned object that this rule affects is an editioned view. An editioned view can be either an ordinary view or an editioning view. To enable editions for a user, use the The Enabling editions is retroactive and irreversible. When a user is editions-enabled, every editionable-type object that the user has owned or will own is an editioned object. You cannot enable editions for a user who owns a potentially editioned object with noneditioned dependents unless you specify The preceding statement enables editions for the specified user and invalidates noneditioned dependents of editioned objects. Using Now Enable editions for user Recompile For example, if For information about the For information about the You cannot enable editions for a user who owns one or more evolved ADTs. Trying to do so causes error ORA-38820. If an ADT has no table dependents, you can use the See Also: Oracle Database SQL Language Reference for the syntax of the Oracle Database Reference for more information about the static data dictionary views To create an edition, use the SQL statement You must create the edition as the child of an existing edition. The parent of the first edition created with a (Example 19-1 and others use the preceding statement.) At Oracle Database 11g Release 2, an edition can have at most one child. The descendents of an edition are its child, its child's child, and so on. The ancestors of an edition are its parent, its parent's parent, and so on. The root edition has no parent, and a leaf edition has no child. See Also: Each database session uses exactly one edition at a time. Upon creation, a child edition inherits from its parent edition all editioned objects in the database that are visible in the parent edition. Each inherited object is visible in the child edition. An inherited object is copied on change or actualized; that is, when a user of the child edition references an inherited object in a DDL statement (other than Note: Example 19-1 creates a procedure named Example 19-1 Inherited and Actual Objects Create procedure in parent edition: Invoke procedure in parent edition: Result: Create child edition: Use child edition: For information about In child edition, invoke procedure: Child edition inherits procedure from parent edition. Child edition invokes inherited procedure. Result: Change procedure in child edition: Child changes only its own copy of procedure. Child's copy is an actual object. Invoke procedure: Child invokes its own copy, the actual procedure: Return to parent: Invoke procedure and see that it has not changed: Result: Topics: If a user of the child edition drops an inherited object, that object is no longer visible in the child edition, but it continues to be visible in the parent edition. Example 19-2 creates a procedure named Example 19-2 Dropping an Inherited Object Create procedure in edition Invoke procedure: Result: Create edition Use edition In In In Result: Return to parent: In parent, invoke procedure: Result: Because Its descendents do not inherit the procedure No object named In Example 19-3, Example 19-3 Creating an Object with the Name of a Dropped Inherited Object Return to For information about In Create edition Use edition In Result: In Result: When a referenced object is actualized in an edition, all of its dependents (direct and indirect) that are not yet actualized in that edition become actualized in that edition in an invalid state. Therefore, an editioned object cannot have dependents that cannot be actualized. In other words, a noneditioned object cannot depend on an editioned object (for examples, see "Rules for Editioned Objects"). When an invalid object is referenced, the database automatically validates it, which requires name resolution. The database looks for the object name first in the current edition, then in the parent edition, and so on. See Also: As the creator of the edition, you automatically have the To make an edition available to all users, either: Grant the For information about the Make the edition the database default edition: This has the side effect of granting the For information about the Each database session uses exactly one edition at a time. The edition that a database session is using at any one time is called its current edition. When a database session begins, its current edition is its session edition, which is the edition in whic h it begins. If you change the session edition, the current edition changes to the same thing. However, there are situations in which the current edition and session edition differ. Topics: When you connect to the database, you can specify your initial session edition. Your initial session edition can be any edition on which you have the How you specify your initial session edition at connection time depends on how you connect to the database—see the documentation for your interface. See Also: Oracle Database Administrator's Guide for information about setting the database default edition SQL*Plus User's Guide and Reference for information about connecting to the database with SQL*Plus Oracle Call Interface Programmer's Guide for information about connecting to the database with Oracle Call Interface (OCI) Oracle Database JDBC Developer's Guide for information about connecting to the database with JDBC As of Oracle Database 11g Release 2 (11.2.0.2), if you do not specify your session edition at connection time, then: If you use a database service to connect to the database, and an initial session edition was specified for that service, then the initial session edition for the service is your initial session edition. Otherwise, your initial session edition is the database default edition. As of Release 11.2.0.2, when you create or modify a database service, you can specify its initial session edition. To create or modify a database service, Oracle recommends using the Alternatively, you can create or modify a database service with the Note: See Also: Oracle Database Administrator's Guide for information about the Oracle Database Administrator's Guide for information about the Oracle Database PL/SQL Packages and Types Reference for information about the Oracle Database PL/SQL Packages and Types Reference for information about the After connecting to the database, you can change your session edition with the SQL statement These statements from Example 19-1 and Example 19-2 change the session edition (and current edition) first to Note: See Also: Oracle Database SQL Language Reference for more information about the Oracle Database PL/SQL Packages and Types Reference for more information about the This statement returns the name of the current edition: This statement returns the name of the session edition: See Also: The current edition might differ from the session edition in these situations: A crossedition trigger fires. For details, see "Crossedition Trigger Interaction with Editions". You run a statement by calling the While the statement is running, the current edition is the specified edition, but the session edition does not change. For information about the Example 19-4 creates a function that returns the names of the session edition and current edition. Then it creates a child edition, which invokes the function twice. The first time, the session edition and current edition are the same. The second time, they are not, because a different edition is passed as a parameter to the Example 19-4 Current Edition Differs from Session Edition Create function that returns the names of the session edition and current edition: Create child edition: Use child edition: Invoke function: Result: Invoke function again: Result: After making a new edition (an upgraded application) available to all users, you want to retire the old edition (the original application), so that no user except Note: For information about the To retire an edition, you must revoke the For information about the Note: To drop an edition, use the If a You drop an edition in these situations: You want to roll back the application upgrade. (Optional) You have retired the edition. You can drop an edition only if all of these statements are true: The edition is either the root edition or a leaf edition. If the edition is the root, it has no objects that its descendents inherit. (That is, each object inherited from the root edition was either actualized or dropped.) The edition is not in use (that is, it is not the current edition or session edition of a session). The edition is not the database default edition. To explicitly actualize an inherited object in the child edition: Make the child edition your session edition. For instructions, see "Changing Your Session Edition". Recompile the object, using the appropriate For example, this statement actualizes the procedure For information about the For information about the See Also: Oracle Database SQL Language Reference for information about the Oracle Database SQL Language Reference for information about the Oracle Database PL/SQL Language Reference for information about the Oracle Database PL/SQL Language Reference for information about the Oracle Database PL/SQL Language Reference for information about the Oracle Database PL/SQL Language Reference for information about the Oracle Database PL/SQL Language Reference for information about the The owner of an editioning view must be editions-enabled before the editioning view is created. On a noneditioning view, the only type of trigger that you can define is an An editioning view selects a subset of the columns from a single base table and, optionally, provides aliases for them. In providing aliases, the editioning view maps physical column names (used by the base table) to logical column names (used by the application). An editioning view is like an API for a table. There is no performance penalty for accessing a table through an editioning view, rather than directly. That is, if a SQL The static data dictionary view Topics: See Also: To create an editioning view, use the SQL statement If an editioning view is read-only, users of the unchanged application can see the data in the base table, but cannot change it. The base table has semi-availability. Semi-availability is acceptable for applications such as online dictionaries, which users read but do not change. Make the editioning view read-only if you do not define crossedition triggers on the base table. If an editioning view is read-write, users of the unchanged application can both see and change the data in the base table. The base table has maximum availability. Maximum availability is required for applications such as online stores, where users submit purchase orders. If you define crossedition triggers on the base table, make the editioning view read-write. Because an editioning view must do no more than select a subset of the columns from the base table and provide aliases for them, the See Also: An editioning view defined on a partitioned table can have a partition-extended name, with partition and subpartition names that refer to the partitions and subpartitions of the base table. The data manipulation language (DML) statements that support partition-extended table names also support partition-extended editioning view names. These statements are: See Also: To change an existing editioning view from read-only to read-write, use the SQL statement See Also: To replace an editioning view, use the SQL statement You can replace an editioning view only with another editioning view. Any triggers defined on the replaced editioning view are retained. If you drop or rename the base table on which an editioning view is defined, the editioning view is not dropped, but the editioning view and its dependents become invalid. However, any triggers defined on the editioning view remain. If your upgraded application requires new indexes or constraints, you must add them to the base table. You cannot add them to the editioning view. If the new indexes might negatively impact the old edition (the original application), make them invisible. In the crossedition triggers that must use the new indexes, specify them in When all users are using only the upgraded application: If the new indexes were used only by the crossedition triggers, drop them. If the new indexes are helpful in the upgraded application, make them visible. See Also: "Guidelines for Managing Indexes" for information about when to use indexes Oracle Database SQL Language Reference for information about SQL optimizer index hints are specified in terms of the logical names of the columns participating in the index. Any SQL optimizer index hints specified on an editioning view using logical column names must be mapped to an index on the corresponding physical column in the base table. The most important difference between crossedition triggers and noncrossedition triggers is how they interact with editions. A crossedition trigger is visible only in the edition in which it is actual, never in a descendent edition. Forward crossedition triggers move data from columns used by the old edition to columns used by the new edition; reverse crossedition triggers do the reverse. Other important differences are: Crossedition triggers can be ordered with trigge rs defined on other tables, while noncrossedition triggers can be ordered only with other triggers defined on the same table. Crossedition triggers are temporary—you drop them after you have made the restructured tables available to all users. Topics: The DML changes that you make to the table in the post-upgrade edition are written only to new columns or new tables, never to columns that users of pre-upgrade (ancestor) editions might be reading or writing. However, if the user of an ancestor edition changes the table data, the editioning view that you see must accurately reflect these changes. This is accomplished with forward crossedition triggers. A forward crossedition trigger defines a transform, which is a rule for transforming an old row to one or more new rows. An old row is a row of data in the pre-upgrade representation. A new row is a row of data in the post-upgrade representation. The name of the trigger refers to the trigger itself and to the transform that the trigger defines. If the pre- and post-upgrade editions will be in ordinary use at the same time (hot rollover), use reverse crossedition triggers to ensure that when users of the post-upgrade edition make changes to the table data, the changes are accurately reflected in the pre-upgrade editions. The most important difference between crossedition triggers and noncrossedition triggers is how they interact with editions. In this topic, the current edition is the edition in which the triggering DML statement runs. The current edition might differ from the session edition (for details, see "When the Current Edition Might Differ from the Session Edition"). Editions inherit noncrossedition triggers in the same way that they inherit other editioned objects (see "Inherited and Actual Objects"). Editions do not inherit crossedition triggers. A crossedition trigger might fire in response to a DML statement that another edition runs, but its name is visible only in the edition in which it was created. Therefore, an edition can reuse the name of a crossedition trigger created in an ancestor edition. Reusing the name of a crossedition trigger does not change the conditions under which the older trigger fires. Crossedition triggers that appear in static data dictionary views are actual objects in the current edition. What kind of triggers can fire depends on the category of the triggering DML statement. The categories are: Note: Forward crossedition trigger SQL is SQL that is executed in either of these ways: Directly from the body of a forward crossedition trigger This category includes SQL in an invoked subprogram only if the subprogram is local to the forward crossedition trigger. By invoking the The only valid non- If a forward crossedition trigger invokes a subprogram in another compilation unit, the SQL in the subprogram is forward crossedition trigger SQL only if it is invoked by the Forward crossedition trigger SQL can fire only triggers that satisfy all of these conditions: They are forward crossedition triggers. They were created either in the current edition or in a descendent of the current edition. They explicitly follow the running forward crossedition trigger. Reverse crossedition trigger SQL is SQL that is executed directly from the body of a reverse crossedition trigger. This category includes SQL in an invoked subprogram only if the subprogram is local to the reverse crossedition trigger. Reverse crossedition trigger SQL can fire only triggers that satisfy all of these conditions: They are reverse crossedition triggers. They were created either in the current edition or in an ancestor of the current edition. They explicitly precede the running reverse crossedition trigger. Application SQL is all SQL except crossedition trigger SQL, including these DML statements: Dynamic SQL DML statements coded with the DML statements executed by Java stored procedures and external procedures (even when these procedures are invoked by Application SQL fires both noncrossedition and crossedition triggers, according to these rules: For a trigger to fire in response to a specific DML statement, the trigger must: Be the right kind (see "What Kind of Triggers Can Fire") Satisfy the selection criteria (for example, the type of DML statement and the Be enabled For the triggers that meet these requirements, firing order depends on: See Also: When triggers A and B are to be fired at the same timing point, A fires before B fires if either of these is true: A explicitly precedes B. B explicitly follows A. This rule is independent of conditions such as: Whether the triggers are enabled or disabled Whether the columns specified in the Whether the Whether the triggers are associated with the same kinds of DML statements ( Whether the triggers have overlapping timing points The firing order of triggers that do not explicitly follow or precede each other is unpredictable. For each timing point associated with a triggering DML statement, eligible triggers fire in this order. In categories 1 through 3, Noncrossedition triggers Forward crossedition triggers created in the current edition Forward crossedition triggers created in descendents of the current edition, in the order that the descendents were created (child, grandchild, and so on) Reverse crossedition triggers created in the current edition Reverse crossedition triggers created in the ancestors of the current edition, in the reverse order that the ancestors were created (parent, grandparent, and so on) A crossedition trigger runs using the edition in which it was created. Any code that the crossedition trigger calls (including package references, PL/SQL subprogram calls, and SQL statements) also runs in the edition in which the crossedition trigger was created. If a PL/SQL package is actual in multiple editions, then the package variables and other state are private in each edition, even within a single session. Because each crossedition trigger and the code that it calls run using the edition in which the crossedition trigger was created, the same session can instantiate two or more versions of the package, with the same name. To create a crossedition trigger, you must be editions-enabled (for information about enabling editions for a user, see "Enabling Editions for a User"). Create a crossedition trigger with the SQL statement A crossedition trigger must be defined on a table, not a view. A crossedition trigger must be a DML trigger (simple or compound). The DML statement in a crossedition trigger body can be either a static SQL statement (described in Oracle Database PL/SQL Language Reference) or a native dynamic SQL statement (described in Oracle Database PL/SQL Language Reference). A crossedition trigger is forward unless you specify The The The triggers specified in the Like a noncrossedition trigger, a crossedition trigger is created in the enabled state unless you specify Tip: The operation in a crossedition trigger body must be idempotent (that is, performing the operation multiple times is redundant; it does not change the result). See Also: The operation in the body of a forward crossedition trigger must be idempotent, because it is impossible to predict: The context in which the body will first run for an old row. The possibilities are: When a user of an ancestor edition runs a DML statement that fires the trigger (a serendipitous change) When you apply the transform that the trigger defines For information about applying transforms, see "Transforming Data from Pre- to Post-Upgrade Representation". How many times the body will run for each old row. Topics: If a forward crossedition trigger populates a new table (rather than new columns of a table), its body must handle data transformation collisions. For example, suppose that a column of the new table has a If your collision-handling strategy depends on why the trigger is running, you can determine the reason with the function To ignore collisions and insert the rows that do not collide with existing rows, put the If you do not want to ignore such collisions, but want to know where they occur so that you can handle them, put the Note: Example 19-5 creates a crossedition trigger that uses the Example 19-5 Crossedition Trigger that Handles Data Transformation Collisions See Also: Oracle Database SQL Language Reference for more information about Oracle Database SQL Language Reference for more information about Oracle Database SQL Language Reference for general information about hints If the body of a forward crossedition trigger includes explicit SQL statements that change tables other than the one on which the trigger is defined, and if the rows of those tables do not have a one-to-one correspondence with the rows of the table on which the trigger is defined, then the body code must implement a locking mechanism that correctly handles these situations: Two or more users of ancestor editions simultaneously issue DML statements for the table on which the trigger is defined. At least one user of an ancestor edition issues a DML statement for the table on which the trigger is defined. After redefining the database objects that comprise the application that you are upgrading (in the new edition), you must transform the application data from its pre-upgrade representation (in the old edition) to its post-upgrade representation (in the new edition). The rules for this transformation are called transforms, and they are defined by forward crossedition triggers. (For general information about forward crossedition triggers, see "Forward Crossedition Triggers".) Some old rows might have been transformed to new rows by serendipitous changes; that is, by changes that users of the pre-upgrade application made, which fired forward crossedition triggers. However, any rows that were not transformed by serendipitous changes are still in their pre-upgrade representation. To ensure that all old rows are transformed to new rows, you must apply the transforms that you defined on the tables that store the application data. There are two ways to apply a transform: Fire the trigger that defines the transform on every row of the table, one row at a time. Instead of firing the trigger, run a SQL statement that does what the trigger would do, but faster, and then fire any triggers that follow that trigger. This second way is recommended if you have replaced an entire table or created a new table. For either way of applying the transform, invoke either the Group sets of rows in the table into smaller chunks. Apply the desired The advantages are: You lock only one set of rows at a time, for a relatively short time, instead of locking the entire table. You do not lose work that has been done if something fails before the entire operation finishes. For both the For To fire the trigger on every row of the table, one row at a time: For the value of For To run a SQL statement that does what the trigger would do, and then fire any triggers that follow that trigger: For the value of For See Also: Oracle Database PL/SQL Packages and Types Reference for more information about the Oracle Database PL/SQL Packages and Types Reference for more information about the To prevent lost updates when applying a transform, use this procedure: Enable crossedition triggers. Wait until pending changes to the affected tables are either committed or rolled back. Use the procedure Apply the transform. Note: A race condition can now occur when both Session One and Session Two will change the same row (row n). Chance determines which session reaches row n first. Both updates succeed, even if the session that reaches row n second must wait until the session that reached it first commits its change and releases its lock. The problem occurs when Session Two wins the race. Because its SQL statement was compiled after the trigger was enabled, the program that implements the statement also implements the trigger action; therefore, the intended post-upgrade column values are set for row n. Now Session One reaches row n, and because its SQL statement was compiled before the trigger was enabled, the program that implements the statement does not implement the trigger action. Therefore, the values that Session Two set in the post-upgrade columns do not change—they reflect the values that the source columns had before Session One updated row n. That is, the intended side-effect of Session One's update is lost. To drop a crossedition trigger, use the You drop crossedition triggers in these situations: You are rolling back the application upgrade (dropping the post-upgrade edition). Before dropping the post-upgrade edition, you must disable or drop any constraints on the new columns. You have finished the application upgrade and made the post-upgrade edition available to all users. When all sessions are using the post-upgrade edition, you can drop the forward crossedition triggers. However, before dropping the reverse crossedition triggers, you must disable or drop any constraints on the old columns. To disable or drop constraints, use the Table 19-1 and Table 19-2 describe the static data dictionary views that display information about editions and editioning views, respectively. For more information about a view in either table, see Oracle Database Reference. The static data dictionary views that display information about triggers are described in Oracle Database Reference. Crossedition triggers that appear in static data dictionary views are actual objects in the session edition. Child cursors cannot be shared if the set of crossedition triggers that might run differs. The dynamic performance views Table 19-1 *_ Dictionary Views with Edition Information Note: A reference to the object (either during compilation or execution) An invocation of An invocation of any Table 19-2 *_ Dictionary Views with Editioning View Information Describes every view in the database that is visible (actual or inherited) in the session edition, including editioning views. Describes every editioning view in the database that is visible (actual or inherited) in the session edition. Useful for showing relationships between editioning views and their base tables. Join with Describes every actual object in every editioning view in the database, in every edition. Describes the columns of every editioning view in the database that is visible (actual or inherited) in the session edition. Useful for showing relationships between the columns of editioning views and the table columns to which they map. Join with Describes the columns of every editioning view in the database, in every edition. Each row of The row of To use edition-based redefinition to upgrade your application online, you must first ready your application: Editions-enable the appropriate users. For instructions, see "Enabling Editions for a User". The reason for this step is that only editions-enabled users can own editioning views, which you create in the next step. Prepare your application to use editioning views. For instructions, see "Preparing Your Application to Use Editioning Views". With the editioning views in place, you can use edition-based redefinition to upgrade your application online as often as necessary. For each upgrade: If the type of every object that you will redefine is editionable (tables are not editionable), use the "Procedure for Edition-Based Redefinition Using Only Editions". If you will change the structure of one or more tables, and while you are doing so, other users do not need to be able to change data in those tables, use the "Procedure for Edition-Based Redefinition Using Editioning Views". If you will change the structure of one or more tables, and while you are doing so, other users must be able to change data in those tables, use the "Procedure for Edition-Based Redefinition Using Crossedition Triggers". Topics: Procedure for Edition-Based Redefinition Using Only Editions Procedure for Edition-Based Redefinition Using Editioning Views Procedure for Edition-Based Redefinition Using Crossedition Triggers Example: Using Edition-Based Redefinition to Upgrade an Application An application that uses one or more tables must cover each table with an editioning view. An editioning view covers a table when all of these statements are true: Every ordinary object in the application references the table only through the editioning view. (An ordinary object is any object except an editioning view or crossedition trigger. Editioning views and crossedition triggers must reference tables.) Application users are granted object privileges only on the editioning view, not on the table. Oracle Virtual Private Database (VPD) policies are attached only to the editioning view, not to the table. (Regular auditing and fine-grained auditing (FGA) policies are attached only to the table.) When the editioning view is actualized, a copy of the VPD policy is attached to the actualized editioning view. (A policy is uniquely identified by its name and the object to which is it attached.) If the policy function is also actualized, the copy of the policy uses the actualized policy function; otherwise, it uses the original policy function. The static data dictionary views See Also: Oracle Database Security Guide for information about VPD, including that static data dictionary views that show information about VPD policies Oracle Database Reference for information about If an existing application does not use editioning views, prepare it to use them by following this procedure for each table that it uses: Give the table a new name (so that you can give its current name to its editioning view). Oracle recommends choosing a new name that is related to the original name and reflects the change history. For example, if the original table name is (Optional) Give each column of the table a new name. Again, Oracle recommends choosing new names that are related to the original names and reflect the change history. For example, Any triggers that depend on renamed columns are now invalid. For details, see the entry for Create the editioning view, giving it the original name of the table. For instructions, see "Creating an Editioning View". Because the editioning view has the name that the table had, objects that reference that name now reference the editioning view. If triggers are defined on the table, drop them, and rerun the code that created them. Now the triggers that were defined on the table are defined on the editioning view. If VPD policies are attached to the table, drop the policies and policy functions and rerun the code that created them. Now the VPD policies that were attached to the table are attached to the editioning view. Revoke all object privileges on the table from all application users. To see which application users have which object privileges on the table, use this query: For every privilege revoked in step 6, grant the same privilege on the editioning view. Enable editions for users who own private synonyms that refer to the table (for instructions, see "Enabling Editions for a User") and notify those users that they must re-create those synonyms. Note: Use this procedure only if the type of every object that you will redefine is editionable (as defined in "Editionable and Noneditionable Schema Object Types"). Table is not an editionable type. Create a new edition. For instructions, see "Creating an Edition". Make the new edition your session edition. For instructions, see "Changing Your Session Edition". Make the necessary changes to the editioned objects of the application. Ensure that all objects are valid. Query the static data dictionary Check that the changes work as intended. If so, go to step 6. If not, either make further changes (return to step 3) or roll back the application upgrade (for instructions, see "Rolling Back the Application Upgrade"). Make the new edition (the upgraded application) available to all users. For instructions, see "Making an Edition Available to All Users". Retire the old edition (the original application), so that all users except For instructions, see "Retiring an Edition". Example 19-6 shows how to use the preceding procedure to change a very simple PL/SQL procedure. Example 19-6 Edition-Based Redefinition of Very Simple Procedure Create PL/SQL procedure for this example: Invoke PL/SQL procedure: Result: Do edition-based redefinition of procedure: Create new edition: Result: Make new edition your session edition: Result: Change procedure: Result: Check that change works as intended: Result: Make new edition available to all users (requires system privileges): Retire old edition (requires system privileges): List grantees: Result: Revoke use on old edition from all grantees: Use this procedure only if you will change the structure of one or more tables, and while you are doing so, other users do not need to be able to change data in those tables. Create a new edition. For instructions, see "Creating an Edition". Make the new edition your session edition. For instructions, see "Changing Your Session Edition". In the new edition, if the editioning views are read-only, make them read-write. For instructions, see "Changing the 'Write-ability' of an Editioning View". In every edition except the new edition, make the editioning views read-only. Make the necessary changes to the objects of the application. Ensure that all objects are valid. Query the static data dictionary Check that the changes work as intended. If so, go to step 8. If not, either make further changes (return to step 5) or roll back the application upgrade (for instructions, see "Rolling Back the Application Upgrade"). Make the upgraded application available to all users. For instructions, see "Making an Edition Available to All Users". Retire the old edition (the original application), so that all users except For instructions, see "Retiring an Edition". Use this procedure only if you will change the structure of one or more tables, and while you are doing so, other users must be able to change data in those tables. Create a new edition. For instructions, see "Creating an Edition". Make the new edition your session edition. For instructions, see "Changing Your Session Edition". Make the permanent changes to the objects of the application. For example, add new columns to the tables and create any new permanent subprograms. Objects that depend on objects that you changed might now be invalid. For more information, see Table 18-2. Ensure that all objects are valid. Query the static data dictionary Create the temporary objects—the crossedition triggers (in the disabled state) and any subprograms that they need. For instructions, see "Creating a Crossedition Trigger". You need reverse crossedition triggers only if you do step 10, which is optional. When the crossedition triggers compile successfully, enable them. Use the Wait until pending changes are either committed or rolled back. Use the procedure Apply the transforms. For instructions, see "Transforming Data from Pre- to Post-Upgrade Representation". Note: Check that the changes work as intended. If so, go to step 10. If not, either make further changes (return to step 3) or roll back the application upgrade (for instructions, see "Rolling Back the Application Upgrade"). (Optional) Grant the For instructions, see "Making an Edition Available to Some Users". Make the upgraded application available to all users. For instructions, see "Making an Edition Available to All Users". Disable or drop the constraints and then drop the crossedition triggers. For instructions, see P"Dropping the Crossedition Triggers". Retire the old edition (the original application), so that all users except For instructions, see "Retiring an Edition". To roll back the application upgrade: Change your session edition to something other than the new edition that you created for the upgrade. For instructions, see "Changing Your Session Edition". Drop the new edition that you created for the upgrade. For instructions, see "Dropping an Edition". If you created new table columns during the upgrade, reclaim the space that they occupy (for instructions, see "Reclaiming Space Occupied by Unused Table Columns"). If you roll back an upgrade for which you created new table columns, To reclaim the space that unused columns occupy: Set the values of the unused columns to To avoid locking out other users while doing this operation, use the Set the unused columns to Use the Shrink the table. Use the This example uses an edition, an editioning view, a forward crossedition trigger, and a reverse crossedition trigger. Topics: Note: The existing application—the application to be upgraded—consists of a single table on which a trigger is defined. The application was created as in Example 19-7. Example 19-7 Creating the Existing Application Create table: Populate table (not shown). Prepare to create trigger on table: Create trigger: Example 19-8 shows how the table Example 19-8 Viewing Data in Existing Table Query: Result: Suppose that you must redefine You need all features of edition-based redefinition: the edition, which is always needed; the editioning view, because you are redefining a table; and crossedition triggers, because other users must be able to change data in the table while you are redefining it. Example 19-9 shows how to create the editioning view from which other users will access the table Example 19-9 Creating an Editioning View for the Existing Table Give table a new name (so that you can give its current name to editioning view): (Optional) Give columns of table new names: Create editioning view: Move trigger Example 19-10 shows how to create an edition in which to upgrade the "Existing Application", make the new edition the session edition, and check that the new edition really is the session edition. Example 19-10 Creating Edition in Which to Upgrade the Application Create new edition: Make new edition your session edition: Check session edition: Result: In the Example 19-11 Changing the Table and Replacing the Editioning View Add new columns to physical table: (This is nonblocking DDL.) Recompile invalidated trigger: Replace editioning view so that it selects replacement columns with their desired logical names: In the Example 19-12 Creating and Enabling the Crossedition Triggers Create first procedure that forward crossedition trigger uses: Create second procedure that forward crossedition trigger uses: Create forward crossedition trigger in disabled state: Enable forward crossedition trigger: Create reverse crossedition trigger in disabled state: Enable reverse crossedition trigger: Wait until pending changes are either committed or rolled back: For information about the In the Example 19-13 Applying the Transforms In the Example 19-14 Viewing Data in Changed Table Format columns for readability: Query: Result: If the change worked as intended, you can now follow steps 10 through 13 of the "Procedure for Edition-Based Redefinition Using Crossedition Triggers". Continuous Query Notification (CQN) allows an application to register queries with the database for either object change notification (the default) or query result change notification. An object referenced by a registered query is a registered object. If a query is registered for object change notification (OCN), the database notifies the application whenever a transaction changes an object that the query references and commits, regardless of whether the query result changed. If a query is registered for query result change notification (QRCN), the database notifies the application whenever a transaction changes the result of the query and commits. A CQN registration associates a list of one or more queries with a notification type (OCN or QRCN) and a notification handler. To create a CQN registration, you can use either the PL/SQL interface or Oracle Call Interface (OCI). If you use the PL/SQL interface, the notification handler is a server-side PL/SQL stored procedure; if you use OCI, the notification handler is a client-side C callback procedure. This chapter explains general CQN concepts and explains how to use the PL/SQL CQN interface. For information about using OCI for CQN, see Oracle Call Interface Programmer's Guide. Topics: Note: If an application registers a query for object change notification (OCN), the database sends the application an OCN whenever a transaction changes an object associated with the query and commits, regardless of whether the result of the query changed. For example, if an application registers the query in Example 11-1 for OCN, and a user commits a transaction that changes the Note: For information about the For information about AUM, see Oracle Database Administrator's Guide. If an application registers a query for query result change notification (QRCN), the database sends the application a QRCN whenever a transaction changes the result of the query and commits. For example, if an application registers the query in Example 11-1 for QRCN, the database sends the application a QRCN only if the query result set changes; that is, if one of these data manipulation language (DML) statements commits: An An An An The default notification type is OCN. For QRCN, specify With QRCN, you have a choice of guaranteed mode (the default) or best-effort mode. Topics: In guaranteed mode, there are no false positives: the database sends the application a QRCN only when the query result set is guaranteed to have changed. For example, suppose that an application registered the query in Example 11-1 for QRCN, that employee 201 is in department 10, and that these statements are executed: Each For guaranteed mode, specify Some queries are too complex for QRCN in guaranteed mode. For the characteristics of queries that can be registered in guaranteed mode, see "Queries that Can Be Registered for QRCN in Guaranteed Mode". Some queries that are too complex for guaranteed mode can be registered for QRCN in best-effort mode, in which CQN creates and registers simpler versions of them. For example, the query in Example 11-2 is too complex for QRCN in guaranteed mode because it contains the aggregate function Example 11-2 Query Too Complex for QRCN in Guaranteed Mode In best-effort mode, CQN registers this simpler version of the query in Example 11-2: Whenever the result of the original query changes, the result of its simpler version also changes; therefore, no notifications are lost from the simplification. However, the simplification might cause false positives, because the result of the simpler version can change when the result of the original query does not. In best-effort mode, the database: Minimizes the OLTP response overhead that is from notification-related processing, as follows: For a single-table query, the database determines whether the query result has changed by which columns changed and which predicates the changed rows satisfied. For a multiple-table query (a join), the database uses the primary-key/foreign-key constraint relationships between the tables to determine whether the query result has changed. Sends the application a QRCN whenever a DML statement changes the query result set, even if a subsequent DML statement nullifies the change made by the first DML statement. The overhead minimization of best-effort mode infrequently causes false positives, even for queries that CQN does not simplify. For example, consider the query in Example 11-1 and the transaction in "Guaranteed Mode". In best-effort mode, CQN does not simplify the query, but the transaction generates a false positive. Some types of queries are so simplified that invalidations are generated at object level; that is, whenever any object referenced in those queries changes. Examples of such queries are those that use unsupported column types or include subqueries. The solution to this problem is to rewrite the original queries. For example, the query in Example 11-3 is too complex for QRCN in guaranteed mode because it includes a subquery. Example 11-3 Query Whose Simplified Version Invalidates Objects In best-effort mode, CQN simplifies the query in Example 11-3 to this: The simplified query can cause objects to be invalidated. However, if you rewrite the original query as follows, you can register it in either guaranteed mode or best-effort mode: Queries that can be registered only in best-effort mode are described in "Queries that Can Be Registered for QRCN Only in Best-Effort Mode". The default for QRCN mode is guaranteed mode. For best-effort mode, specify These events generate notifications: When the notification type is OCN, any DML transaction that changes one or more registered objects generates one notification for each object when it commits. When the notification type is QRCN, any DML transaction that changes the result of one or more registered queries generates a notification when it commits. The notification includes the query IDs of the queries whose results changed. For either notification type, the notification includes: Name of each changed table Operation type ( For both OCN and QRCN, these data definition language (DDL) statements, when committed, generate notifications: Note: Any OCN registrations of queries on the dropped table become disassociated from that table (which no longer exists), but the registrations themselves continue to exist. If any of these registrations are associated with objects other than the dropped table, committed changes to those other objects continue to generate notifications. Registrations associated only with the dropped table also continue to exist, and their creator can add queries (and their referenced objects) to them. An OCN registration is based on the version and definition of an object at the time the query was registered. If an object is dropped, registrations on that object are disassociated from it forever. If an object is created with the same name, and in the same schema, as the dropped object, the created object is not associated with OCN registrations that were associated with the dropped object. When the notification type is QRCN: The notification includes: Query IDs of the queries whose results have changed Name of the modified table Type of DDL operation Some DDL operations that invalidate registered queries can cause those queries to be deregistered. For example, suppose that this query is registered for QRCN: Suppose that This DDL statement, when committed, invalidates the query and causes it to be removed from the registration: For both OCN and QRCN, deregistration—removal of a registration from the database—generates a notification. The reasons that the database removes a registration are: Timeout If If Loss of privileges If privileges are lost on an object associated with a registered query, and the notification type is OCN, the database purges the registration. (When the notification type is QRCN, the database removes that query from the registration, but does not purge the registration.) For privileges needed to register queries, see "Prerequisites for Creating CQN Registrations". A notification is not generated when a client application performs an explicit deregistration. The global events In an Oracle RAC environment, these events generate notifications: The preceding global events are constants defined in the See Also: A notification contains some or all of this information: Type of event, which is one of: Startup Object change Query result change Deregistration Shutdown Registration ID of affected registration Names of changed objects If If the notification type is QRCN: Query IDs of queries whose results changed If notification resulted from a DML or DDL statement: Array of names of modified tables Operation type (for example, A notification does not contain the changed data itself. For example, the notification does not say that a monthly salary increased from 5000 to 6000. To obtain more recent values for the changed objects or rows or query results, the application must query the database. Good candidates for CQN are applications that cache the result sets of queries on infrequently changed objects in the middle tier, to avoid network round trips to the database. These applications can use CQN to register the queries to be cached. When such an application receives a notification, it can refresh its cache by rerunning the registered queries. An example of such an application is a web forum. Because its users need not view content as soon as it is inserted into the database, this application can cache information in the middle tier and have CQN tell it when it when to refresh the cache. Figure 11-1 illustrates a typical scenario in which the database serves data that is cached in the middle tier and then accessed over the Internet. Applications in the middle tier require rapid access to cached copies of database objects while keeping the cache as current as possible in relation to the database. Cached data becomes obsolete when a transaction modifies the data and commits, thereby putting the application at risk of accessing incorrect results. If the application uses CQN, the database can publish a notification when a change occurs to registered objects with details on what changed. In response to the notification, the application can refresh cached data by fetching it from the back-end database. Figure 11-2 illustrates the process by which middle-tier Web clients receive and process notifications. Figure 11-2 Basic Process of Continuous Query Notification (CQN) Explanation of steps in Figure 11-2 (if registrations are created using PL/SQL and that the application has cached the result set of a query on The developer uses PL/SQL to create a CQN registration for the query, which consists of creating a stored PL/SQL procedure to process notifications and then using the PL/SQL CQN interface to create a registration for the query, specifying the PL/SQL procedure as the notification handler. The database populates the registration information in the data dictionary. A user updates a row in the The database adds a message that describes the change to an internal queue. The database notifies a The Inside the server-side PL/SQL procedure, the developer can implement logic to notify the middle-tier client application of the changes to the registered objects. For example, it notifies the application of the The client application in the middle tier queries the back-end database to retrieve the data in the changed row. The client application updates the cache with the data. A CQN registration associates a list of one or more queries with a notification type and a notification handler. The notification type is either OCN or QRCN. For information about these types, see "Object Change Notification (OCN)" and "Query Result Change Notification (QRCN)". To create a CQN registration, you can use either the PL/SQL interface or OCI. If you use the PL/SQL interface, the notification handler is a server-side PL/SQL stored procedure; if you use OCI, the notification handler is a client-side C callback procedure. (This topic explains only the PL/SQL interface. For information about OCI, see Oracle Call Interface Programmer's Guide.) Once created, a registration is stored in the database. In an Oracle RAC environment, it is visible to all database instances. Transactions that change the query results in any database instance generate notifications. By default, a registration survives until the application that created it explicitly deregisters it or until the database implicitly purges it (from loss of privileges, for example). Topics: Queries that Can Be Registered for Object Change Notification (OCN) Queries that Can Be Registered for Query Result Change Notification (QRCN) The PL/SQL CQN registration interface is implemented with the For step-by-step instructions, see "Using PL/SQL to Register Queries for CQN". See Also: You can change the CQN registration defaults with the options summarized in Table 11-1. Table 11-1 Continuous Query Notification Registration Options Notification Type Specifies QRCN (the default is OCN). QRCN ModeFoot 1 Specifies best-effort mode (the default is guaranteed mode). Includes the value of the Operations FilterFoot 2 Publishes the notification only if the operation type matches the specified filter condition. Transaction LagFootref 2 Deprecated. Use Notification Grouping instead. Notification Grouping Specifies how notifications are grouped. Reliable Stores notifications in a persistent database queue (instead of in shared memory, the default). Purge on Notify Purges the registration after the first notification. Timeout Purges the registration after a specified time interval. Footnote 1 Applies only when notification type is QRCN. Footnote 2 Applies only when notification type is OCN. Topics: The notification types are OCN (described in "Object Change Notification (OCN)") and QRCN (described in "Query Result Change Notification (QRCN)"). The QRCN mode option applies only when the notification type is QRCN. Instructions for setting the notification type to QRCN are in "Notification Type Option". The QRCN modes are guaranteed (described in "Guaranteed Mode") and best-effort (described in "Best-Effort Mode"). The default is guaranteed mode. For best-effort mode, specify The Note: From the If the server does not have enough memory for the Total shared memory consumption from Too many rows were changed in a single registered object within a transaction (the upper limit is approximately 80). Total length of the logical You specified the Notification Grouping option Because a The Operations Filter option applies only when the notification type is OCN. The Operations Filter option enables you to specify the types of operations that generate notifications. The default is all operations. To specify that only some operations generate notifications, use the To specify multiple operations, use bitwise See Also: The Transaction Lag option applies only when the notification type is OCN. Note: The Transaction Lag option specifies the number of transactions by which the client application can lag behind the database. If the number is 0, every transaction that changes a registered object results in a notification. If the number is 5, every fifth transaction that changes a registered object results in a notification. The database tracks intervening changes at object granularity and includes them in the notification, so that the client does not lose them. A transaction lag greater than 0 is useful only if an application implements flow-of-control notifications. Ensure that the application generates notifications frequently enough to satisfy the lag, so that they are not deferred indefinitely. If you specify By default, notifications are generated immediately after the event that causes them. Notification Grouping options, which are attributes of the Note: The single notification does not include Note: By default, a CQN registration is stored in shared memory. To store it in a persistent database queue instead—that is, to generate reliable notifications—specify The advantage of reliable notifications is that if the database fails after generating them, it can still deliver them after it restarts. In an Oracle RAC environment, a surviving database instance can deliver them. The disadvantage of reliable notifications is that they have higher CPU and I/O costs than default notifications do. By default, a CQN registration survives until the application that created it explicitly deregisters it or until the database implicitly purges it (from loss of privileges, for example). To purge the registration after it generates its first notification, specify To purge the registration after n seconds, specify n in the You can use the Purge-on-Notify and Timeout options together. These are prerequisites for creating CQN registrations: You must have these privileges: Loss of privileges on an object associated with a registered query generates a notification—see "Deregistration". You must be connected as a non-SYS user. You must not be in the middle of an uncommitted transaction. The (This is also a prerequisite for receiving notifications.) Note: Most queries can be registered for OCN, including those executed as part of stored procedures and Queries that cannot be registered for OCN are: Queries on fixed tables or fixed views Queries on user views Queries that contain database links (dblinks) Queries over materialized views Note: Some queries can be registered for QRCN in guaranteed mode, some can be registered for QRCN only in best-effort mode, and some cannot be registered for QRCN in either mode. (For information about modes, see "Guaranteed Mode" and "Best-Effort Mode".) Topics: To be registered for QRCN in guaranteed mode, a query must conform to these rules: Every column that it references is either a Arithmetic operators in column expressions are limited to these binary operators, and their operands are columns with numeric data types: Comparison operators in the predicate are limited to: Boolean operators in the predicate are limited to The query contains no aggregate functions (such as For a list of SQL aggregate functions, see Oracle Database SQL Language Reference. Guaranteed mode supports most queries on single tables and some inner equijoins, such as: Notes: Sometimes the query optimizer uses an execution plan that makes a query incompatible for guaranteed mode (for example, Queries that can be registered in guaranteed mode can also be registered in best-effort mode, but results might differ, because best-effort mode can cause false positives even for queries that CQN does not simplify. For details, see "Best-Effort Mode". A query that does any of the following can be registered for QRCN only in best-effort mode, and its simplified version generates notifications at object granularity: Refers to columns that have encryption enabled Has more than 10 items of the same type in the Has expressions that include any of these: String functions (such as Arithmetic functions (such as For a list of SQL functions, see Oracle Database SQL Language Reference. Pattern-matching conditions Has disjunctions involving predicates defined on columns from different tables. For example: Has user rowid access. For example: Has any join other than an inner join Has an execution plan that involves any of these: Bitmap join, domain, or function-based indexes (Either in the query itself, or as the result of an (Either in the query itself, or as the result of a Partitioned index-organized table (IOT) with overflow segment Clustered objects Parallel execution A query that refers to any of the following cannot be registered for QRCN in either guaranteed or best-effort mode: Views Tables that are fixed, remote, or have Virtual Private Database (VPD) policies enabled Synonyms Calls to user-defined PL/SQL subprograms Operators not listed in "Queries that Can Be Registered for QRCN in Guaranteed Mode" The aggregate function (Other aggregate functions are allowed in best-effort mode, but not in guaranteed mode.) Application contexts; for example: Also, a query that the query optimizer has rewritten using a materialized view cannot be registered for QRCN. For information about the query optimizer, see Oracle Database Performance Tuning Guide. To use PL/SQL to create a CQN registration, follow these steps: Create a stored PL/SQL procedure to serve as the notification handler. Create a In your client application, use the Run the queries to register. (Do not run DML or DDL operations.) Close the registration block, using the Topics: See Also: The PL/SQL stored procedure that you create to serve as the notification handler must have this signature: In the preceding signature, The notification descriptor is a The Note: An object of type Table 11-2 describes the attributes of Table 11-2 Attributes of CQ_NOTIFICATION$_REG_INFO Specifies the name of the PL/SQL procedure to be executed when a notification is generated (a notification handler). You must specify the name in the form Specifies one or more quality-of-service flags, which are constants in the To specify multiple quality-of-service flags, use bitwise Specifies the timeout period for registrations. If set to a nonzero value, it specifies the time in seconds after which the database purges the registration. If Can be combined with the Applies only to OCN (described in "Object Change Notification (OCN)"). Has no effect if you specify the Filters messages based on types of SQL statement. You can specify these constants in the You can specify a combination of operations with a bitwise Deprecated. To implement flow-of-control notifications, use the Applies only to OCN (described in "Object Change Notification (OCN)"). Has no effect if you specify the Specifies the number of transactions or database changes by which the client can lag behind the database. If 0, then the client receives an invalidation message as soon as it is generated. If 5, then every fifth transaction that changes a registered object results in a notification. The database tracks intervening changes at an object granularity and bundles the changes along with the notification. Thus, the client does not lose intervening changes. Most applications that must be notified of changes to an object on transaction commit without further deferral are expected to chose 0 transaction lag. A nonzero transaction lag is useful only if an application implements flow control on notifications. When using nonzero transaction lag, it is recommended that the application workload has the property that notifications are generated at a reasonable frequency. Otherwise, notifications might be deferred indefinitely till the lag is satisfied. If you specify Specifies the class by which to group notifications. The only allowed value is Specifies the time interval that defines the group, in seconds. For example, if this value is 900, notifications generated in the same 15-minute interval are grouped. Specifies either of these types of grouping: Specifies when to start generating notifications. If specified as Specifies how many times to repeat the notification. Set to The quality-of-service flags in Table 11-3 are constants in the Table 11-3 Quality-of-Service Flags Purges the registration after the first notification. Stores notifications in a persistent database queue. In an Oracle RAC environment, if a database instance fails, surviving database instances can deliver any queued notification messages. Default: Notifications are stored in shared memory, which performs more efficiently. Includes the Registers queries for QRCN, described in Query Result Change Notification (QRCN). If a query cannot be registered for QRCN, an error is generated at registration time, unless you also specify Default: Queries are registered for OCN, described in "Object Change Notification (OCN)" Used with To see which queries were simplified, query the static data dictionary view Default: Queries are registered for QRCN in guaranteed mode, described in "Guaranteed Mode" Suppose that you must invoke the procedure Example 11-4 Creating a CQ_NOTIFICATION$_REG_INFO Object Any query in a registered list of queries can cause a continuous query notification. To know when a certain query causes a notification, use the Result: When that query causes a notification, the notification includes the query ID. To add queries to an existing registration, follow these steps: Retrieve the registration ID of the existing registration. You can retrieve it from either saved output or a query of Open the existing registration by calling the procedure Run the queries to register. (Do not run DML or DDL operations.) Close the registration, using the Example 11-5 adds a query to an existing registration whose registration ID is 21. Example 11-5 Adding a Query to an Existing Registration For best CQN performance, follow these registration guidelines: Register few queries—preferably those that reference objects that rarely change. Extremely volatile registered objects cause numerous notifications, whose overhead slows OLTP throughput. Minimize the number of duplicate registrations of any given object, to avoid replicating a notification message for multiple recipients. If you are unable to create a registration, or if you have created a registration but are not receiving the notifications that you expected, the problem might be one of these: The This prevents you from receiving PL/SQL notifications through the notification handler. You were connected as a SYS user when you created the registrations. You must be connected as a non-SYS user to create CQN registrations. You changed a registered object, but did not commit the transaction. Notifications are generated only when the transaction commits. The registrations were not successfully created in the database. To check, query the static data dictionary view Runtime errors occurred during the execution of the notification handler. If so, they were logged to the trace file of the For example, if the ORACLE_SID is Suppose that a registration is created with If runtime errors occurred during the execution of the notification handler, create a very simple version of the notification handler to verify that you are actually receiving notifications, and then gradually add application logic. An example of a very simple notification handler is: There is a time lag between the commit of a transaction and the notification received by the end user. To see top-level information about all registrations, including their QOS options, query the static data dictionary view For example, you can obtain the registration ID for a client and the list of objects for which it receives notifications. To view registration IDs and table names for To see which queries are registered for QRCN, query the static data dictionary view See Also: When a transaction commits, the database determines whether registered objects were modified in the transaction. If so, it runs the notification handler specified in the registration. Topics: When a CQN registration generates a notification, the database passes a In SQL*Plus, you can list these attributes by connecting as Table 11-4 summarizes the attributes of Table 11-4 Attributes of CQ_NOTIFICATION$_DESCRIPTOR The registration ID that was returned during registration. The ID for the transaction that made the change. The name of the database in which the notification was generated. The database event that triggers a notification. For example, the attribute can contain these constants, which correspond to different database events: The number of tables that were modified. This field is present only for OCN registrations. For QRCN registrations, it is If Otherwise: This field is present only for QRCN registrations. For OCN registrations, it is If Otherwise: The In SQL*Plus, you can list these attributes by connecting as Table 11-5 summarizes the attributes of Table 11-5 Attributes of CQ_NOTIFICATION$_TABLE The type of operation performed on the modified table. For example, the attribute can contain these constants, which correspond to different database operations: The name of the modified table. The number of modified rows. A The In SQL*Plus, you can list these attributes by connecting as Table 11-6 summarizes the attributes of Table 11-6 Attributes of CQ_NOTIFICATION$_QUERY Query ID of the changed query. Operation that changed the query (either A If the Table 11-7 summarizes the attributes of Table 11-7 Attributes of CQ_NOTIFICATION$_ROW The type of operation performed on the modified table. See the description of The To delete a registration, call the procedure Only the user who created the registration or the SYS user can deregister it. In this scenario, you are a developer who manages a Web application that provides employee data: name, location, phone number, and so on. The application, which runs on Oracle Application Server, is heavily used and processes frequent queries of the You can use the Create a server-side PL/SQL stored procedure to process the notifications, as instructed in "Creating a PL/SQL Notification Handler". Register the queries on the After you complete these steps, any committed change to the result of a query registered in step 2 causes the notification handler created in step 1 to notify the Web application of the change, whereupon the Web application refreshes the cache by querying the back-end database. Topics: Create a a server-side stored PL/SQL procedure to process notifications as follows: Connect to the database Grant the required privileges to Enable the Connect to the database as a non-SYS user (such as Create database tables to hold records of notification events received: Create the procedure Example 11-6 Creating Server-Side PL/SQL Notification Handler After creating the notification handler, you register the queries for which you want to receive notifications, specifying Example 11-7 Registering a Query View the newly created registration: Result is similar to: Run this transaction, which changes the result of the query with The notification procedure Query the table in which notification events are recorded: Result is similar to: Query the table in which changes to registered tables are recorded: Result is similar to: Query the table in which Result is similar to: This chapter explains how to use SQL data types in database applications. Topics: See Also: Oracle Database PL/SQL Language Reference for information about PL/SQL data types Oracle Database PL/SQL Language Reference for introductory information about Abstract Data Types (ADTs) Oracle Database Object-Relational Developer's Guide for advanced information about ADTs An ADT consists of a data structure and subprograms that manipulate the data. In the static data dictionary view A data type associates fixed properties with the values that can be inserted in table columns or passed as parameters to subprograms. These properties cause Oracle Database to treat values of different data types differently. For example, Oracle Database can add values of Oracle Database provides many data types and several categories for user-defined types that can be used as data types. The Oracle precompilers recognize other data types in embedded SQL programs. These data types are called external data types and are associated with host variables. Do not confuse external data types with Oracle built-in, Oracle-supplied, and user-defined data types. See Also: Oracle Database SQL Language Reference for complete information about SQL data types Oracle Database Concepts for additional introductory information about SQL data types (which it calls Oracle data types) Table 2-1 summarizes the SQL data types that store alphanumeric data. Table 2-1 SQL Character Data Types Fixed-length character literals Fixed-length Unicode character literals Variable-length character literals Variable-length Unicode character literals Single-byte and multibyte character strings of up to (4 gigabytes - 1) * (the value obtained from Single-byte and multibyte Unicode character strings of up to (4 gigabytes - 1) * (the value obtained from Variable-length character data of up to 2 gigabytes - 1. Provided only for backward compatibility. For a client/server application, if the character set on the client side differs from the character set on the server side, then Oracle Database automatically converts See Also: Oracle Database SQL Language Reference for more information about "Large Objects (LOBs)" for more information about "LONG and LONG RAW Data Types" for more information about You can specify the lengths of When using a multibyte database character encoding scheme, consider carefully the space required for tables with character columns. If the database character encoding scheme is single-byte, then the number of bytes and the number of characters in a column is the same. If it is multibyte, however, then generally there is no such correspondence. A character might consist of one or more bytes, depending on the specific multibyte encoding scheme and whether shift-in/shift-out control codes are present. To avoid overflowing buffers, specify data as See Also: Oracle Database Globalization Support Guide for more information about SQL data types Oracle Database SQL Language Reference for more information about SQL data types When choosing a data type for a column that stores alphanumeric data in a table, consider: Space usage Oracle Database blank-pads values stored in Performance Because of the blank-padding difference, a full table scan on a large table containing Comparison semantics When you need ANSI compatibility in comparison semantics, use the See Also: Future compatibility The The SQL data types that store numeric data are The The In client interfaces that Oracle Database supports, arithmetic operations on Native floating-point data types conform substantially with the Institute of Electrical and Electronics Engineers (IEEE) Standard for Binary Floating-Point Arithmetic, IEEE Standard 754-1985 (IEEE754). For details, see Oracle Database SQL Language Reference. Topics: See Also: Oracle Database SQL Language Reference for more information about the Oracle Database SQL Language Reference for more information about the A floating-point number has these components: Binary-valued sign Signed exponent Significand Base The formula for a floating-point value is: For example, the floating-point value 4.31 is represented: The components of the preceding representation are: A floating-point number format specifies how the components of a floating-point number are represented, thereby determining the range and precision of the values that the format can represent. The range is the interval bounded by the smallest and largest values and the precision is the number of significant digits. Both range and precision are finite. If a floating-point number is too precise for a given format, then the number is rounded. How the number is rounded depends on the base of its format, which can be either decimal or binary. A number stored in decimal format is rounded to the nearest decimal place (for example, 1000, 10, or 0.01). A number stored in binary format is rounded to the nearest binary place (for example, 1024, 512, or 1/64). Native floating-point values are stored in binary format. Topics: This formula determines the value of a floating-point number that uses a binary format: Table 2-2 describes the components of the preceding formula. Table 2-2 Binary Floating-Point Format Components 0 or 1 For single-precision (32-bit) data type, an integer from -126 through 127. For double-precision (64-bit) data type, an integer from -1022 through 1023. 0 or 1. (The bit sequence represents a number in base 2.) For single-precision data type, 24. For double-precision data type, 53. The leading bit of the significand, b0, must be set (1), except for subnormal numbers (explained later). Therefore, the leading bit is not actually stored, and a binary format provides n bits of precision while storing only n-1 bits. The IEEE 754 standard defines the in-memory formats for single-precision and double-precision data types, which Table 2-3 shows. Table 2-3 Summary of Binary Format Storage Parameters Single-precision 1 8 24 (23 stored) 32 Double-precision 1 11 53 (52 stored) 64 Note: A significand whose leading bit is set is called normalized. The IEEE 754 standard defines subnormal numbers (also called denormal numbers) that are too small to represent with normalized significands. If the significand of a subnormal number were normalized, then its exponent would be too large. Subnormal numbers preserve this property: If x-y==0.0 (using floating-point subtraction), then x==y. IEEE 754 formats support subnormal values. Table 2-4 shows the range and precision of the IEEE 754 single- and double-precision formats and Oracle Database Table 2-4 Range and Precision of Floating-Point Data Types Footnote 1 These numbers are from the IEEE Numerical Computation Guide. See Also: Oracle Database SQL Language Reference for information about literal representation of numeric values Oracle Database SQL Language Reference for more information about floating-point formats Oracle Database SQL Language Reference for information about floating-point conditions The IEEE 754 standard supports the special values shown in Table 2-5. Each value in Table 2-5 is represented by a specific bit pattern, except The IEEE 754 standard distinguishes between quiet In Oracle Database, exceptions cannot be enabled. Oracle Database acts as the IEEE 754 standard specifies for when exceptions are disabled. In particular, Oracle Database does not distinguish between quiet and signaling The IEEE 754 standard defines these classes of special values: Zero Subnormal Normal Infinity The values in each class in the preceding list are larger than the values in the classes that precede it in the list (ignoring signs), except In Oracle Database: All Any non- Any All -0 is converted to +0. See Also: Oracle Database defines these comparison operators for native floating-point data types: Equal to Not equal to Greater than Greater than or equal to Less than Less than or equal to Unordered Comparisons ignore the sign of zero ( See Also: Oracle Database defines these arithmetic operators for native floating-point data types: Multiplication Division Addition Subtraction Remainder Square root You can define the mode used to round the result of the operation. Exceptions can be raised when operations are performed. Exceptions can also be disabled. Formerly, Java required floating-point arithmetic to be exactly reproducible. IEEE 754 does not have this requirement. Therefore, results of operations (including arithmetic operations) can be delivered to a destination that uses a range greater than the range that the operands of the operation use. You can compute the result of a double-precision multiplication at an extended double-precision destination, but the result must be rounded as if the destination were single-precision or double-precision. The range of the result (that is, the number of bits used for the exponent) can use the range supported by the wider (extended double-precision) destination; however, this might cause a double-rounding error in which the least significant bit of the result is incorrect. This situation can occur only for double-precision multiplication and division on hardware that implements the IA-32 and IA-64 instruction set architecture. Therefore, except for this case, arithmetic for these data types is reproducible across platforms. When the result of a computation is Oracle Database defines functions that convert between floating-point and other data types, including string formats that use decimal precision (but precision might be lost during the conversion). For example: Oracle Database can raise exceptions during conversion. The IEEE 754 standard defines these exceptions: Invalid Inexact Divide by zero Underflow Overflow Oracle Database does not raise these exceptions for native floating-point data types. Generally, operations that raise exceptions produce the values described in Table 2-6. Oracle Database supports native floating-point data types in these client interfaces: SQL PL/SQL Oracle Call Interface (OCI) Oracle C++ Call Interface (OCCI) Pro*C/C++ JDBC Topics: The OCI API implements the IEEE 754 single- and double-precision native floating-point data types with the data types Oracle Database supports the SQL data types Pro*C/C++ supports the native Oracle Database stores date and time (datetime) data in its own internal format, in 7-byte fields that correspond to century, year, month, day, hour, minute, and second. Table 2-7 summarizes the SQL datetime data types. For more information about these data types, see Oracle Database SQL Language Reference. Table 2-7 SQL Datetime Data Types Use to store point-in-time (datetime) values in a table—for example, dates of jobs. Use to store datetime values that are precise to fractional seconds—for example, times of events that must be compared to determine the order in which they occurred. Use to store datetime values that must be gathered or coordinated across geographic regions. Use to store datetime values when the time zone is insignificant—for example, in an application that schedules teleconferences, where participants each see the start and end times for their own time zone. Appropriate for two-tier applications in which you want to display dates and times that use the time zone of the client system. Usually inappropriate for three-tier applications, because data displayed in a web browser is formatted according to the time zone of the web server, not the time zone of the browser. The web server is the database client, so its local time is used. Use to store the difference between two datetime values, where only the year and month are significant—for example, to set a reminder for a date 18 months in the future, or check whether 6 months have elapsed since a particular date. Use to store the precise difference between two datetime values—for example, to set a reminder for a time 36 hours in the future or to record the time between the start and end of a race. To represent long spans of time with high precision, use a large number of days. Topics: See Also: The simplest way to display the current date and time is: The preceding command displays the current date and time in the default date format, which depends on the initialization parameter The standard Oracle Database default date format is To display Example 2-1 uses Example 2-1 Displaying Current Date and Time in Nondefault Format Result: Tip: See Also: Oracle Database SQL Language Reference for more information about Oracle Database Globalization Support Guide for information about Oracle Database SQL Language Reference for more information about Oracle Database SQL Language Reference for information about datetime format models Oracle Database SQL Language Reference for more information about the Although Oracle Database always stores dates in the default date format (set by the initialization parameter Example 2-2 creates a table with a Example 2-2 Inserting and Displaying Date in Nondefault Formats Result: Result: See Also: Oracle Database Globalization Support Guide for information about Oracle Database SQL Language Reference for more information about Oracle Database SQL Language Reference for more information about Oracle Database SQL Language Reference for information about datetime format models Oracle Database SQL Language Reference for more information about the Although Oracle Database always stores times in the 24-hour format In a The default time is 12:00:00 A.M. (midnight). The default time applies to any value in the column that has no time portion, either because none was specified or because the value was truncated. The default date is the first day of the current month. The default date applies to any value in the column that has no date portion, because none was specified. Example 2-3 creates a table with a Example 2-3 Inserting and Displaying Dates and Times in Nondefault Formats Display current date: Result: Display both date and time portions of stored datetime values: Result: You can perform arithmetic operations on datetime values. The results of such operations are determined by the rules in Oracle Database SQL Language Reference. SQL has many datetime functions that you can use in datetime expressions. For example, the function Table 2-8 summarizes the SQL functions that convert to or from datetime data types. Table 2-8 SQL Conversion Functions for Datetime Data Types You can import, export, and compare When importing, exporting, and comparing Topics: To represent Geographic Information System (GIS) or spatial data in the database, you can use Oracle Spatial features, including the type Oracle Multimedia enables Oracle Database to store, manage, and retrieve images, audio, video, or other heterogeneous media data in an integrated fashion with other enterprise information. Oracle Multimedia extends Oracle Database reliability, availability, and data management to multimedia content in traditional, Internet, electronic commerce, and media-rich applications. Whether you store such multimedia data inside the database as Oracle Multimedia provides the Extracting metadata and attributes from multimedia data Retrieving and managing multimedia data from Oracle Multimedia, web servers, file systems, and other servers Performing manipulation operations on image data For representing large amounts of data, Oracle Database provides: LONG and LONG RAW Data Types (for backward compatibility) Large Objects (LOBs) are data types that are designed to store large amounts of data (the maximum size of a LOB depends on how your database is configured). Storing data in LOBs enables you to access and manipulate the data efficiently in your application. Table 2-9 summarizes the LOBs. Table 2-9 Large Objects (LOBs) An instance of type See Also: Oracle Database SQL Language Reference for additional general information about LOBs Oracle Database SecureFiles and Large Objects Developer's Guide for information about using LOBs in application development The Rather than writing low-level code to do full-text searches, you can use Oracle Text. Oracle Text stores the search data in a special kind of index and lets you query the data with operators and PL/SQL packages. This technology enables you to create your own search engine using data from tables, files, or URLs, and combine the search logic with relational queries. You can also search XML data this way with the XPath notation. If you have information stored as files in XML format, or want to store an ADT in XML format, then you can use the Oracle-supplied type When you create an In a As binary XML (stored internally as a Object relationally See Also: Oracle XML DB Developer's Guide for information about Oracle XML DB and how you can use it to store, generate, manipulate, manage, and query XML data in the database Oracle XML Developer's Kit Programmer's Guide for information about client-side programming with XML Some languages allow data types to change at run time, and some let a program check the type of a variable. For example, C has the In Oracle Database, you can create variables and columns that can hold data of any type and test their values to determine their underlying representation. For example, a single table column can have a numeric value in one row, a string value in another row, and an object in another row. You can use the Oracle-supplied ADT To check and manipulate type information, use the With OCI, use the Example 2-4 Accessing Information in a SYS.ANYDATA Column Result: SQL statements that create tables and clusters can use ANSI data types and data types from the IBM products SQL/DS and DB2 (except those noted after this paragraph). Oracle Database converts the ANSI or IBM data type to the equivalent Oracle data type, records the Oracle data type as the name of the column data type, and stores the column data in the Oracle data type. For conversion details, see Oracle Database SQL Language Reference. Note: Oracle Expression Filter (a feature of Rules Manager) enables you to store, index, and evaluate conditional expressions in one or more columns of a database table. Then Oracle Expression Filter compares the stored expressions to incoming data, identifying rows of interest. Scenario: You created the following table, in which each row holds data for a stock-trading account holder, and you want to define a column that stores information about the stocks in which each trader is interested as a conditional expression. Solution: Create a type with attributes for the trading symbol, limit price, and amount of change in the stock price: Create an attribute set based on the type Associate the attribute set with the expression set stored in the column The preceding code ensures that the Populate the table with trader names, e-mail addresses, and conditional expressions that represent stocks in which the trader is interested, at specific prices. For example: Use the Result: Tip: See Also: The fastest way to access a row is by its address, or rowid, which uniquely identifies it. Different rows in the same data block can have the same rowid only if they are in different clustered tables. If a row is larger than one data block, then its rowid identifies its initial row piece. To see rowids, query the Note: Topics: Each table in Oracle Database has a pseudocolumn named Example 2-5 creates a table of with a column of the data type Example 2-5 Querying the ROWID Pseudocolumn Query: Query: In heap-organized tables generated by Oracle Database, the values in the Note: Topics: A Data file identifier Block identifier Row identifier On most platforms, the size of this structure is 6 bytes. The database server returns a A The database server returns a To access and interpret the contents of an extended rowid, use the Some client applications use a binary internal format for the In binary internal format, the The format of the extended binary In tables that are foreign (that is, not generated by Oracle Database) or index-organized, the values in the Urowids for foreign tables (such as DB2 tables accessed through a gateway) are called foreign rowids. Urowids for index-organized tables (whose rows are stored in index leaves, which can move) are called logical rowids. Oracle Database creates logical rowids based on the primary key of the table. The logical rowids do not change if the primary key does not change. To store urowids in a table, define a column of data type Generally, you cannot assign a value of one data type to a variable or column of another data type, or create an expression with values of different data types. However, in some cases, Oracle Database accepts data of one type where it expects data of another type and then automatically converts the accepted data to the expected type. This is called implicit data conversion. Topics: if the data type of A character-to- Examples Assume that In the assignment the data type of In the statement the data type of In the statement the data type of In the statement the data type of When evaluating an expression, Oracle Database can perform the same automatic conversions that it does for assignments. The target data type is determined by the context of the expression. For example, if an expression is the operand of an arithmetic operator, then Oracle Database tries to convert the value of the expression to For the assignment Oracle Database first evaluates The dynamic performance view These views enable third-party tools to leverage SQL functions without maintaining their metadata in the application layer. Topics: See Also: Oracle Database Reference for more information about Oracle Database Reference for more information about In the view The The In the view Often, a SQL function argument can have any data type in a data type family. Table 2-11 shows the data type families and their member data types.
PKU/Id Dd PK |%A OEBPS/adfns_web.htm
4 Using Indexes in Database Applications
Guidelines for Managing Indexes
NOLOGGING
Managing Indexes
When to Use Domain Indexes
When to Use Function-Based Indexes
NULL. Therefore, either ensure that no column involved in the index expression can contain NULL or use the NVL function in the index expression to substitute another value for NULL. (For information about NVL, see Oracle Database SQL Language Reference.)
Advantages of Function-Based Indexes
WHERE clause selects fewer than 15% of the rows of a large table. The optimizer can more accurately estimate how many rows an expression selects if the expression is materialized in a function-based index.ANALYZE statement (described in Oracle Database SQL Language Reference) can build a histogram.REF column.UPPER and LOWER for case-insensitive sorts (as in Example 4-3) and the SQL function NLSSORT for linguistic-based sorts (as in Example 4-4).
Disadvantages of Function-Based Indexes
DBMS_STATS.GATHER_TABLE_STATS (described in Oracle Database PL/SQL Packages and Types Reference) or DBMS_STATS.GATHER_SCHEMA_STATS (described in Oracle Database PL/SQL Packages and Types Reference).DBMS_STATS.GATHER_TABLE_STATS or DBMS_STATS.GATHER_SCHEMA_STATS.OR expansion.DETERMINISTIC, but because Oracle Database does not check this assertion, you must ensure that the function really is deterministic.DETERMINISTIC function and recompile it, then you must manually rebuild any dependent function-based indexes and materialized views. Otherwise, they report results for the prior version of the function.NOT NULL, you must ensure that the query that uses the index cannot fetch NULL values. Otherwise, the database performs a full table scan.VARCHAR2, RAW, LONGRAW, or a PL/SQL data type of unknown length.
CREATE OR REPLACE FUNCTION initials (
name IN VARCHAR2
) RETURN VARCHAR2
DETERMINISTIC
IS
BEGIN
RETURN('A. J.');
END;
/
/* Invoke SUBSTR both when creating index and when referencing
function in queries. */
CREATE INDEX func_substr_index ON
EMPLOYEES(SUBSTR(initials(FIRST_NAME),1,10));
SELECT SUBSTR(initials(FIRST_NAME),1,10) FROM EMPLOYEES;
CREATE FUNCTION statement, including restrictions
Examples of Function-Based Indexes
a, b, and c; creates an index on the table, and then queries the table. The index is a composite index on three columns: a virtual column that represents the expression a+b*(c-1), column a, and column b. The query uses the indexed expression in its WHERE clause; therefore, it can use an index range scan instead of a full index scan.
DROP TABLE Fbi_tab;
CREATE TABLE Fbi_tab (
a INTEGER,
b INTEGER,
c INTEGER
);
CREATE INDEX Idx ON Fbi_tab (a+b*(c-1), a, b);
SELECT a FROM Fbi_tab WHERE a+b*(c-1) < 100;
Reg_obj has been defined, and that it stores information about a city. The example creates a table whose first column has type Reg_obj, a deterministic function with a parameter of type Reg_obj, and two function-based indexes that invoke the function. The first query uses the first index to quickly find cities further than 1000 miles from the equator. The second query uses the second index (which is composite) to quickly find cities where the temperature delta is less than 20 and the maximum temperature is greater than 75. (The table is not populated for the example, so the queries return no rows.)
DROP TABLE Weatherdata_tab;
CREATE TABLE Weatherdata_tab (
Reg_obj INTEGER,
Maxtemp INTEGER,
Mintemp INTEGER
);
Reg_obj:
CREATE OR REPLACE FUNCTION Distance_from_equator (
Reg_obj IN INTEGER
) RETURN INTEGER
DETERMINISTIC
IS
BEGIN
RETURN(3000);
END;
/
CREATE INDEX Distance_index
ON Weatherdata_tab (Distance_from_equator (Reg_obj));
SELECT * FROM Weatherdata_tab
WHERE (Distance_from_equator (Reg_Obj)) > '1000';
no rows selected
CREATE INDEX Compare_index
ON Weatherdata_tab ((Maxtemp - Mintemp) DESC, Maxtemp);
SELECT * FROM Weatherdata_tab
WHERE ((Maxtemp - Mintemp) < '20' AND Maxtemp > '75');
no rows selected
EMPLOYEES table and then uses the index expression in a query.
CREATE INDEX emp_lastname ON EMPLOYEES (UPPER(LAST_NAME));
SELECT first_name, last_name
FROM EMPLOYEES
WHERE UPPER(LAST_NAME) LIKE 'J%S_N';
FIRST_NAME LAST_NAME
-------------------- -------------------------
Charles Johnson
1 row selected.
NAME, and a function-based index to sort that column using the collation sequence GERMAN, and then selects all columns of the table, ordering them by NAME. Because the query can use the index, the query is faster. (Assume that the query is run in a German session, where NLS_SORT is set to GERMAN and NLS_COMP is set to ANSI. Otherwise, the query would have to specify the values of these Globalization Support parameters.)
DROP TABLE nls_tab;
CREATE TABLE nls_tab (NAME VARCHAR2(80));
CREATE INDEX nls_index
ON nls_tab (NLSSORT(NAME, 'NLS_SORT = GERMAN'));
NAME:
SELECT * FROM nls_tab
WHERE NAME IS NOT NULL
ORDER BY NAME;
PK3 Ͳ PK |%A OEBPS/adfns_sqlproc.htm
9 Developing PL/SQL Web Applications
Overview of PL/SQL Web Applications
Implementing PL/SQL Web Applications
PL/SQL Gateway
mod_plsql
mod_plsql is one implementation of the PL/SQL gateway. The module is a plug-in of Oracle HTTP Server and enables web browsers to invoke PL/SQL stored subprograms. Oracle HTTP Server is a component of both Oracle Application Server and the database.mod_plsql plug-in enables you to use PL/SQL stored subprograms to process HTTP requests and generate responses. In this context, an HTTP request is a URL that includes parameter values to be passed to a stored subprogram. PL/SQL gateway translates the URL, invokes the stored subprogram with the parameters, and returns output (typically HTML) to the client.mod_plsql over the embedded form of the PL/SQL gateway are:mod_plsql features such as dynamic HTML caching, system monitoring, and logging in the Common Log Format.
Embedded PL/SQL Gateway
mod_plsql in the database but does not require the Oracle HTTP Server. You configure the embedded PL/SQL gateway with the DBMS_EPG package in the PL/SQL Web Toolkit.mod_plsql are as follows:
PL/SQL Web Toolkit
mod_plsql at run time.
Package Description of Contents
htp package. The function versions do not directly generate output in a web page. Instead, they pass their output as return values to the statements that invoke them. Use these functions when you must nest function calls.
htp.anchor generates the HTML anchor tag, <A>.
OWA_PATTERN for manipulating strings. You can also use them directly.
Using mod_plsql Gateway to Map Client Requests to a PL/SQL Web Application
mod_plsql maps web client requests to PL/SQL stored subprograms over HTTP. See this documentation for instructions.
mod_plsqlmod_plsql module
Using Embedded PL/SQL Gateway
mod_plsql gateway. Before using the embedded version of the gateway, familiarize yourself with the Oracle HTTP Server mod_plsql User's Guide. Much of the information is the same or similar.
How Embedded PL/SQL Gateway Processes Client Requests
Description of "Figure 9-2 Processing Client Requests with Embedded PL/SQL Gateway"
mod_plsql, the embedded gateway processes HTTP requests with the Oracle XML DB Listener. This listener is the same server-side process as the Oracle Net Listener and supports Oracle Net Services, HTTP, and FTP.xdbconfig.xml file. Use the DBMS_EPG package for all embedded PL/SQL gateway configuration, for example, creating or setting attributes for a DAD.
Installing Embedded PL/SQL Gateway
Configuring Embedded PL/SQL Gateway
mod_plsql by editing the Oracle HTTP Server configuration files. Because the embedded gateway is installed as part of the Oracle XML DB HTTP Listener, you manage the embedded gateway as a servlet through the Oracle XML DB servlet management interface.DBMS_EPG. This package modifies the underlying xdbconfig.xml configuration file that XML DB uses. The default values of the embedded gateway configuration parameters are sufficient for most users.
Configuring Embedded PL/SQL Gateway: Overview
mod_plsql, each request for a PL/SQL stored subprogram is associated with a Database Access Descriptor (DAD). A DAD is a set of configuration values used for database access. A DAD specifies information such as:xdbconfig.xml. The value of the DAD attribute corresponds to the element content. For example, the database-username DAD attribute corresponds to the <database-username> XML element; if the value of the DAD attribute is HR it corresponds to <database-username>HR<database-username>. DAD attribute names are case-sensitive.DBMS_EPG package to perform these embedded PL/SQL gateway configurations:DBMS_EPG.CREATE_DAD procedure.DBMS_EPG.SET_DAD_ATTRIBUTE procedure.mod_plsql DAD parameters. Enumeration values in the "Legal Values" column are case-sensitive.
mod_plsql DAD Attribute Embedded PL/SQL Gateway DAD Attribute Multiple Occurrences Legal Values
PlsqlAfterProcedure
after-procedure
PlsqlAlwaysDescribeProcedure
always-describe-procedure
PlsqlAuthenticationMode
authentication-mode
PlsqlBeforeProcedure
before-procedure
PlsqlBindBucketLengths
bind-bucket-lengths
PlsqlBindBucketWidths
bind-bucket-widths
PlsqlCGIEnvironmentList
cgi-environment-list
PlsqlCompatibilityMode
compatibility-mode
PlsqlDatabaseUsername
database-username
PlsqlDefaultPage
default-page
PlsqlDocumentPath
document-path
PlsqlDocumentProcedure
document-procedure
PlsqlDocumentTablename
document-table-name
PlsqlErrorStyle
error-style
PlsqlExclusionList
exclusion-list
PlsqlFetchBufferSize
fetch-buffer-size
PlsqlInfoLogging
info-logging
PlsqlInputFilterEnable
input-filter-enable
PlsqlMaxRequestsPerSession
max-requests-per-session
PlsqlNLSLanguage
nls-language
PlsqlOWADebugEnable
owa-debug-enable
PlsqlPathAlias
path-alias
PlsqlPathAliasProcedure
path-alias-procedure
PlsqlRequestValidationFunction
request-validation-function
PlsqlSessionCookieName
session-cookie-name
PlsqlSessionStateManagement
session-state-management
PlsqlTransferMode
transfer-mode
PlsqlUploadAsLongRaw
upload-as-long-raw
mod_plsql users do not need these attributes:PlsqlDatabasePasswordPlsqlDatabaseConnectString (because the embedded gateway does not support logon to external databases)DBMS_EPG global attributes and the corresponding mod_plsql global parameters.
mod_plsql DAD Attribute Embedded PL/SQL Gateway DAD Attribute Multiple Occurrences Legal Values
PlsqlLogLevel
log-level
PlsqlMaxParameters
max-parameters
mod_plsql DAD attributes. See this documentation for default values and usage notes.DBMS_EPG packagexdbconfig.xml file
Configuring User Authentication for Embedded PL/SQL Gateway
mod_plsql. In particular, it does not store database passwords in a DAD.
mod_plsql.DBMS_EPG package to configure database authentication.
Configuring Static Authentication with DBMS_EPG
mod_plsql user who stores database user names and passwords in the DAD so that the browser user is not required to enter database authentication information.XDBADMIN role assigned).HR_DAD and maps the virtual path to /hrweb/:
EXEC DBMS_EPG.CREATE_DAD('HR_DAD', '/hrweb/*');
ALTER ANY USER system privilege. Set the DAD attribute database-username to the database account whose privileges must be used by the DAD. For example, this procedure specifies that the DAD named HR_DAD has the privileges of the HR account:
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('HR_DAD', 'database-username', 'HR');
database-username is case-sensitive.
EXEC DBMS_EPG.AUTHORIZE_DAD('HR_DAD', 'HR');
XDBADMIN privileges, log on as the database user whose privileges must be used by the DAD, and then use this command to assign these privileges to the DAD:
EXEC DBMS_EPG.AUTHORIZE_DAD('HR_DAD');
database-username attribute setting of the DAD determines which user's privileges to use.mod_plsql, the embedded gateway connects to the database as the special user ANONYMOUS, but accesses database objects with the user privileges assigned to the DAD. The database rejects access if the browser user attempts to connect explicitly with the HTTP Authorization header.
ANONYMOUS is locked after XML DB installation. To use static authentication with the embedded PL/SQL gateway, first unlock this account.
Configuring Dynamic Authentication with DBMS_EPG
mod_plsql user who does not store database user names and passwords in the DAD.database-username attribute is set for the DAD. If the attribute is not set, then the embedded gateway connects to the database as the user supplied by the browser client. If the attribute is set, then the database restricts access to the user specified in the database-username attribute.XDBADMIN role).DYNAMIC_DAD and maps the virtual path to /hrweb/:
EXEC DBMS_EPG.CREATE_DAD('DYNAMIC_DAD', '/hrweb/*');
database-username to the database account whose privileges must be used by the DAD. The browser prompts the user to enter the username and password for this account when accessing the DAD. For example, this procedure specifies that the DAD named DYNAMIC_DAD has the privileges of the HR account:
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('DYNAMIC_DAD', 'database-username', 'HR');
database-username is case-sensitive.
Configuring Anonymous Authentication with DBMS_EPG
mod_plsql user who creates a special DAD database user for database logon, but stores the application procedures and document tables in a different schema and grants access to the procedures and document tables to PUBLIC.XDBADMIN role assigned.HR_DAD and maps the virtual path to /hrweb/:
EXEC DBMS_EPG.CREATE_DAD('HR_DAD', '/hrweb/*');
database-username to ANONYMOUS. For example:
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('HR_DAD', 'database-username', 'ANONYMOUS');
database-username and ANONYMOUS are case-sensitive.ANONYMOUS privileges to access database objects, because ANONYMOUS has no system privileges and owns no database objects.
Determining the Authentication Mode of a DAD
database-username attribute for the DAD set?database-username user?database-username attribute the one that the user authorized to use the DAD?
DAD Exists? database-username set? User authorized? Mode
ANONYMOUS)
MY_DAD. If the database-username attribute for MY_DAD is set to HR, but the HR user does not authorize MY_DAD, then the authentication mode for MY_DAD is dynamic and restricted. A browser user who attempts to run a PL/SQL subprogram through MY_DAD is prompted to enter the HR database username and password.DBA_EPG_DAD_AUTHORIZATION view shows which users have authorized use of a DAD. The DAD_NAME column displays the name of the DAD; the USERNAME column displays the user whose privileges are assigned to the DAD. The DAD authorized might not exist.
Creating and Configuring DADs: Examples
HR and assigns it the privileges of the HR account, which then authorizes it.HR account.
------------------------------------------------------------------------
--- DAD with static authentication
------------------------------------------------------------------------
CONNECT SYSTEM AS SYSDBA
PASSWORD: password
EXEC DBMS_EPG.CREATE_DAD('Static_Auth_DAD', '/static/*');
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('Static_Auth_DAD', 'database-username', 'HR');
GRANT EXECUTE ON DBMS_EPG TO HR;
-- Authorization
CONNECT HR
PASSWORD: password
EXEC DBMS_EPG.AUTHORIZE_DAD('Static_Auth_DAD');
------------------------------------------------------------------------
-- DAD with dynamic authentication
------------------------------------------------------------------------
CONNECT SYSTEM AS SYSDBA
PASSWORD: password
EXEC DBMS_EPG.CREATE_DAD('Dynamic_Auth_DAD', '/dynamic/*');
-------------------------------------------------------------------------
-- DAD with dynamic authentication restricted
-------------------------------------------------------------------------
EXEC DBMS_EPG.CREATE_DAD('Dynamic_Auth_DAD_Restricted', '/dynamic/*');
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE
('Dynamic_Auth_DAD_Restricted', 'database-username', 'HR');
database-user attribute is changed to your username)HR and assigns it the privileges of the HR account. Then:HR authorizes a nonexistent DAD.OE authorizes the DAD (whose database-user attribute is set to HR.database-user attribute is changed to OE.
REM Create DAD with static authentication for database user HR
CONNECT SYSTEM AS SYSDBA
PASSWORD: password
EXEC DBMS_EPG.CREATE_DAD('Static_Auth_DAD', '/static/*');
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('Static_Auth_DAD', 'database-username', 'HR');
GRANT EXECUTE ON DBMS_EPG TO HR;
REM Database user HR authorizes DAD that does not exist
CONNECT HR
PASSWORD: password
EXEC DBMS_EPG.AUTHORIZE_DAD('Static_Auth_DAD_Typo');
REM Database user OE authorizes DAD with database-username 'HR'
CONNECT OE
PASSWORD: password
EXEC DBMS_EPG.AUTHORIZE_DAD('Static_Auth_DAD');
Determining the Authentication Mode for a DAD: Example
show_dad_auth_status, which accepts the name of a DAD and reports its authentication mode. If the specified DAD does not exist, the procedure exits with an error.
CREATE OR REPLACE PROCEDURE show_dad_auth_status (p_dadname VARCHAR2) IS
v_daduser VARCHAR2(32);
v_cnt PLS_INTEGER;
BEGIN
-- Determine DAD user
v_daduser := DBMS_EPG.GET_DAD_ATTRIBUTE(p_dadname, 'database-username');
-- Determine whether DAD authorization exists for DAD user
SELECT COUNT(*)
INTO v_cnt
FROM DBA_EPG_DAD_AUTHORIZATION da
WHERE da.DAD_NAME = p_dadname
AND da.USERNAME = v_daduser;
-- If DAD authorization exists for DAD user, authentication mode is static
IF (v_cnt > 0) THEN
DBMS_OUTPUT.PUT_LINE (
'''' || p_dadname ||
''' is set up for static authentication for user ''' ||
v_daduser || '''.');
RETURN;
END IF;
-- If no DAD authorization exists for DAD user, authentication mode is dynamic
-- Determine whether dynamic authentication is restricted to particular user
IF (v_daduser IS NOT NULL) THEN
DBMS_OUTPUT.PUT_LINE (
'''' || p_dadname ||
''' is set up for dynamic authentication for user ''' ||
v_daduser || ''' only.');
ELSE
DBMS_OUTPUT.PUT_LINE (
'''' || p_dadname ||
''' is set up for dynamic authentication for any user.');
END IF;
END;
/
SET SERVEROUTPUT ON;
BEGIN
show_dad_auth_status('Static_Auth_DAD');
END;
/
'Static_Auth_DAD' is set up for static authentication for user 'HR'.
Determining the Authentication Mode for All DADs: Example
show_dad_auth_status procedure from Example 9-3.
DECLARE
v_dad_names DBMS_EPG.VARCHAR2_TABLE;
BEGIN
DBMS_OUTPUT.PUT_LINE
('---------- Authorization Status for All DADs ----------');
DBMS_EPG.GET_DAD_LIST(v_dad_names);
FOR i IN 1..v_dad_names.count LOOP
show_dad_auth_status(v_dad_names(i));
END LOOP;
END;
/
---------- Authorization Status for All DADs ----------
'Static_Auth_DAD' is set up for static auth for user 'HR'.
'Dynamic_Auth_DAD' is set up for dynamic auth for any user.
'Dynamic_Auth_DAD_Restricted' is set up for dynamic auth for user 'HR' only.
Showing DAD Authorizations that Are Not in Effect: Example
database-username attribute of the DAD
DECLARE
v_dad_names DBMS_EPG.VARCHAR2_TABLE;
v_dad_user VARCHAR2(32);
v_dad_found BOOLEAN;
BEGIN
DBMS_OUTPUT.PUT_LINE
('---------- DAD Authorizations Not in Effect ----------');
DBMS_EPG.GET_DAD_LIST(v_dad_names);
FOR r IN (SELECT * FROM DBA_EPG_DAD_AUTHORIZATION) LOOP -- Outer loop
v_dad_found := FALSE;
FOR i IN 1..v_dad_names.count LOOP -- Inner loop
IF (r.DAD_NAME = v_dad_names(i)) THEN
v_dad_user :=
DBMS_EPG.GET_DAD_ATTRIBUTE(r.DAD_NAME, 'database-username');
-- Is database-username the user for whom DAD is authorized?
IF (r.USERNAME <> v_dad_user) THEN
DBMS_OUTPUT.PUT_LINE (
'DAD authorization of ''' || r.dad_name ||
''' by user ''' || r.username || '''' ||
' is not in effect because DAD user is ' ||
'''' || v_dad_user || '''.');
END IF;
v_dad_found := TRUE;
EXIT; -- Inner loop
END IF;
END LOOP; -- Inner loop
-- Does DAD exist?
IF (NOT v_dad_found) THEN
DBMS_OUTPUT.PUT_LINE (
'DAD authorization of ''' || r.dad_name ||
''' by user ''' || r.username ||
''' is not in effect because the DAD does not exist.');
END IF;
END LOOP; -- Outer loop
END;
/
---------- DAD Authorizations Not in Effect ----------
DAD authorization of 'Static_Auth_DAD' by user 'OE' is not in effect
because DAD user is 'HR'.
DAD authorization of 'Static_Auth_DAD_Typo' by user 'HR' is not in effect
because DAD does not exist.
Examining Embedded PL/SQL Gateway Configuration
$ORACLE_HOME/rdbms/admin/epgstat.sql
epgstat.sql script for Example 9-1 when the ANONYMOUS account is locked.
@$ORACLE_HOME/rdbms/admin/epgstat.sql
+--------------------------------------+
| XDB protocol ports: |
| XDB is listening for the protocol |
| when the protocol port is nonzero. |
+--------------------------------------+
HTTP Port FTP Port
--------- --------
0 0
1 row selected.
+---------------------------+
| DAD virtual-path mappings |
+---------------------------+
Virtual Path DAD Name
-------------------------------- --------------------------------
/dynamic/* Dynamic_Auth_DAD_Restricted
/static/* Static_Auth_DAD
2 rows selected.
+----------------+
| DAD attributes |
+----------------+
DAD Name DAD Param DAD Value
------------ --------------------- ----------------------------------------
Dynamic_Auth database-username HR
_DAD_Restric
ted
Static_Auth_ database-username HR
DAD
2 rows selected.
+---------------------------------------------------+
| DAD authorization: |
| To use static authentication of a user in a DAD, |
| the DAD must be authorized for the user. |
+---------------------------------------------------+
DAD Name User Name
-------------------------------- --------------------------------
Static_Auth_DAD HR
OE
Static_Auth_DAD_Typo HR
3 rows selected.
+----------------------------+
| DAD authentication schemes |
+----------------------------+
DAD Name User Name Auth Scheme
-------------------- -------------------------------- ------------------
Dynamic_Auth_DAD Dynamic
Dynamic_Auth_DAD_Res HR Dynamic Restricted
tricted
Static_Auth_DAD HR Static
3 rows selected.
+--------------------------------------------------------+
| ANONYMOUS user status: |
| To use static or anonymous authentication in any DAD, |
| the ANONYMOUS account must be unlocked. |
+--------------------------------------------------------+
Database User Status
--------------- --------------------
ANONYMOUS EXPIRED & LOCKED
1 row selected.
+-------------------------------------------------------------------+
| ANONYMOUS access to XDB repository: |
| To allow public access to XDB repository without authentication, |
| ANONYMOUS access to the repository must be allowed. |
+-------------------------------------------------------------------+
Allow repository anonymous access?
----------------------------------
false
1 row selected.
Invoking PL/SQL Stored Subprograms Through Embedded PL/SQL Gateway
mod_plsql gateway. See Oracle HTTP Server mod_plsql User's Guide for instructions. You must adapt the mod_plsql instructions slightly for use with the embedded gateway. For example, invoke the embedded gateway in a browser by entering the URL in this format:
protocol://hostname[:port]/virt-path/[[!][schema.][package.]proc_name[?query_str]]
virt-path stands for the virtual path that you configured in DBMS_EPG.CREATE_DAD. The mod_plsql documentation uses DAD_location instead of virt-path.
Securing Application Access with Embedded PL/SQL Gateway
mod_plsql. See Oracle HTTP Server mod_plsql User's Guide for instructions.
Restrictions in Embedded PL/SQL Gateway
mod_plsql restrictions documented in the first chapter of Oracle HTTP Server mod_plsql User's Guide apply equally to the embedded gateway. In addition, the embedded version of the gateway does not support these features:
Using Embedded PL/SQL Gateway: Scenario
hr.employees table and delivers HTML output to a web browser through the PL/SQL gateway. It assumes that you have both XML DB and the sample schemas installed.ALTER USER privileges and ensure that the database account ANONYMOUS is unlocked. The ANONYMOUS account, which is locked by default, is required for static authentication. If the account is locked, then use this SQL statement to unlock it:
ALTER USER anonymous ACCOUNT UNLOCK;
XDBADMIN role.XDADMIN role, query the data dictionary:
SELECT *
FROM DBA_ROLE_PRIVS
WHERE GRANTED_ROLE = 'XDBADMIN';
HR_DAD and maps the virtual path to /plsql/:
EXEC DBMS_EPG.CREATE_DAD('HR_DAD', '/plsql/*');
database-username to the database user whose privileges must be used by the DAD. For example, this procedure specifies that the DAD HR_DAD accesses database objects with the privileges of user HR:
EXEC DBMS_EPG.SET_DAD_ATTRIBUTE('HR_DAD', 'database-username', 'HR');
database-username is case-sensitive.EXECUTE privilege to the database user whose privileges must be used by the DAD (so that he or she can authorize the DAD). For example:
GRANT EXECUTE ON DBMS_EPG TO HR;
HR).
EXEC DBMS_EPG.AUTHORIZE_DAD('HR_DAD');
print_employees. This program creates an HTML page that includes the result set of a query of hr.employees:
CREATE OR REPLACE PROCEDURE print_employees IS
CURSOR emp_cursor IS
SELECT last_name, first_name
FROM hr.employees
ORDER BY last_name;
BEGIN
HTP.PRINT('<html>');
HTP.PRINT('<head>');
HTP.PRINT('<meta http-equiv="Content-Type" content="text/html">');
HTP.PRINT('<title>List of Employees</title>');
HTP.PRINT('</head>');
HTP.PRINT('<body TEXT="#000000" BGCOLOR="#FFFFFF">');
HTP.PRINT('<h1>List of Employees</h1>');
HTP.PRINT('<table width="40%" border="1">');
HTP.PRINT('<tr>');
HTP.PRINT('<th align="left">Last Name</th>');
HTP.PRINT('<th align="left">First Name</th>');
HTP.PRINT('</tr>');
FOR emp_record IN emp_cursor LOOP
HTP.PRINT('<tr>');
HTP.PRINT('<td>' || emp_record.last_name || '</td>');
HTP.PRINT('<td>' || emp_record.first_name || '</td>');
END LOOP;
HTP.PRINT('</table>');
HTP.PRINT('</body>');
HTP.PRINT('</html>');
END;
/
lsnrctl status | grep HTTP
(DESCRIPTION=
(ADDRESS=(PROTOCOL=tcp)(HOST=example.com)(PORT=8080))
(Presentation=HTTP)
(Session=RAW)
)
listener_name with the name of your Oracle Net local listener), then restart the database and the listener:
dispatchers="(PROTOCOL=TCP)"
local_listener=listener_name
print_employees program from your web browser. For example, you can use this URL, replacing host with the name of your host computer and port with the value of the PORT parameter in the previous step:
http://host:port/plsql/print_employees
test.com and your HTTP port is 8080, then enter:
http://example.com:8080/plsql/print_employees
hr.employees table.
Generating HTML Output with PL/SQL
HTP functions that correspond to each HTML tag.
CREATE OR REPLACE PROCEDURE html_page IS
BEGIN
HTP.HTMLOPEN; -- generates <HTML>
HTP.HEADOPEN; -- generates <HEAD>
HTP.TITLE('Title'); -- generates <TITLE>Hello</TITLE>
HTP.HEADCLOSE; -- generates </HTML>
-- generates <BODY TEXT="#000000" BGCOLOR="#FFFFFF">
HTP.BODYOPEN( cattributes => 'TEXT="#000000" BGCOLOR="#FFFFFF"');
-- generates <H1>Heading in the HTML File</H1>
HTP.HEADER(1, 'Heading in the HTML File');
HTP.PARA; -- generates <P>
HTP.PRINT('Some text in the HTML file.');
HTP.BODYCLOSE; -- generates </BODY>
HTP.HTMLCLOSE; -- generates </HTML>
END;
/
HTP.PRINT function to print both text and tags. Example 9-8 illustrates this technique.
CREATE OR REPLACE PROCEDURE html_page2 IS
BEGIN
HTP.PRINT('<html>');
HTP.PRINT('<head>');
HTP.PRINT('<meta http-equiv="Content-Type" content="text/html">');
HTP.PRINT('<title>Title of the HTML File</title>');
HTP.PRINT('</head>');
HTP.PRINT('<body TEXT="#000000" BGCOLOR="#FFFFFF">');
HTP.PRINT('<h1>Heading in the HTML File</h1>');
HTP.PRINT('<p>Some text in the HTML file.');
HTP.PRINT('</body>');
HTP.PRINT('</html>');
END;
/
Passing Parameters to PL/SQL Web Applications
Submit button on the page.
Passing List and Dropdown-List Parameters from an HTML Form
<SELECT>.
Passing Option and Check Box Parameters from an HTML Form
CHECKED attribute in anINPUT tag, or include a DEFAULT clause on the parameter within the stored subprogram. When setting up a group of options, be sure to include a choice that indicates "no preference", because after selecting a option, the user can select a different one, but cannot clear the selection completely. For example, include a "Don't Care" or "Don't Know" selection along with "Yes" and "No" choices, in case someone makes a selection and then realizes it was wrong.NAME attribute comprise a check box group. If none of the check boxes in a group is checked, the stored subprogram receives a null value for the corresponding parameter.VARCHAR2 parameter.TABLE OF VARCHAR2. You must declare a type like TABLE OF VARCHAR2, or use a predefined one like OWA_UTIL.IDENT_ARR. To retrieve the values, use a loop:
CREATE OR REPLACE PROCEDURE handle_checkboxes (
checkboxes owa_util.ident_arr
) AS
BEGIN
FOR i IN 1..checkboxes.count
LOOP
htp.print('<p>Check Box value: ' || checkboxes(i));
END LOOP;
END;
/
Passing Entry-Field Parameters from an HTML Form
Back button when they enter wrong data, display a single page with an error message and the original form with all the other values filled in.<INPUT TYPE=PASSWORD>, hides the text as it is typed in.
DROP TABLE name_zip_table;
CREATE TABLE name_zip_table (
name VARCHAR2(100),
zipcode NUMBER
);
-- Store a name and associated zip code in the database.
CREATE OR REPLACE PROCEDURE associate_name_with_zipcode
(name VARCHAR2 := NULL,
zip VARCHAR2 := NULL)
AS
BEGIN
-- Each entry field must contain a value. Zip code must be 6 characters.
-- (In a real program you perform more extensive checking.)
IF name IS NOT NULL AND zip IS NOT NULL AND length(zip) = 6 THEN
INSERT INTO name_zip_table (name, zipcode) VALUES (name, zip);
HTP.PRINT('<p>The person ' || name || ' has the zip code ' || zip || '.');
-- If input was OK, stop here. User does not see form again.
RETURN;
END IF;
-- If user entered incomplete or incorrect data, show error message.
IF (name IS NULL AND zip IS NOT NULL)
OR (name IS NOT NULL AND zip IS NULL)
OR (zip IS NOT NULL AND length(zip) != 6)
THEN
HTP.PRINT('<p><b>Please reenter data. Fill all fields,
and use 6-digit zip code.</b>');
END IF;
-- If user entered no data or incorrect data, show error message
-- & make form invoke same procedure to check input values.
HTP.FORMOPEN('HR.associate_name_with_zipcode', 'GET');
HTP.PRINT('<p>Enter your name:</td>');
HTP.PRINT
('<td valign=center><input type=text name=name value="' || name || '">');
HTP.PRINT('<p>Enter your zip code:</td>');
HTP.PRINT
('<td valign=center><input type=text name=zip value="' || zip || '">');
HTP.FORMSUBMIT(NULL, 'Submit');
HTP.FORMCLOSE;
END;
/
Passing Hidden Parameters from an HTML Form
Uploading a File from an HTML Form
CLOB, BLOB, or other type that can hold large amounts of data.
Submitting a Completed HTML Form
Submit button, which transmits the data from the form to a stored subprogram or CGI program. You can label this button with text of your choice, such as "Search", "Register", and so on.Submit button. You can even have forms consisting entirely of hidden parameters, where the user makes no choice other than clicking the button.Submit button is not essential.
Handling Missing Input from an HTML Form
VALUE parameter of "" (empty quotation marks).NULL when you want to check whether the user actually specifies a value.NULL, check if it is null.
Maintaining State Information Between Web Pages
Submit button. Subsequent pages can use forms with hidden parameters (<INPUT TYPE=HIDDEN> tags) to pass these choices from one page to the next.Submit button by representing actions as hyperlinks and including any necessary name-value pairs in the query string (the part after the ? within a URL).mod_ose module. This approach lets you store state information in package variables that remain available as a user moves around a web site.
http://www.oracle.com/technetwork/indexes/documentation/index.html
Performing Network Operations in PL/SQL Subprograms
http://[2001:0db8:85a3:08d3:1319:8a2e:0370:7344]/
Sending Email from PL/SQL
UTL_SMTP package, a PL/SQL subprogram can send email, as in Example 9-11.
CREATE OR REPLACE PROCEDURE send_test_message
IS
mailhost VARCHAR2(64) := 'mailhost.example.com';
sender VARCHAR2(64) := 'me@example.com';
recipient VARCHAR2(64) := 'you@example.com';
mail_conn UTL_SMTP.CONNECTION;
BEGIN
mail_conn := UTL_SMTP.OPEN_CONNECTION(mailhost, 25); -- 25 is the port
UTL_SMTP.HELO(mail_conn, mailhost);
UTL_SMTP.MAIL(mail_conn, sender);
UTL_SMTP.RCPT(mail_conn, recipient);
UTL_SMTP.OPEN_DATA(mail_conn);
UTL_SMTP.WRITE_DATA(mail_conn, 'This is a test message.' || chr(13));
UTL_SMTP.WRITE_DATA(mail_conn, 'This is line 2.' || chr(13));
UTL_SMTP.CLOSE_DATA(mail_conn);
/* If message were in single string, open_data(), write_data(),
and close_data() could be in a single call to data(). */
UTL_SMTP.QUIT(mail_conn);
EXCEPTION
WHEN OTHERS THEN
-- Insert error-handling code here
RAISE;
END;
/
UTL_SMTP package
Getting a Host Name or Address from PL/SQL
UTL_INADDR package, a PL/SQL subprogram can determine the host name of the local system or the IP address of a given host name.
UTL_INADDR package
Using TCP/IP Connections from PL/SQL
UTL_TCP package, a PL/SQL subprogram can open TCP/IP connections to systems on the network, and read or write to the corresponding sockets.
UTL_TCP package
Retrieving HTTP URL Contents from PL/SQL
UTL_HTTP package, a PL/SQL subprogram can:UTL_HTTP package by using the functions UTL_URL.ESCAPE and UTL_URL.UNESCAPE.UTL_HTTP package to retrieve the contents of an HTTP URL.
CREATE OR REPLACE PROCEDURE show_url
(url IN VARCHAR2,
username IN VARCHAR2 := NULL,
password IN VARCHAR2 := NULL)
AS
req UTL_HTTP.REQ;
resp UTL_HTTP.RESP;
name_ VARCHAR2(256);
value_ VARCHAR2(1024);
data_ VARCHAR2(255);
my_scheme VARCHAR2(256);
my_realm VARCHAR2(256);
my_proxy BOOLEAN;
BEGIN
-- When going through a firewall, pass requests through this host.
-- Specify sites inside the firewall that do not need the proxy host.
UTL_HTTP.SET_PROXY('proxy.example.com', 'corp.example.com');
-- Ask UTL_HTTP not to raise an exception for 4xx and 5xx status codes,
-- rather than just returning the text of the error page.
UTL_HTTP.SET_RESPONSE_ERROR_CHECK(FALSE);
-- Begin retrieving this web page.
req := UTL_HTTP.BEGIN_REQUEST(url);
-- Identify yourself.
-- Some sites serve special pages for particular browsers.
UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0');
-- Specify user ID and password for pages that require them.
IF (username IS NOT NULL) THEN
UTL_HTTP.SET_AUTHENTICATION(req, username, password);
END IF;
-- Start receiving the HTML text.
resp := UTL_HTTP.GET_RESPONSE(req);
-- Show status codes and reason phrase of response.
DBMS_OUTPUT.PUT_LINE('HTTP response status code: ' || resp.status_code);
DBMS_OUTPUT.PUT_LINE
('HTTP response reason phrase: ' || resp.reason_phrase);
-- Look for client-side error and report it.
IF (resp.status_code >= 400) AND (resp.status_code <= 499) THEN
-- Detect whether page is password protected
-- and you didn't supply the right authorization.
IF (resp.status_code = UTL_HTTP.HTTP_UNAUTHORIZED) THEN
UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, my_proxy);
IF (my_proxy) THEN
DBMS_OUTPUT.PUT_LINE('Web proxy server is protected.');
DBMS_OUTPUT.PUT('Please supply the required ' || my_scheme ||
' authentication username for realm ' || my_realm ||
' for the proxy server.');
ELSE
DBMS_OUTPUT.PUT_LINE('Web page ' || url || ' is protected.');
DBMS_OUTPUT.PUT('Please supplied the required ' || my_scheme ||
' authentication username for realm ' || my_realm ||
' for the web page.');
END IF;
ELSE
DBMS_OUTPUT.PUT_LINE('Check the URL.');
END IF;
UTL_HTTP.END_RESPONSE(resp);
RETURN;
-- Look for server-side error and report it.
ELSIF (resp.status_code >= 500) AND (resp.status_code <= 599) THEN
DBMS_OUTPUT.PUT_LINE('Check if the web site is up.');
UTL_HTTP.END_RESPONSE(resp);
RETURN;
END IF;
-- HTTP header lines contain information about cookies, character sets,
-- and other data that client and server can use to customize each
-- session.
FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP
UTL_HTTP.GET_HEADER(resp, i, name_, value_);
DBMS_OUTPUT.PUT_LINE(name_ || ': ' || value_);
END LOOP;
-- Read lines until none are left and an exception is raised.
LOOP
UTL_HTTP.READ_LINE(resp, value_);
DBMS_OUTPUT.PUT_LINE(value_);
END LOOP;
EXCEPTION
WHEN UTL_HTTP.END_OF_BODY THEN
UTL_HTTP.END_RESPONSE(resp);
END;
/
BEGIN
show_url('http://www.oracle.com/no-such-page.html');
show_url('http://www.oracle.com/protected-page.html');
show_url
('http://www.oracle.com/protected-page.html','username','password');
END;
/
UTL_HTTP packageUTL_URL.ESCAPE and UTL_URL.UNESCAPE
Using Tables, Image Maps, Cookies, and CGI Variables from PL/SQL
mod_plsql plug-in of Oracle HTTP Server (OHS), a PL/SQL subprogram can format the results of a query in an HTML table, produce an image map, set and get HTTP cookies, check the values of CGI variables, and perform other typical web operations.DESCRIBE statement:
DESCRIBE HTP;
DESCRIBE HTF;
DESCRIBE OWA_UTIL;
PKҰt_ [_ PK |%A OEBPS/img_text/adfns109.htmU
1 SQL Processing for Application Developers
Description of SQL Statement Processing
employees table. You can embed this SQL statement in your program:
EXECUTE SQL UPDATE employees SET salary = 1.10 * salary
WHERE department_id = :department_id;
:department_id, which the SQL statement uses when it runs.
:department_id. The process of obtaining these values is called binding variables.
INSERT statement, the database locks no rows, because no data is changing. If the statement is an UPDATE or DELETE statement, the database locks all rows that the statement affects, until the next COMMIT, ROLLBACK, or SAVEPOINT for the transaction, thereby ensuring data integrity.ORDER BY clause, orders the rows. Each successive fetch retrieves another row of the result set, until the last row has been fetched.
Grouping Operations into Transactions
Deciding How to Group Operations in Transactions
Improving Transaction Performance
DBMS_STATS package, which lets you collect statistics in parallel, collect global statistics for partitioned objects, and fine-tune your statistics collection in other ways. For more information about this package, see Oracle Database PL/SQL Packages and Types Reference.ANALYZE. For more information about this statement, see Oracle Database SQL Language Reference.DBMS_APPLICATION_INFO procedures to record the name of the transaction in the database for later use when tracking its performance with Oracle Trace and the SQL trace facility. For information about the DBMS_APPLICATION_INFO package, see Oracle Database PL/SQL Packages and Types Reference.
Committing Transactions
COMMIT statement. These two statements are equivalent and commit the current transaction:
COMMIT WORK;
COMMIT;
COMMIT statement lets you include the COMMENT parameter with a comment that provides information about the transaction being committed. A comment is useful for including information about the origin of the transaction when you commit distributed transactions:
COMMIT COMMENT 'Dallas/Accts_pay/Trans_type 10B';
Managing Commit Redo Action
COMMIT options so that the application need not wait for the database to write data to the online redo logs.COMMIT options.
NOWAIT option, a failure that occurs after the commit message is received, but before the redo log records are written, can falsely indicate to a transaction that its changes are persistent.
COMMIT options, use either the COMMIT statement (described in Oracle Database SQL Language Reference) or the appropriate initialization parameter. For information about initialization parameters, see Oracle Database Reference.
IMMEDIATE and WAIT action for distributed transactions.OCITransCommit function in your application:OCI_TRANS_WRITEWAITOCI_TRANS_WRITENOWAITOCI_TRANS_WRITEBATCHOCI_TRANS_WRITEIMMED
OCI_TRANS_WRITENOWAIT can cause silent transaction loss with shutdown termination, startup force, and any instance or node failure. On an Oracle RAC system, asynchronously committed changes might not be immediately available to read on other instances.
OCITransCommit functionNOWAIT and BATCH options has a small window of vulnerability in which Oracle Database can roll back a transaction that your application views as committed. Your application must be able to tolerate these scenarios:
Rolling Back Transactions
ROLLBACK statement. For example, either of these statements rolls back the entire current transaction:
ROLLBACK WORK;
ROLLBACK;
WORK option of the ROLLBACK statement has no function.TO option of the ROLLBACK statement. For example, either of these statements rolls back the current transaction to the savepoint named POINT1:
SAVEPOINT Point1;
...
ROLLBACK TO SAVEPOINT Point1;
ROLLBACK TO Point1;
Defining Transaction Savepoints
SAVEPOINT statement. This statement creates the savepoint named ADD_EMP1 in the current transaction:
SAVEPOINT Add_emp1;
COMMIT or ROLLBACK statement. The number of active savepoints for each session is unlimited.COMMIT, SAVEPOINT, and ROLLBACK statements within a transaction.
SQL Statement Results
SAVEPOINT a;
DELETE...;
SAVEPOINT b;
INSERT INTO...;
SAVEPOINT c;
UPDATE...;
ROLLBACK TO c;
UPDATE statement is rolled back, savepoint C remains defined.
ROLLBACK TO b;
INSERT statement is rolled back, savepoint C is lost, savepoint B remains defined.
ROLLBACK TO c;
INSERT INTO...;
COMMIT;
DELETE statement) and the last DML statement (the second INSERT statement).COMMIT. The savepoint A is no longer active.
Ensuring Repeatable Reads with Read-Only Transactions
SET TRANSACTION READ ONLY [ NAME string ];
SET TRANSACTION READ ONLY statement. After the SET TRANSACTION READ ONLY statement successfully runs, the transaction can include only SELECT (without FOR UPDATE), COMMIT, ROLLBACK, or non-DML statements (such as SET ROLE, ALTER SYSTEM, and LOCK TABLE). A COMMIT, ROLLBACK, or DDL statement ends the read-only transaction.
SET TRANSACTION statementUNDO_RETENTION. For example, if UNDO_RETENTION is set to 30 minutes, then the database retains all committed undo information for at least 30 minutes, ensuring that all queries running for 30 minutes or less do not encounter the OER error "snapshot too old."
Using Cursors
How Many Cursors Can a Session Have?
OPEN_CURSORS, described in Oracle Database Reference
Using a Cursor to Reexecute a Statement
V$SQL dynamic performance view to display the text of the associated query (see Oracle Database Reference). Because the results of EXPLAIN PLAN for the original query might differ from the way the database actually processes the query, the DBA can get more precise information by examining these dynamic performance views:
View Description V$SQL_PLANExecution plan information for each child cursor loaded in the library cache. For more information, see Oracle Database Reference. V$SQL_PLAN_STATISTICSExecution statistics at the row source level for each child cursor. For more information, see Oracle Database Reference. V$SQL_PLAN_STATISTICS_ALLMemory usage statistics for row sources that use SQL memory (sort or hash-join). This view concatenates information in V$SQL_PLAN with execution statistics from V$SQL_PLAN_STATISTICS and V$SQL_WORKAREA. For more information, see Oracle Database Reference.
Scrollable Cursors
Closing a Cursor
Canceling a Cursor
OCIStmtFetch2 statement
Locking Tables Explicitly
LOCK TABLE (described in Oracle Database SQL Language Reference)SELECT with the FOR UPDATE clause (described in Oracle Database SQL Language Reference)SET TRANSACTION with the READ ONLY or ISOLATION LEVEL SERIALIZABLE option (described in Oracle Database SQL Language Reference)
ISOLATION_LEVEL parameter of the ALTER SESSION statementDML_LOCKS (described in Oracle Database Reference) determines the maximum number of DML locks. Although its default value is usually enough, you might need to increase it if you use explicit locks.
Privileges Required to Acquire Table Locks
LOCK ANY TABLE system privilege or any object privilege (for example, SELECT or UPDATE) for the table.
Choosing a Locking Strategy
LOCK TABLE statement is executed. A LOCK TABLE statement explicitly overrides default locking. When a LOCK TABLE statement is issued on a view, the underlying base tables are locked. This statement acquires exclusive table locks for the employees and departments tables on behalf of the containing transaction:
LOCK TABLE employees, departments
IN EXCLUSIVE MODE NOWAIT;
LOCK TABLE statement.
LOCK TABLE statement, you can also indicate how long you want to wait for the table lock:NOWAIT or WAIT 0.WAIT n, where n is greater than 0 and less than or equal to 100000.NOWAIT nor WAIT.
When to Lock with ROW SHARE MODE and ROW EXCLUSIVE MODE
ROW SHARE MODE and ROW EXCLUSIVE MODE table locks offer the highest degree of concurrency. You might use these locks if:
When to Lock with SHARE MODE
SHARE MODE table locks are rather restrictive data locks. You might use these locks if:SHARE MODE locks on the table either commit or roll back.SHARE MODE table locks on the same table, also giving them the option of transaction-level read consistency.
SELECT FOR UPDATE statement). Therefore, if concurrent share table locks on the same table are common, updates cannot proceed and deadlocks are common. In this case, use share row exclusive or exclusive table locks instead.employees and budget_tab require a consistent set of data in a third table, departments. For a given department number, you want to update the information in employees and budget_tab, and ensure that no members are added to the department between these two transactions.departments table in SHARE MODE, as shown in Example 1-1. Because the departments table is rarely updated, locking it probably does not cause many other transactions to wait long.
-- Create and populate table:
DROP TABLE budget_tab;
CREATE TABLE budget_tab (
sal NUMBER(8,2),
deptno NUMBER(4)
);
INSERT INTO budget_tab (sal, deptno)
SELECT salary, department_id
FROM employees;
-- Lock departments and update employees and budget_tab:
LOCK TABLE departments IN SHARE MODE;
UPDATE employees
SET salary = salary * 1.1
WHERE department_id IN
(SELECT department_id FROM departments WHERE location_id = 1700);
UPDATE budget_tab
SET sal = sal * 1.1
WHERE deptno IN
(SELECT department_id FROM departments WHERE location_id = 1700);
COMMIT; -- COMMIT releases lock
When to Lock with SHARE ROW EXCLUSIVE MODE
SHARE ROW EXCLUSIVE MODE table lock if:SELECT FOR UPDATE), which might make UPDATE and INSERT statements in the locking transaction wait and might cause deadlocks.
When to Lock with EXCLUSIVE MODE
EXCLUSIVE MODE table if:
Letting Oracle Database Control Table Locking
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE or ALTER SESSION ISOLATION LEVEL SERIALIZABLE preserves ANSI serializability without changing the underlying locking protocol. This technique gives concurrent access to the table while providing ANSI serializability. Getting table locks greatly reduces concurrency.
SET TRANSACTION statementALTER SESSION statements
Explicitly Acquiring Row Locks
SELECT statement that includes the FOR UPDATE clause. This statement acquires exclusive row locks for selected rows (as an UPDATE statement does), in anticipation of updating the selected rows in a subsequent statement.SELECT FOR UPDATE statement to lock a row without actually changing it. For example, several triggers in Oracle Database PL/SQL Language Reference show how to implement referential integrity. In the EMP_DEPT_CHECK trigger, the row that contains the referenced parent key value is locked to guarantee that it remains for the duration of the transaction; if the parent key is updated or deleted, referential integrity is violated.SELECT FOR UPDATE statements are often used by interactive programs that enable a user to modify fields of one or more specific rows (which might take some time); row locks are acquired so that only a single interactive program user is updating the rows at any given time.SELECT FOR UPDATE statement is used when defining a cursor, the rows in the return set are locked when the cursor is opened (before the first fetch) rather than being locked as they are fetched from the cursor. Locks are only released when the transaction that opened the cursor is committed or rolled back, not when the cursor is closed.SELECT FOR UPDATE statement is locked individually; the SELECT FOR UPDATE statement waits until the other transaction releases the conflicting row lock. If a SELECT FOR UPDATE statement locks many rows in a table, and if the table experiences a lot of update activity, it might be faster to acquire an EXCLUSIVE table lock instead.
SELECT FOR UPDATE might change while the query is running; for example, if columns selected by the query are updated or rows are deleted after the query started. When this happens, SELECT FOR UPDATE acquires locks on the rows that did not change, gets a read-consistent snapshot of the table using these locks, and then restarts the query to acquire the remaining locks.
SELECT FOR UPDATE statement waits until the requested row lock is acquired. To change this behavior, use the NOWAIT, WAIT, or SKIP LOCKED clause of the SELECT FOR UPDATE statement. For information about these clauses, see Oracle Database SQL Language Reference.
Examples of Concurrency Under Explicit Locking
LOCK TABLE statement and the SELECT statement with the FOR UPDATE clause are used. For brevity, the message text for ORA-00054 ("resource busy and acquire with NOWAIT specified") is not included. User-entered text is bold.
Transaction 1 Time Point Transaction 2
LOCK TABLE hr.departments
IN ROW SHARE MODE;
Statement processed.
DROP TABLE hr.departments;
DROP TABLE hr.departments
*
ORA-00054
LOCK TABLE hr.departments
IN EXCLUSIVE MODE
NOWAIT;
ORA-00054
SELECT location_id
FROM hr.departments
WHERE department_id = 20
FOR UPDATE OF location_id;
LOCATION_ID
-----------
DALLAS
1 row selected.
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
ROLLBACK;
1 row processed.
ROLLBACK;
LOCK TABLE hr.departments
IN ROW EXCLUSIVE MODE;
Statement processed.
LOCK TABLE hr.departments
IN EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
1 row processed.
ROLLBACK;
SELECT location_id
FROM hr.departments
WHERE department_id = 20
FOR UPDATE OF location_id;
LOCATION_ID
-----------
DALLAS
1 row selected.
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
1 row processed.
ROLLBACK;
1 row processed.
ROLLBACK;
LOCK TABLE hr.departments
IN ROW SHARE MODE
Statement processed.
LOCK TABLE hr.departments
IN EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE MODE;
Statement processed.
SELECT location_id
FROM hr.departments
WHERE department_id = 20;
LOCATION_ID
-----------
DALLAS
1 row selected.
SELECT location_id
FROM hr.departments
WHERE department_id = 20
FOR UPDATE OF location_id;
LOCATION_ID
-----------
DALLAS
1 row selected.
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
ROLLBACK;
1 row processed.
ROLLBACK;
LOCK TABLE hr.departments
IN SHARE ROW EXCLUSIVE MODE;
Statement processed.
LOCK TABLE hr.departments
IN EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE MODE
NOWAIT;
ORA-00054
SELECT location_id
FROM hr.departments
WHERE department_id = 20;
LOCATION_ID
-----------
DALLAS
1 row selected.
SELECT location_id
FROM hr.departments
WHERE department_id = 20
FOR UPDATE OF location_id;
LOCATION_ID
-----------
DALLAS
1 row selected.
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 20;
Cancel operation.
ROLLBACK;
1 row processed.
LOCK TABLE hr.departments
IN EXCLUSIVE MODE;
LOCK TABLE hr.departments
IN EXCLUSIVE MODE;
ORA-00054
LOCK TABLE hr.departments
IN ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN SHARE MODE;
ORA-00054
LOCK TABLE hr.departments
IN ROW EXCLUSIVE MODE
NOWAIT;
ORA-00054
LOCK TABLE hr.departments
IN ROW SHARE MODE
NOWAIT;
ORA-00054
SELECT location_id
FROM hr.departments
WHERE department_id = 20;
LOCATION_ID
-----------
DALLAS
1 row selected.
SELECT location_id
FROM hr.departments
WHERE department_id = 20
FOR UPDATE OF location_id;
UPDATE hr.departments
SET department_id = 30
WHERE department_id = 20;
1 row processed.
COMMIT;
0 rows selected.
SET TRANSACTION READ ONLY;
SELECT location_id
FROM hr.departments
WHERE department_id = 10;
LOCATION_ID
-----------
BOSTON
UPDATE hr.departments
SET location_id = 'NEW YORK'
WHERE department_id = 10;
1 row processed.
SELECT location_id
FROM hr.departments
WHERE department_id = 10;
LOCATION_ID
-----------
BOSTON
COMMIT;
SELECT location_id
FROM hr.departments
WHERE department_id = 10;
LOCATION_ID
-----------
BOSTON
COMMIT;
SELECT location_id
FROM hr.departments
WHERE department_id = 10;
LOCATION_ID
-----------
NEW YORK
Using Oracle Lock Management Services (User Locks)
DBMS_LOCK package. An application can request a lock of a specific mode, give it a unique name (recognizable in another subprogram in the same or another instance), change the lock mode, and release it. Because a reserved user lock is an Oracle Database lock, it has all the features of a database lock, such as deadlock detection. Ensure that any user locks used in distributed transactions are released upon COMMIT, otherwise an undetected deadlock can occur.
DBMS_LOCK package
When to Use User Locks
******************************************************************
* Print Check *
* Any cashier may issue a refund to a customer returning goods. *
* Refunds under $50 are given in cash, more than $50 by check. *
* This code prints the check. One printer is opened by all *
* the cashiers to avoid the overhead of opening and closing it *
* for every check, meaning that lines of output from multiple *
* cashiers can become interleaved if you do not ensure exclusive *
* access to the printer. The DBMS_LOCK package is used to *
* ensure exclusive access. *
******************************************************************
CHECK-PRINT
* Get the lock "handle" for the printer lock.
MOVE "CHECKPRINT" TO LOCKNAME-ARR.
MOVE 10 TO LOCKNAME-LEN.
EXEC SQL EXECUTE
BEGIN DBMS_LOCK.ALLOCATE_UNIQUE ( :LOCKNAME, :LOCKHANDLE );
END; END-EXEC.
* Lock the printer in exclusive mode (default mode).
EXEC SQL EXECUTE
BEGIN DBMS_LOCK.REQUEST ( :LOCKHANDLE );
END; END-EXEC.
* You now have exclusive use of the printer, print the check.
...
* Unlock the printer so other people can use it
EXEC SQL EXECUTE
BEGIN DBMS_LOCK.RELEASE ( :LOCKHANDLE );
END; END-EXEC.
Viewing and Monitoring Locks
Tool Description
UTLLOCKT.SQL
UTLLOCKT.SQL script displays a simple character lock wait-for graph in tree structured fashion. Using any SQL tool (such as SQL*Plus) to run the script, it prints the sessions in the system that are waiting for locks and the corresponding blocking locks. The location of this script file is operating system dependent. (You must have run the CATBLOCK.SQL script before using UTLLOCKT.SQL.)
Using Serializable Transactions for Concurrency Control
SELECT FOR UPDATE statement), then the DML statement that A issued waits until B either commits or rolls back the transaction. This concurrency model, which provides higher concurrency and thus better performance, is appropriate for most applications.
Transaction Interaction and Isolation Level
Isolation Level Dirty Read Unrepeatable Read Phantom Read
Isolation Level Provided by Oracle Database
READ COMMITTED isolation requires.
SERIALIZABLE.
SERIALIZABLE.SERIALIZABLE or READ COMMITTED) interacts with a serializable transaction.
Description of "Figure 1-1 Interaction Between Serializable Transaction and Another Transaction"
Setting Isolation Levels
ALTER SESSION statement, described in Oracle Database SQL Language Reference.ISOLATION LEVEL clause of the SET TRANSACTION statement. The SET TRANSACTION statement, described in Oracle Database SQL Language Reference, must be the first statement in the transaction.
SERIALIZABLE, then you must use the ALTER TABLE statement to set the INITRANS parameter to at least 3. Use higher values for tables for which many transactions update the same blocks. For more information about INITRANS, see Oracle Database SQL Language Reference.
Serializable Transactions and Referential Integrity
SERIALIZABLE transactions, data read by one transaction can be overwritten by another. Therefore, transactions that perform database consistency checks at the application level must not assume that the data they read does not change during the transaction (even though such changes are invisible to the transaction). Code your application-level consistency checks carefully, even when using SERIALIZABLE transactions.READ COMMITTED or SERIALIZABLE) perform application-level checks to maintain the referential integrity of the parent/child relationship between two tables. Transaction A queries the parent table to check that it has a row with a specific primary key value before inserting corresponding child rows into the child table. Transaction B queries the child table to check that no child rows exist for a specific primary key value before deleting the corresponding parent row from the parent table. Both transactions assume (but do not ensure) that the data they read does not change before the transaction completes.SERIALIZABLE transactions, because neither transaction prevents the other from changing the data that it reads to check consistency.SERIALIZABLE isolation level provides. However, in Oracle Database:SELECT FOR UPDATE statement to query and lock the parent row, thereby preventing transaction B from deleting it.FOR UPDATE clause of the SELECT statement, see Oracle Database SQL Language Reference.BEFORE INSERT trigger that does this:SELECT FOR UPDATE statement, thereby ensuring that if the parent row exists, then it remains in the database for the duration of the transaction that inserts the child rows.
READ COMMITTED transaction runs the triggering statement, then the triggered statements see the database as it was when the triggering statement began to execute. If a SERIALIZABLE transaction runs the triggering statement, then the triggered statements see the database as it was at the beginning of the transaction. In either case, using SELECT FOR UPDATE in the trigger correctly enforces referential integrity.
READ COMMITTED and SERIALIZABLE Isolation Levels
READ COMMITTED and SERIALIZABLE. Both levels provide a high degree of consistency and concurrency, reduce contention, and are designed for real-world applications. This topic compares them and explains how to choose between them.
Transaction Set Consistency Differences
Oracle Database
READ COMMITTED isolation level are transaction set consistent on an individual-statement basis, because all rows that a query reads must be committed before the query begins.SERIALIZABLE isolation level are transaction set consistent on an individual-transaction basis, because all statements in a SERIALIZABLE transaction run on an image of the database as it was at the beginning of the transaction.
Other Database Systems
READ UNCOMMITTED isolation level is not transaction set consistent, because it might see only a subset of the changes made by another transaction. For example, a join of a master table with a detail table can see a master record inserted by another transaction, but not the corresponding details inserted by that transaction (or the reverse). READ COMMITTED isolation level avoids this problem, providing more consistency than read-locking systems do.REPEATABLE READ isolation level provides transaction set consistency at the statement level, but not at the transaction level. Due to the absence of phantom read protection, two queries in the same transaction can see data committed by different sets of transactions. In these systems, only the throughput-limiting and deadlock-susceptible SERIALIZABLE isolation level provides transaction set consistency at the transaction level.
Choosing Transaction Isolation Levels
READ COMMITTED isolation can provide considerably more concurrency with a somewhat increased risk of inconsistent results (from unrepeatable and phantom reads) for some transactions.SERIALIZABLE isolation provides somewhat more consistency (by protecting against phantoms and unrepeatable reads), which might be important where a read/write transaction runs a query more than once. However, SERIALIZABLE isolation requires applications to check for the "cannot serialize access" error, and this checking can significantly reduce throughput in an environment with many concurrent transactions accessing the same data for update.READ COMMITTED or SERIALIZABLE transactions.READ COMMITTED and SERIALIZABLE transactions.
Operation READ COMMITTED SERIALIZABLE
Autonomous Transactions
AUTONOMOUS_TRANSACTION pragma. For the definition of routine in this context, see Oracle Database PL/SQL Language Reference.COMMIT and ROLLBACK end the active autonomous transaction but do not exit the autonomous transaction. As Figure 1-3 shows, when one transaction ends, the next SQL statement begins another transaction.
Description of "Figure 1-4 Possible Sequences of Autonomous Transactions"
Examples of Autonomous Transactions
Autonomous Transaction Main Transaction
Ordering a Product
Withdrawing Money from a Bank Account
Scenario 1: Sufficient Funds
Description of "Figure 1-6 Bank Withdrawal—Sufficient Funds"
Scenario 2: Insufficient Funds with Overdraft Protection
Description of "Figure 1-7 Bank Withdrawal—Insufficient Funds with Overdraft Protection"
Scenario 3: Insufficient Funds Without Overdraft Protection
Description of "Figure 1-8 Bank Withdrawal—Insufficient Funds Without Overdraft Protection"
Defining Autonomous Transactions
PRAGMA AUTONOMOUS_TRANSACTION, which instructs the PL/SQL compiler to mark the subprogram as autonomous.balance is autonomous.
-- Create table for package to use:
DROP TABLE accounts;
CREATE TABLE accounts (account INTEGER, balance REAL);
-- Create package:
CREATE OR REPLACE PACKAGE banking AS
FUNCTION balance (acct_id INTEGER) RETURN REAL;
-- Additional functions and packages
END banking;
/
CREATE OR REPLACE PACKAGE BODY banking AS
FUNCTION balance (acct_id INTEGER) RETURN REAL IS
PRAGMA AUTONOMOUS_TRANSACTION;
my_bal REAL;
BEGIN
SELECT balance INTO my_bal FROM accounts WHERE account=acct_id;
RETURN my_bal;
END;
-- Additional functions and packages
END banking;
/
PRAGMA AUTONOMOUS_TRANSACTION
Resuming Execution After Storage Allocation Errors
What Operations Have Resumable Storage Allocation?
OCIStmtExecute.
Handling Suspended Storage Allocation
AFTER SUSPEND trigger or the DBA must periodically check for suspended statements.SERVERERROR exception.
Using an AFTER SUSPEND Trigger in the Application
AFTER SUSPEND trigger can get information about the problem by invoking subprograms in the DBMS_RESUMABLE package (described in Oracle Database PL/SQL Packages and Types Reference). Then the trigger can send the information to an operator, using email (for example).SYSTEM tablespace. If the trigger encounters a deadlock condition because of locks held by the suspended statement, then the trigger terminates and the application receives the original error code, as if the statement were never suspended. If the trigger encounters an out-of-space condition, then both the trigger and the suspended statement are rolled back. To prevent rollback, use an exception handler in the trigger to wait for the statement to resume.SYSDBA.
-- Create table used by trigger body
DROP TABLE rbs_error;
CREATE TABLE rbs_error (
SQL_TEXT VARCHAR2(64),
ERROR_MSG VARCHAR2(64),
SUSPEND_TIME VARCHAR2(64)
);
-- Resumable Storage Allocation
CREATE OR REPLACE TRIGGER suspend_example
AFTER SUSPEND
ON DATABASE
DECLARE
cur_sid NUMBER;
cur_inst NUMBER;
err_type VARCHAR2(64);
object_owner VARCHAR2(64);
object_type VARCHAR2(64);
table_space_name VARCHAR2(64);
object_name VARCHAR2(64);
sub_object_name VARCHAR2(64);
msg_body VARCHAR2(64);
ret_value BOOLEAN;
error_txt VARCHAR2(64);
mail_conn UTL_SMTP.CONNECTION;
BEGIN
SELECT DISTINCT(SID) INTO cur_sid FROM V$MYSTAT;
cur_inst := USERENV('instance');
ret_value := DBMS_RESUMABLE.SPACE_ERROR_INFO
(err_type,
object_owner,
object_type,
table_space_name,
object_name,
sub_object_name);
IF object_type = 'ROLLBACK SEGMENT' THEN
INSERT INTO rbs_error
(SELECT SQL_TEXT, ERROR_MSG, SUSPEND_TIME
FROM DBA_RESUMABLE
WHERE SESSION_ID = cur_sid
AND INSTANCE_ID = cur_inst);
SELECT ERROR_MSG INTO error_txt
FROM DBA_RESUMABLE
WHERE SESSION_ID = cur_sid
AND INSTANCE_ID = cur_inst;
msg_body :=
'Space error occurred: Space limit reached for rollback segment '
|| object_name || ' on ' || to_char(SYSDATE, 'Month dd, YYYY, HH:MIam')
|| '. Error message was: ' || error_txt;
mail_conn := UTL_SMTP.OPEN_CONNECTION('localhost', 25);
UTL_SMTP.HELO(mail_conn, 'localhost');
UTL_SMTP.MAIL(mail_conn, 'sender@localhost');
UTL_SMTP.RCPT(mail_conn, 'recipient@localhost');
UTL_SMTP.DATA(mail_conn, msg_body);
UTL_SMTP.QUIT(mail_conn);
DBMS_RESUMABLE.ABORT(cur_sid);
ELSE
DBMS_RESUMABLE.SET_TIMEOUT(3600*8);
END IF;
COMMIT;
END;
/
Checking for Suspended Statements
AFTER SUSPEND trigger, then the DBA must periodically check for suspended statements, using the static data dictionary view DBA_RESUMABLE (described in Oracle Database Reference).V$_SESSION_WAIT (described in Oracle Database Reference).
PKy` PK |%A OEBPS/img_text/adfns065.htmA
PK,.! PK |%A OEBPS/img_text/adfns062.htm5
PROCEDURE fire_emp (empid NUMBER) IS
invalid_empid EXCEPTION
PRAGMA EXCEPTION_INIT (invalid_empid, -20101);
BEGIN
DELETE FROM emp WHERE empno = empid;
EXCEPTION
WHEN invlid_empid THEN
INSERT INTO emp_audit
VALUES (empid, 'Fired before probation ended');
END;
TRIGGER emp_probation
BEFORE DELETE ON emp
FOR EACH ROW
BEGIN
IF (sysdate - :old.hiredate) < 30 THEN
raise_application_error(20101,
'Employee' || old.ename || ' on probation')
END IF;
END;
PK!: 5 PK |%A OEBPS/img_text/adfns057.htm]
PK* b ] PK |%A OEBPS/img_text/adfns104.htmE
PKiU PK |%A OEBPS/img_text/adfns091.htmY
PKn 5* % PK |%A OEBPS/img_text/adfns063.htmu
PK _ PK |%A OEBPS/img_text/adfns089.htm
PKhb| PK |%A OEBPS/img_text/adfns090.htmY
Table DEPARTMENTS
DEPTNO DNAME LOC
------ ----- --------
20 RESEARCH DALLAS
30 SALES NEW YORK
40 MARKETING BOSTON
Table EMPLOYEES
EMPNO ENAME JOB MGR HIREDATE SAL COMM DEPTNO COMMENT
----- ----- -------- ---- --------- -------- ------ ------ -------
7329 SMITH CEO N/A 17-DEC-85 9,000.00 N/A 20
7499 ALLEN VP-SALES 7329 20-FEB-90 7,500.00 100.00 30
7521 WARD MANAGER 7499 22-FEB-90 5,000.00 200.00 30
7586 JONES SALESMAN 7521 02-APR-90 2,975.00 400.00 20
7571 FORD MANAGER 7499 23-FEB-90 5,000.00 200.00 50 1
7571 FORD MANAGER 7499 23-FEB-90 5,000.00 200.00 N/A 2
PK{+ PK |%A OEBPS/img_text/adfns102.htm
PKs9 PK |%A OEBPS/img_text/adfns039.htm5
HTP.Print generate Web pages dynamically. A generated Web page varies depending on the database contents and the input parameters.
DEPNO DNAME LOC
----- --------- --------
20 RESEARCH DALLAS
30 SALES NEW YORK
40 MARKETING BOSTON
- UNIQUE -
DEPNO DNAME LOC COMMENTS
----- ----- -------- --------
50 SALES NEW YORK 1
60 N/A BOSTON 2
PKډ PK |%A OEBPS/img_text/adfns092.htm
PK3 PK |%A OEBPS/img_text/adfns108.htmM
PK"* PK |%A OEBPS/adfns_flashback.htm
A Multithreaded extproc Agent
extproc agent is, how it contributes to the overall efficiency of a distributed database system, and how to administer it.
Why Use the Multithreaded extproc Agent?
extproc agent contributes to the efficiency of external procedures.
The Challenge of Dedicated Agent Architecture
extproc agent is started for each user session and the extproc agent process terminates only when the user session ends.extproc agent processes. Because an extproc agent process is started for each session, several thousand extproc agent processes run concurrently. The extproc agent processes operate regardless of whether each individual extproc agent process is active at the moment. Thus extproc agent processes and open connections can consume a disproportionate amount of system resources. When sessions connect to Oracle Database, this problem is addressed by starting the server in shared server mode. Shared server mode allows database connections to be shared by a small number of server processes.
The Advantage of Multithreading
extproc agent provides similar functionality for connections to external procedures. The multithreaded extproc agent architecture uses a pool of shared agent threads. The tasks requested by the user sessions are put in a queue and are picked up by the first available multithreaded extproc agent thread. Because only a small percentage of user connections are active at a given moment, using a multithreaded extproc architecture allows more efficient use of system resources.
Multithreaded extproc Agent Architecture
extproc agent must be started for each system identifier (SID) before attempting to connect to the external procedure. This is done using the agent control utility agtctl. This utility is also used to configure the agent and to shut down the agent.extproc agent was started for the SID, then the listener passes the request to that extproc agent.extproc agents, each incoming connection request is processed by different kinds of threads:extproc agent. User sessions 1 and 2 issue requests for callouts to functions in some DLLs. These requests get serviced through heterogeneous services to the multithreaded extproc agent. These requests get handled by the agent's dispatcher threads, which then pass them on to the task threads. The task thread that is actually handling a request is responsible for loading the respective DLL and calling the function therein.
Description of "Figure A-1 Multithreaded extproc Agent Architecture"
exproc agent by using the agent control utility agtctl
Monitor Thread
agtctl starts a multithreaded extproc agent for a SID, agtctl creates the monitor thread. The monitor thread performs these functions:extproc agent. While the dispatcher for this SID is running, the listener does not start a process when it gets an incoming connection. Instead, the listener gives the connection to this same dispatcher.extproc agent, enabling listeners to give incoming connections to the least loaded dispatcher.
Dispatcher Threads
Task Threads
Administering the Multithreaded extproc Agent
extproc agent must be started for each system identifier (SID) before attempting to connect to the external procedure.extproc agent is started, stopped, and configured by an agent control utility called agtctl, which works like lsnrctl. However, unlike lsnrctl, which reads a configuration file (listener.ora), agtctl takes configuration information from the command line and writes it to a control file.agtctl, ensure that Oracle Listener is running. Then use the agtctl commands to set the agtctl configuration parameters (if you do not want their default values) and to start agtctl, as in Example A-1.
agtctl set max_dispatchers 2 ep_agt1
agtctl set tcp_dispatchers 1 ep_agt1
agtctl set max_task_threads 2 ep_agt1
agtctl set max_sessions 5 ep_agt1
agtctl unset listener_address ep_agt1
agtctl set listener_address "(address=(protocol=ipc)(key=extproc))" ep_agt1
agtctl startup extproc ep_agt1
agtctl commands in either single-line command mode or shell mode.
Agent Control Utility (agtctl) Commands
agtctl and create and maintain its control file by using the commands shown in Table A-1.
Command Description
startup
extproc agent
shutdown
extproc agent
set
extproc agent
unset
show
delete
exit
help
agtctl and an AGTCTL> prompt appears. You then can enter commands from within the agtctl shell. This mode is called shell mode.agtctl commands depend on the mode in which they are issued.
agtctl utility puts its control file in the directory specified by either one of two environment variables, AGTCTL_ADMIN or TNS_ADMIN. Ensure that at least one of these environment variables is set and that it specifies a directory to which the agent has access.extproc agent requires that an environment variable be set, or if the ENVS parameter was used when configuring the listener.ora entry for the agent working in dedicated mode, then all required environment variables must be set in the UNIX or DOS shell that runs the agtctl utility.
Using agtctl in Single-Line Command Mode
agtctl commands. They are presented in single-line command mode.
Setting Configuration Parameters for a Multithreaded extproc Agent
extproc agent before you start the agent. If a configuration parameter is not specifically set, a default value is used. Configuration parameters and their default values are shown in Table A-2.set command to set multithreaded extproc agent configuration parameters.
agtctl set parameter parameter_value agent_sid
parameter is the parameter that you are setting.parameter_value is the value being assigned to that parameter.agent_sid is the SID that this agent services. This must be specified for single-line command mode.
agtctl set max_dispatchers 5 salesDB
Starting a Multithreaded extproc Agent
startup command to start a multithreaded extproc agent.
agtctl startup extproc agent_sid
agent_sid is the SID that this multithreaded extproc agent services. This must be specified for single-line command mode.
agtctl startup extproc salesDB
Shutting Down a Multithreaded extproc Agent
shutdown command to stop a multithreaded extproc agent. There are three forms of shutdown:agtctl asks the multithreaded extproc agent to terminate itself gracefully. All sessions complete their current operations and then shut down.agtctl tells the multithreaded extproc agent to terminate immediately. The agent exits immediately regardless of the state of current sessions.extproc agent, agtctl issues a system call to stop it.
agtctl shutdown [immediate|abort] agent_sid
agent_sid is the SID that the multithreaded extproc agent services. It must be specified for single-line command mode.
agtctl shutdown immediate salesDB
Examining the Value of Configuration Parameters
show command.
agtctl show parameter agent_sid
parameter is the parameter that you are examining.agent_sid is the SID that this multithreaded extproc agent services. This must be specified for single-line command mode.
agtctl show max_dispatchers salesDB
Resetting a Configuration Parameter to Its Default Value
unset command.
agtctl unset parameter agent_sid
parameter is the parameter that you are resetting (or changing).agent_sid is the SID that this multithreaded extproc agent services. It must be specified for single-line command mode.
agtctl unset max_dispatchers salesDB
Deleting an Entry for a Specific SID from the Control File
delete command deletes the entry for the specified SID from the control file.
agtctl delete agent_sid
agent_sid is the SID entry to delete.
agtctl delete salesDB
Using Shell Mode Commands
agtctl by entering:
agtctl
AGTCTL>. Thereafter, because you are issuing commands from within the agtctl shell, you need not prefix the command string with agtctl.
AGTCTL> set agent_sid agent_sid
agent_sid value is changed. Unlike single-line command mode, you do not specify agent_sid in the command string.
AGTCTL> set language language
exit.
Example: Setting a Configuration Parameter
shutdown_address configuration parameter.
AGTCTL> set shutdown_address (address=(protocol=ipc)(key=oraDBsalesDB))
Configuration Parameters for Multithreaded extproc Agent Control
Parameter Description Default Value
max_dispatchers
tcp_dispatchers
max_task_threads
max_sessions
listener_address
(ADDRESS_LIST=
(ADDRESS=
(PROTOCOL=IPC)
(KEY=PNPKEY))
(ADDRESS=
(PROTOCOL=IPC)
(KEY=listener_sid))
(ADDRESS=
(PROTOCOL=TCP)
(HOST=127.0.0.1)
(PORT=1521)))
listener_sid is the IPC key of the address, on the Oracle Database, on which the listener is listening.
shutdown_address
agtctl.
(ADDRESS=
(PROTOCOL=IPC)
(KEY=listener_sid || agent_sid))
(ADDRESS=
(PROTOCOL=TCP)
(HOST=127.0.0.1)
(PORT=1521))
agent_sid is the SID of the multithreaded extproc agent.listener_sid and agent_sid are concatenated into one string.max_dispatchers, tcp_dispatchers, max_task_threads, and max_sessions.max_dispatchers, tcp_dispatchers, max_task_threads with these formulas:
max_dispatchers = CEIL(x/y)
tcp_dispatchers = CEIL(x_tcpip/y)
max_task_threads = CEIL(x/max_sessions)
CEIL is a SQL function that returns the smallest integer greater than or equal to its argument.x is the maximum number of sessions that can be connected to extproc concurrently.y is the maximum number of connections that the system can support for each dispatcher.x_tcpip is the maximum number of sessions that can be connected to extproc concurrently by TCP/IP.x - x_tcpip is the maximum number of sessions that can be connected to extproc concurrently by IPC.)max_sessions, which affects max_task_threads.max_dispatchers must be at least 1 (which is the default).extproc concurrently (x) is 650.extproc concurrently by TCP/IP (x_tcpip) is 400.extproc concurrently by IPC is 650-400=250.)y) is 100.max_sessions) is 20.
max_dispatchers = CEIL(650/100) = CEIL(6.5) = 7
tcp_dispatchers = CEIL(400/100) = CEIL(4) = 4
max_task_threads = CEIL(650/20) = CEIL(32.5) = 33
listener_address and shutdown_address are specified with ADDRESS, as shown in both Table A-2 and Example A-1. Within ADDRESS, you can specify the parameter HOST, which can be either an IPv6 or IPv4 address or a host name. If HOST is a host name, then these values of the optional ADDRESS parameter IP are relevant:
IP Value Meaning FIRSTListen on the first IP address returned by the DNS resolution of the host name. V4_ONLYListen only on the IPv4 interfaces in the system. V6_ONLYListen only on the IPv6 interfaces in the system. listener_address or shutdown_address restricts it to IPv6 interfaces:
"(ADDRESS=(PROTOCOL=tcp)(HOST=sales)(PORT=1521)(IP=V6_ONLY))"
PKҸ
. PK |%A
OEBPS/toc.ncxP
12 Using Oracle Flashback Technology
Overview of Oracle Flashback Technology
UPDATE statement to change a salary from 1000 to 1100, then Oracle Database stores the value 1000 in the undo data.
Application Development Features
AS OF clause of the SELECT statement. For more information, see "Using Oracle Flashback Query (SELECT AS OF)".VERSIONS BETWEEN clause of the SELECT statement. For more information, see "Using Oracle Flashback Version Query".FLASHBACK_TRANSACTION_QUERY. For more information, see "Using Oracle Flashback Transaction Query".DBMS_FLASHBACK package.) For more information, see "Using DBMS_FLASHBACK Package".
Database Administration Features
DROP TABLE statement.
Configuring Your Database for Oracle Flashback Technology
Configuring Your Database for Automatic Undo Management
UNDO_MANAGEMENTUNDO_TABLESPACEUNDO_RETENTIONUNDO_RETENTION parameter.
V$UNDOSTAT.TUNED_UNDORETENTION to determine the amount of time for which undo is retained for the current undo tablespace. For more information about V$UNDOSTAT, see Oracle Database Reference.UNDO_RETENTION does not guarantee that unexpired undo data is not discarded. If the system needs more space, Oracle Database can overwrite unexpired undo with more recently generated undo data.RETENTION GUARANTEE clause for the undo tablespace to ensure that unexpired undo data is not discarded.
Configuring Your Database for Oracle Flashback Transaction Query
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
Configuring Your Database for Flashback Transaction
ARCHIVELOG:
ALTER DATABASE ARCHIVELOG;
ALTER SYSTEM ARCHIVE LOG CURRENT;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (FOREIGN KEY) COLUMNS;
Enabling Oracle Flashback Operations on Specific LOB Columns
ALTER TABLE statement with the RETENTION option.
RETENTION parameter
Granting Necessary Privileges
GRANT statement, see Oracle Database SQL Language Reference.FLASHBACK and SELECT privileges on those objects.FLASHBACK ANY TABLE privilege.SELECT ANY TRANSACTION privilege.SELECT, UPDATE, DELETE, and INSERT privileges for specific tables.DBMS_FLASHBACK package, grant the EXECUTE privilege on DBMS_FLASHBACK.FLASHBACK ARCHIVE object privilege on that Flashback Data Archive to that user. To grant the FLASHBACK ARCHIVE object privilege, you must either be logged on as SYSDBA or have FLASHBACK ARCHIVE ADMINISTER system privilege.FLASHBACK ARCHIVE ADMINISTER system privilege:CREATE FLASHBACK ARCHIVEALTER FLASHBACK ARCHIVEDROP FLASHBACK ARCHIVEFLASHBACK ARCHIVE ADMINISTER system privilege, you must be logged on as SYSDBA.CREATE FLASHBACK ARCHIVE or ALTER FLASHBACK ARCHIVE statement, you must be logged on as SYSDBA.SYSDBA or have the FLASHBACK ARCHIVE ADMINISTER system privilege.
Using Oracle Flashback Query (SELECT AS OF)
SELECT statement with an AS OF clause. Oracle Flashback Query retrieves data as it existed at an earlier time. The query explicitly references a past time through a time stamp or System Change Number (SCN). It returns committed data that was current at that point in time.SELECT AS OF statement, see Oracle Database SQL Language Reference.
Example of Examining and Restoring Past Data
employees table, and you know that at 9:30AM the data for Chung was correctly stored in the database. You can use Oracle Flashback Query to examine the contents of the table at 9:30 AM to find out what data was lost. If appropriate, you can restore the lost data.Chung at 9:30AM, April 4, 2004:
SELECT * FROM employees
AS OF TIMESTAMP
TO_TIMESTAMP('2004-04-04 09:30:00', 'YYYY-MM-DD HH:MI:SS')
WHERE last_name = 'Chung';
employees table:
Guidelines for Oracle Flashback Query
AS OF clause for each table and specify different times for different tables.
AS OF clause in queries to perform data definition language (DDL) operations (such as creating and truncating tables) or data manipulation language (DML) statements (such as INSERT and DELETE) in the same session as Oracle Flashback Query.AS OF clause inside an INSERT or CREATE TABLE AS SELECT statement.AS OF clause in the SELECT statement that defines the view.
CREATE VIEW hour_ago AS
SELECT * FROM employees
AS OF TIMESTAMP (SYSTIMESTAMP - INTERVAL '60' MINUTE);
SYSTIMESTAMP refers to the time zone of the database host environment.AS OF clause in self-joins, or in set operations such as INTERSECT and MINUS, to extract or compare data from two different times.CREATE TABLE AS SELECT or INSERT INTO TABLE SELECT statement. For example, this query reinserts into table employees the rows that existed an hour ago:
INSERT INTO employees
(SELECT * FROM employees
AS OF TIMESTAMP (SYSTIMESTAMP - INTERVAL '60' MINUTE)
)
MINUS SELECT * FROM employees);
SYSTIMESTAMP refers to the time zone of the database host environment.
Using Oracle Flashback Version Query
COMMIT statement is executed.VERSIONS BETWEEN clause of the SELECT statement. The syntax is:
VERSIONS {BETWEEN {SCN | TIMESTAMP}
start AND end}
start and end are expressions representing the start and end, respectively, of the time interval to be queried. The time interval includes (start and end).
Pseudocolumn Name Description
TIMESTAMP when the row version was created. This pseudocolumn identifies the time when the data first had the values reflected in the row version. Use this pseudocolumn to identify the past target time for Oracle Flashback Table or Oracle Flashback Query.NULL, then the row version was created before start.
TIMESTAMP when the row version expired.NULL, then either the row version was current at the time of the query or the row corresponds to a DELETE operation.
I for insertion, D for deletion, or U for update. The version is that of the row that was inserted, deleted, or updated; that is, the row after an INSERT operation, the row before a DELETE operation, or the row affected by an UPDATE operation.UPDATE operation as two operations, DELETE plus INSERT, represented as two version rows with a D followed by an I VERSIONS_OPERATION.VERSIONS_START* up to, but not including, its time VERSIONS_END*. That is, it is valid for any time t such that VERSIONS_START* <= t < VERSIONS_END*. For example, this output indicates that the salary was 10243 from September 9, 2002, included, to November 25, 2003, excluded.
VERSIONS_START_TIME VERSIONS_END_TIME SALARY
------------------- ----------------- ------
09-SEP-2003 25-NOV-2003 10243
SELECT versions_startscn, versions_starttime,
versions_endscn, versions_endtime,
versions_xid, versions_operation,
last_name, salary
FROM employees
VERSIONS BETWEEN TIMESTAMP
TO_TIMESTAMP('2008-12-18 14:00:00', 'YYYY-MM-DD HH24:MI:SS')
AND TO_TIMESTAMP('2008-12-18 17:00:00', 'YYYY-MM-DD HH24:MI:SS')
WHERE first_name = 'John';
VERSIONS_XID with Oracle Flashback Transaction Query to locate this transaction 's metadata, including the SQL required to undo the row change and the user responsible for the change—see "Using Oracle Flashback Transaction Query".
VERSIONS clause
Using Oracle Flashback Transaction Query
FLASHBACK_TRANSACTION_QUERY, whose columns are described in Oracle Database Reference.UNDO_SQL shows the SQL code that is the is the logical opposite of the DML operation performed by the transaction. You can usually use this code to reverse the logical steps taken during the transaction. However, there are cases where the SQL_UNDO code is not the exact opposite of the original transaction. For example, a SQL_UNDO INSERT operation might not insert a row back in a table at the same ROWID from which it was deleted.FLASHBACK_TRANSACTION_QUERY view for transaction information, including the transaction ID, the operation, the operation start and end SCNs, the user responsible for the operation, and the SQL code that shows the logical opposite of the operation:
SELECT xid, operation, start_scn, commit_scn, logon_user, undo_sql
FROM flashback_transaction_query
WHERE xid = HEXTORAW('000200030000002D');
LOGON_USER responsible for the row data change:
SELECT xid, logon_user
FROM flashback_transaction_query
WHERE xid IN (
SELECT versions_xid FROM employees VERSIONS BETWEEN TIMESTAMP
TO_TIMESTAMP('2003-07-18 14:00:00', 'YYYY-MM-DD HH24:MI:SS') AND
TO_TIMESTAMP('2003-07-18 17:00:00', 'YYYY-MM-DD HH24:MI:SS')
);
FLASHBACK_TRANSACTION_QUERY without specifying XID in the WHERE clause, the query scans many unrelated rows, degrading performance.
Using Oracle Flashback Transaction Query with Oracle Flashback Version Query
DROP TABLE emp;
CREATE TABLE emp (
empno NUMBER PRIMARY KEY,
empname VARCHAR2(16),
salary NUMBER
);
INSERT INTO emp (empno, empname, salary) VALUES (111, 'Mike', 555);
COMMIT;
DROP TABLE dept;
CREATE TABLE dept (
deptno NUMBER,
deptname VARCHAR2(32)
);
INSERT INTO dept (deptno, deptname) VALUES (10, 'Accounting');
COMMIT;
emp and dept have one row each. In terms of row versions, each table has one version of one row. Suppose that an erroneous transaction deletes empno 111 from table emp:
UPDATE emp SET salary = salary + 100 WHERE empno = 111;
INSERT INTO dept (deptno, deptname) VALUES (20, 'Finance');
DELETE FROM emp WHERE empno = 111;
COMMIT;
empno 111 into the emp table with a new employee name:
INSERT INTO emp (empno, empname, salary) VALUES (111, 'Tom', 777);
UPDATE emp SET salary = salary + 100 WHERE empno = 111;
UPDATE emp SET salary = salary + 50 WHERE empno = 111;
COMMIT;
emp table that correspond to empno 111. The query uses Oracle Flashback Version Query pseudocolumns:
SELECT versions_xid XID, versions_startscn START_SCN,
versions_endscn END_SCN, versions_operation OPERATION,
empname, salary
FROM emp
VERSIONS BETWEEN SCN MINVALUE AND MAXVALUE
WHERE empno = 111;
XID START_SCN END_SCN O EMPNAME SALARY
---------------- ---------- ---------- - ---------------- ----------
09001100B2200000 10093466 I Tom 927
030002002B210000 10093459 D Mike 555
0800120096200000 10093375 10093459 I Mike 555
3 rows selected.
emp that was inserted in the table when the table was created. The second row corresponds to the row in emp that the erroneous transaction deleted. The first row corresponds to the version of the row in emp that was reinserted with a new employee name.030002002B210000 as the erroneous transaction and uses Oracle Flashback Transaction Query to audit all changes made by this transaction:
SELECT xid, start_scn, commit_scn, operation, logon_user, undo_sql
FROM flashback_transaction_query
WHERE xid = HEXTORAW('000200030000002D');
XID START_SCN COMMIT_SCN OPERATION LOGON_USER
---------------- ---------- ---------- --------- ------------------------------
UNDO_SQL
--------------------------------------------------------------------------------
030002002B210000 10093452 10093459 DELETE HR
insert into "HR"."EMP"("EMPNO","EMPNAME","SALARY") values ('111','Mike','655');
030002002B210000 10093452 10093459 INSERT HR
delete from "HR"."DEPT" where ROWID = 'AAATjuAAEAAAAJrAAB';
030002002B210000 10093452 10093459 UPDATE HR
update "HR"."EMP" set "SALARY" = '555' where ROWID = 'AAATjsAAEAAAAJ7AAA';
030002002B210000 10093452 10093459 BEGIN HR
4 rows selected.
COLUMN operation FORMAT A9
COLUMN table_name FORMAT A10
COLUMN table_owner FORMAT A11
SELECT xid, start_scn, commit_scn, operation, table_name, table_owner
FROM flashback_transaction_query
WHERE table_owner = 'HR'
AND start_timestamp >=
TO_TIMESTAMP ('2002-04-16 11:00:00','YYYY-MM-DD HH:MI:SS');
XID START_SCN COMMIT_SCN OPERATION TABLE_NAME TABLE_OWNER
---------------- ---------- ---------- --------- ---------- -----------
02000E0074200000 10093435 10093446 INSERT DEPT HR
030002002B210000 10093452 10093459 DELETE EMP HR
030002002B210000 10093452 10093459 INSERT DEPT HR
030002002B210000 10093452 10093459 UPDATE EMP HR
0800120096200000 10093374 10093375 INSERT EMP HR
09001100B2200000 10093462 10093466 UPDATE EMP HR
09001100B2200000 10093462 10093466 UPDATE EMP HR
09001100B2200000 10093462 10093466 INSERT EMP HR
8 rows selected.
XID in the WHERE clause, it scans many unrelated rows, degrading performance.
Using ORA_ROWSCN
ORA_ROWSCN is a pseudocolumn of any table that is not fixed or external. It represents the SCN of the most recent change to a given row in the current session; that is, the most recent COMMIT operation for the row in the current session. For example:
SELECT ora_rowscn, last_name, salary
FROM employees
WHERE employee_id = 200;
ORA_ROWSCN LAST_NAME SALARY
---------- ------------------------- ----------
884320 Whalen 2800
COMMIT operation for the row in the current session took place at approximately SCN 9371092. To convert an SCN to the corresponding TIMESTAMP value, use the function SCN_TO_TIMESTAMP (documented in Oracle Database SQL Language Reference).ORA_ROWSCN is a conservative upper bound of the latest commit time—the actual commit SCN can be somewhat earlier. ORA_ROWSCN is more precise (closer to the actual commit SCN) for a row-dependent table (created using CREATE TABLE with the ROWDEPENDENCIES clause). For more information about ORA_ROWSCN and ROWDEPENDENCIES, see Oracle Database SQL Language Reference.
ORA_ROWSCN is not supported for Flashback Query. Instead, use the version query pseudocolumns, which are provided explicitly for Flashback Query. For information about these pseudocolumns, see Oracle Database SQL Language Reference.
Scenario: Package Subprogram Might Change Row
ORA_ROWSCN as 202553. Then, your application invokes a package subprogram, whose implementation details you cannot see, which might or might not change the same row (and commit the change). Later, your application must update the row only if the package subprogram did not change it. Make the operation conditional—update the row only if ORA_ROWSCN is still 202553, as in this equivalent interactive statement:
UPDATE employees
SET salary = salary + 100
WHERE employee_id = 200
AND ora_rowscn = 202553;
ORA_ROWSCN is no longer 9371092, and the update fails.ORA_ROWSCN. Suppose that the ORA_ROWSCN is now 415639. The application tries the conditional update again, using the new ORA_ROWSCN. This time, the update succeeds, and it is committed. An interactive equivalent is:
UPDATE employees
SET salary = salary + 100
WHERE employee_id = 7788
AND ora_rowscn = 415639;
ORA_ROWSCN and Tables with Virtual Private Database (VPD)
ORA_ROWSCN pseudocolumn. However, because ORA_ROWSCN is available inside the policy function, you can:
||' AND f_ora_rowscn('||object_name||'.ora_rowscn) = 1'
SELECT t.*, get_rowscn(t.rowid) "ORA_ROWSCN" FROM test_table t;
-- Create context that function uses while processing rows:
CREATE OR REPLACE FUNCTION f_ora_rowscn
(rowscn IN NUMBER)
RETURN NUMBER
AS
BEGIN
DBMS_SESSION.SET_CONTEXT('STORE_ROWSCN','ROWSCN',rowscn);
RETURN 1;
END;
/
CREATE CONTEXT store_rowscn USING f_ora_rowscn;
-- Create function that returns row SCN for each row:
CREATE OR REPLACE FUNCTION get_rowscn
(r IN ROWID)
RETURN VARCHAR2
AS
BEGIN
RETURN sys_context('STORE_ROWSCN','ROWSCN');
END;
/
Using DBMS_FLASHBACK Package
DBMS_FLASHBACK package provides the same functionality as Oracle Flashback Query, but Oracle Flashback Query is sometimes more convenient.DBMS_FLASHBACK package acts as a time machine: you can turn back the clock, perform normal queries as if you were at that earlier time, and then return to the present. Because you can use the DBMS_FLASHBACK package to perform queries on past data without special clauses such as AS OF or VERSIONS BETWEEN, you can reuse existing PL/SQL code to query the database at earlier times.EXECUTE privilege on the DBMS_FLASHBACK package.DBMS_FLASHBACK package in your PL/SQL code:DBMS_FLASHBACK.ENABLE_AT_TIME or DBMS_FLASHBACK.ENABLE_AT_SYSTEM_CHANGE_NUMBER.AS OF). Do not perform DDL or DML operations.DBMS_FLASHBACK.DISABLE.DBMS_FLASHBACK.DISABLE before invoking DBMS_FLASHBACK.ENABLE_AT_TIME or DBMS_FLASHBACK.ENABLE_AT_SYSTEM_CHANGE_NUMBER again. You cannot nest enable/disable pairs.DBMS_FLASHBACK.DISABLE. After storing the results and invoking DBMS_FLASHBACK.DISABLE, you can:INSERT or UPDATE operations to modify the current database state by using the stored results from the past.DBMS_FLASHBACK.DISABLE, open a second cursor. Fetch from the first cursor to retrieve past data; fetch from the second cursor to retrieve current data. You can store the past data in a temporary table and then use set operators such as MINUS or UNION to contrast or combine the past and current data.DBMS_FLASHBACK.GET_SYSTEM_CHANGE_NUMBER at any time to get the current System Change Number (SCN). DBMS_FLASHBACK.GET_SYSTEM_CHANGE_NUMBER always returns the current SCN regardless of previous invocations of DBMS_FLASHBACK.ENABLE.
DBMS_FLASHBACK package
Using Flashback Transaction
DBMS_FLASHBACK.TRANSACTION_BACKOUT procedure rolls back a transaction and its dependent transactions while the database remains online. This recovery operation uses undo data to create and run the compensating transactions that return the affected data to its original state.BFILEBLOBCLOBNCLOBCOMPATIBLE initialization parameter for the database that is rolling back the transaction. The default value is the release number of the most recent major release.
COMPATIBLE initialization parameter
Dependent Transactions
TRANSACTION_BACKOUT Parameters
TRANSACTION_BACKOUT procedure are:TRANSACTION_BACKOUT procedure and detailed parameter descriptions, see Oracle Database PL/SQL Packages and Types Reference.
Option Description
CASCADE
CASCADE, if any dependent transaction is not specified, an error occurs.
NOCASCADE
*_FLASHBACK_TRANSACTION_REPORT.
NOCASCADE_FORCE
NONCONFLICT_ONLY
TRANSACTION_BACKOUT analyzes the transactional dependencies, performs DML operations, and generates reports. TRANSACTION_BACKOUT does not commit the DML operations that it performs as part of transaction backout, but it holds all the required locks on rows and tables in the right form, preventing other dependencies from entering the system. To make the transaction backout permanent, you must explicitly commit the transaction.
TRANSACTION_BACKOUT Reports
TRANSACTION_BACKOUT generates, query the static data dictionary views *_FLASHBACK_TXN_STATE and *_FLASHBACK_TXN_REPORT.
*_FLASHBACK_TXN_STATE
*_FLASHBACK_TXN_STATE shows whether a transaction is active or backed out. If a transaction appears in this view, it is backed out.*_FLASHBACK_TXN_STATE is maintained atomically for compensating transactions. If a compensating transaction is backed out, all changes that it made are also backed out, and *_FLASHBACK_TXN_STATE reflects this. For example, if compensating transaction ct backs out transactions t1 and t2, then t1 and t2 appear in *_FLASHBACK_TXN_STATE. If ct itself is later backed out, the effects of t1 and t2 are reinstated, and t1 and t2 disappear from *_FLASHBACK_TXN_STATE.
*_FLASHBACK_TXN_REPORT
*_FLASHBACK_TXN_REPORT provides a detailed report for each backed-out transaction.
Using Flashback Data Archive (Oracle Total Recall)
SYSDBA, you can specify a default Flashback Data Archive for the system. A Flashback Data Archive is configured with retention time. Data archived in the Flashback Data Archive is retained for the retention time.FLASHBACK ARCHIVE object privilege on the Flashback Data Archive to use for that table.LONG nor nested columns.FLASHBACK ARCHIVE ADMINISTER system privilege or you are logged on as SYSDBA.FLASHBACK ARCHIVE object privilege.
http://www.oracle.com/database/total-recall.html for more information about Oracle Total Recall
Creating a Flashback Data Archive
CREATE FLASHBACK ARCHIVE statement, specifying:SYSDBA, you can also specify that this is the default Flashback Data Archive for the system. If you omit this option, you can still make this Flashback Data Archive the default later (see "Specifying the Default Flashback Data Archive").fla1 that uses up to 10 G of tablespace tbs1, whose data are retained for one year:
CREATE FLASHBACK ARCHIVE DEFAULT fla1 TABLESPACE tbs1
QUOTA 10G RETENTION 1 YEAR;
fla2 that uses tablespace tbs2, whose data are retained for two years:
CREATE FLASHBACK ARCHIVE fla2 TABLESPACE tbs2 RETENTION 2 YEAR;
CREATE FLASHBACK ARCHIVE statement, see Oracle Database SQL Language Reference.
Altering a Flashback Data Archive
ALTER FLASHBACK ARCHIVE statement, you can:
SYSDBA, you can also use the ALTER FLASHBACK ARCHIVE statement to make a specific file the default Flashback Data Archive for the system.fla1 the default Flashback Data Archive:
ALTER FLASHBACK ARCHIVE fla1 SET DEFAULT;
fla1, add up to 5 G of tablespace tbs3:
ALTER FLASHBACK ARCHIVE fla1 ADD TABLESPACE tbs3 QUOTA 5G;
fla1, add as much of tablespace tbs4 as needed:
ALTER FLASHBACK ARCHIVE fla1 ADD TABLESPACE tbs4;
fla1 can use in tablespace tbs3 to 20 G:
ALTER FLASHBACK ARCHIVE fla1 MODIFY TABLESPACE tbs3 QUOTA 20G;
fla1 to use as much of tablespace tbs1 as needed:
ALTER FLASHBACK ARCHIVE fla1 MODIFY TABLESPACE tbs1;
fla1 to two years:
ALTER FLASHBACK ARCHIVE fla1 MODIFY RETENTION 2 YEAR;
tbs2 from Flashback Data Archive fla1:
ALTER FLASHBACK ARCHIVE fla1 REMOVE TABLESPACE tbs2;
tbs2 is not dropped.)fla1:
ALTER FLASHBACK ARCHIVE fla1 PURGE ALL;
fla1:
ALTER FLASHBACK ARCHIVE fla1
PURGE BEFORE TIMESTAMP (SYSTIMESTAMP - INTERVAL '1' DAY);
fla1:
ALTER FLASHBACK ARCHIVE fla1 PURGE BEFORE SCN 728969;
ALTER FLASHBACK ARCHIVE statement, see Oracle Database SQL Language Reference.
Dropping a Flashback Data Archive
DROP FLASHBACK ARCHIVE statement. Dropping a Flashback Data Archive deletes its historical data, but does not drop its tablespaces.fla1 and all its historical data, but not its tablespaces:
DROP FLASHBACK ARCHIVE fla1;
DROP FLASHBACK ARCHIVE statement, see Oracle Database SQL Language Reference.
Specifying the Default Flashback Data Archive
SYSDBA, you can specify default Flashback Data Archive in either of these ways:SET DEFAULT clause of the ALTER FLASHBACK ARCHIVE statement. For example:
ALTER FLASHBACK ARCHIVE fla1 SET DEFAULT;
fla1 does not exist, an error occurs.DEFAULT in the CREATE FLASHBACK ARCHIVE statement when you create a Flashback Data Archive. For example:
CREATE FLASHBACK ARCHIVE DEFAULT fla2 TABLESPACE tbs1
QUOTA 10G RETENTION 1 YEAR;
CREATE FLASHBACK ARCHIVE statementALTER DATABASE statement
Enabling and Disabling Flashback Data Archive
FLASHBACK ARCHIVE object privilege on the Flashback Data Archive to use for that table.FLASHBACK ARCHIVE clause in either the CREATE TABLE or ALTER TABLE statement. In the FLASHBACK ARCHIVE clause, you can specify the Flashback Data Archive where the historical data for the table are stored. The default is the default Flashback Data Archive for the system. If you specify a nonexistent Flashback Data Archive, an error occurs.FLASHBACK ARCHIVE ADMINISTER system privilege or you are logged on as SYSDBA. To disable flashback archiving for a table, specify NO FLASHBACK ARCHIVE in the ALTER TABLE statement. (It is unnecessary to specify NO FLASHBACK ARCHIVE in the CREATE TABLE statement, because that is the default.)
FLASHBACK ARCHIVE clause of the CREATE TABLE statement, including restrictions on its useemployee and store the historical data in the default Flashback Data Archive:
CREATE TABLE employee (EMPNO NUMBER(4) NOT NULL, ENAME VARCHAR2(10),
JOB VARCHAR2(9), MGR NUMBER(4)) FLASHBACK ARCHIVE;
employee and store the historical data in the Flashback Data Archive fla1:
CREATE TABLE employee (EMPNO NUMBER(4) NOT NULL, ENAME VARCHAR2(10),
JOB VARCHAR2(9), MGR NUMBER(4)) FLASHBACK ARCHIVE fla1;
employee and store the historical data in the default Flashback Data Archive:
ALTER TABLE employee FLASHBACK ARCHIVE;
employee and store the historical data in the Flashback Data Archive fla1:
ALTER TABLE employee FLASHBACK ARCHIVE fla1;
employee:
ALTER TABLE employee NO FLASHBACK ARCHIVE;
DDL Statements on Tables Enabled for Flashback Data Archive
ALTER TABLE statement that does any of the following:TRUNCATE TABLE statementRENAME statement that renames a tableALTER TABLE statement that includes an UPGRADE TABLE clause, with or without an INCLUDING DATA clauseALTER TABLE statement that moves or exchanges a partition or subpartition operationDROP TABLE statementDBMS_FLASHBACK_ARCHIVE.DISASSOCIATE_FBA procedure to disassociate the base table from its Flashback Data Archive. To reassociate the Flashback Data Archive with the base table afterward, use the DBMS_FLASHBACK_ARCHIVE.REASSOCIATE_FBA procedure.
ALTER TABLE statementTRUNCATE TABLE statementRENAME statementDROP TABLE statementDBMS_FLASHBACK_ARCHIVE package
Viewing Flashback Data Archive Data
View Description
*_FLASHBACK_ARCHIVE
*_FLASHBACK_ARCHIVE_TS
*_FLASHBACK_ARCHIVE_TABLES
*_FLASHBACK_ARCHIVE*_FLASHBACK_ARCHIVE_TS*_FLASHBACK_ARCHIVE_TABLES
Flashback Data Archive Scenarios
Scenario: Using Flashback Data Archive to Enforce Digital Shredding
Taxes table after ten years. When you create the Flashback Data Archive for Taxes, you specify a retention time of ten years:
CREATE FLASHBACK ARCHIVE taxes_archive TABLESPACE tbs1 RETENTION 10 YEAR;
Taxes exceeds the age of ten years, it is purged. (The Taxes table itself, and history data from transactions less than ten years old, are not purged.)
Scenario: Using Flashback Data Archive to Access Historical Data
inventory, and to be able to retrieve the stock price for each symbol in your portfolio at the close of business on any specified day of the year from the table stock_data.fla1 that uses up to 10 G of tablespace tbs1, whose data are retained for five years (you must be logged on as SYSDBA):
CREATE FLASHBACK ARCHIVE DEFAULT fla1 TABLESPACE tbs1
QUOTA 10G RETENTION 5 YEAR;
inventory and stock_data, and store the historical data in the default Flashback Data Archive:
ALTER TABLE inventory FLASHBACK ARCHIVE;
ALTER TABLE stock_data FLASHBACK ARCHIVE;
SELECT product_number, product_name, count FROM inventory AS OF
TIMESTAMP TO_TIMESTAMP ('2007-01-01 00:00:00', 'YYYY-MM-DD HH24:MI:SS');
SELECT symbol, stock_price FROM stock_data AS OF
TIMESTAMP TO_TIMESTAMP ('2007-07-23 16:00:00', 'YYYY-MM-DD HH24:MI:SS')
WHERE symbol IN my_portfolio;
Scenario: Using Flashback Data Archive to Generate Reports
investments, for data stored in the past five years.fla2 that uses up to 20 G of tablespace tbs1, whose data are retained for five years (you must be logged on as SYSDBA):
CREATE FLASHBACK ARCHIVE DEFAULT fla2 TABLESPACE tbs1
QUOTA 20G RETENTION 5 YEAR;
investments, and store the historical data in the default Flashback Data Archive:
ALTER TABLE investments FLASHBACK ARCHIVE;
SELECT * FROM investments AS OF
TIMESTAMP TO_TIMESTAMP ('2006-12-31 16:00:00', 'YYYY-MM-DD HH24:MI:SS')
WHERE name = 'LISA';
Scenario: Using Flashback Data Archive for Auditing
Billings, and creates a default Flashback Data Archive named fla4 that uses up to 100 G of tablespace tbs1, whose data are retained for 10 years:
CREATE FLASHBACK ARCHIVE DEFAULT fla4 TABLESPACE tbs1
QUOTA 100G RETENTION 10 YEAR;
Billings, and stores the historical data in the default Flashback Data Archive:
ALTER TABLE Billings FLASHBACK ARCHIVE;
SELECT date_billed, amount_billed, patient_name, claim_Id,
test_costs, diagnosis FROM Billings AS OF TIMESTAMP
TO_TIMESTAMP('2007-05-01 00:00:00', 'YYYY-MM-DD HH24:MI:SS');
Scenario: Using Flashback Data Archive to Recover Data
employee table to give Lisa's level-three employees a 10% raise and a promotion to level four. Then Bob finishes his work for the day and leaves for home, unaware that he omitted the requirement of two years of experience in his transaction. A few days later, Lisa checks to see if Bob has done the updates and finds that everyone in the group was given a raise! She calls Bob immediately and asks him to correct the error.employee table has Flashback Data Archive enabled.employee table after his: The commit time stamp from the transaction query corresponds to Bob's transaction, two days ago.employee table to the way it was before his erroneous change:
DELETE EMPLOYEE WHERE MANAGER = 'LISA JOHNSON';
INSERT INTO EMPLOYEE
SELECT * FROM EMPLOYEE
AS OF TIMESTAMP (SYSTIMESTAMP - INTERVAL '2' DAY)
WHERE MANAGER = 'LISA JOHNSON';
General Guidelines for Oracle Flashback Technology
DBMS_FLASHBACK.ENABLE and DBMS_FLASHBACK.DISABLE procedures around SQL code that you do not control, or when you want to use the same past time for several consecutive queries.DBMS_FLASHBACK.GET_SYSTEM_CHANGE_NUMBER.INTERVAL value to the value of the SYSTIMESTAMP function.
(SELECT * FROM employees@some_remote_host AS OF
TIMESTAMP (SYSTIMESTAMP - INTERVAL '60' MINUTE);
COMMIT or ROLLBACK operation before querying past data.PCTFREE, INITRANS, and MAXTRANS) do not invalidate undo data.V$) view. A query on such a view always returns current data.*_TABLES.
Performance Guidelines for Oracle Flashback Technology
DBMS_STATS package to generate statistics for all tables involved in an Oracle Flashback Query. Keep the statistics current. Oracle Flashback Query uses the cost-based optimizer, which relies on these statistics.xid column is of the type RAW(8). To take advantage of the index built on the xid column, use the HEXTORAW conversion function: HEXTORAW(xid).
PK( ( PK |%A OEBPS/adfns_editions.htm
8 Using the PL/SQL Hierarchical Profiler
Overview of PL/SQL Hierarchical Profiler
INSERT_ORDER, but it is more helpful to know which subprograms call INSERT_ORDER often and the total time the program spends under INSERT_ORDER (including its descendant subprograms). Hierarchical profilers provide such information.DBMS_HPROF package and has two components:DBMS_HPROF package provides APIs to turn hierarchical profiling on and off and write the raw profiler output to a file.
plshprof command-line utility.
Collecting Profile Data
DBMS_HPROF.START_PROFILING PL/SQL API to start hierarchical profiler data collection in a session.DBMS_HPROF.STOP_PROFILING PL/SQL API to stop hierarchical profiler data collection.DBMS_HPROF.START_PROFILING and DBMS_HPROF.STOP_PROFILING, see Oracle Database PL/SQL Packages and Types Reference.test:
CREATE OR REPLACE PROCEDURE test IS
n NUMBER;
PROCEDURE foo IS
BEGIN
SELECT COUNT(*) INTO n FROM EMPLOYEES;
END foo;
BEGIN -- test
FOR i IN 1..3 LOOP
foo;
END LOOP;
END test;
/
test.
BEGIN
/* Start profiling.
Write raw profiler output to file test.trc in a directory
that is mapped to directory object PLSHPROF_DIR
(see note after example). */
DBMS_HPROF.START_PROFILING('PLSHPROF_DIR', 'test.trc');
END;
/
-- Run procedure to be profiled
BEGIN
test;
END;
/
BEGIN
-- Stop profiling
DBMS_HPROF.STOP_PROFILING;
END;
/
AS SYSDBA, this CREATE DIRECTORY statement creates the directory object PLSHPROF_DIR and maps it to the file system directory /private/plshprof/results:
CREATE DIRECTORY PLSHPROF_DIR as '/private/plshprof/results';
READ and WRITE privileges on both PLSHPROF_DIR and the directory to which it is mapped. if you are connected to the database AS SYSDBA, this GRANT statement grants READ and WRITE privileges on PLSHPROF_DIR to HR:
GRANT READ, WRITE ON DIRECTORY PLSHPROF_DIR TO HR;
Understanding Raw Profiler Output
test.trc:
P#V PLSHPROF Internal Version 1.0
P#! PL/SQL Timer Started
P#C PLSQL."".""."__plsql_vm"
P#X 2
P#C PLSQL."".""."__anonymous_block"
P#X 50
P#C PLSQL."HR"."TEST"::7."TEST"#980980e97e42f8ec #1
P#X 3
P#C PLSQL."HR"."TEST"::7."TEST.FOO"#980980e97e42f8ec #4
P#X 35
P#C SQL."HR"."TEST"::7."__static_sql_exec_line6" #6
P#X 206
P#R
P#X 26
P#R
P#X 2
P#C PLSQL."HR"."TEST"::7."TEST.FOO"#980980e97e42f8ec #4
P#X 4
P#C SQL."HR"."TEST"::7."__static_sql_exec_line6" #6
P#X 80
P#R
P#X 3
P#R
P#X 0
P#C PLSQL."HR"."TEST"::7."TEST.FOO"#980980e97e42f8ec #4
P#X 3
P#C SQL."HR"."TEST"::7."__static_sql_exec_line6" #6
P#X 69
P#R
P#X 3
P#R
P#X 1
P#R
P#X 1
P#R
P#X 3
P#R
P#C PLSQL."".""."__plsql_vm"
P#X 3
P#C PLSQL."".""."__anonymous_block"
P#X 44
P#C PLSQL."SYS"."DBMS_HPROF"::11."STOP_PROFILING"#980980e97e42f8ec #53
P#R
P#R
P#R
P#! PL/SQL Timer Stopped
Indicator Meaning
P#V
PLSHPROF banner with version number
P#C
P#R
P#X
P#!
P#C) and return events (P#R) are always properly nested (like matched parentheses). If an unhandled exception causes a called subprogram to exit, the profiler still reports a matching return event.P#C) entry in the raw profiler output includes this information:DBMS_HPROF.analyze PL/SQL API (described in "Analyzing Profile Data") stores the hash value in a hierarchical profiler table, which allows both you and DBMS_HPROF.analyze to distinguish between overloaded subprograms (subprograms with the same name).
P#C PLSQL."HR"."TEST"::7."TEST.FOO"#980980e97e42f8ec #4
Component Meaning PLSQLPLSQL is the namespace to which the called subprogram belongs."HR"."TEST"HR.TEST is the name of the PL/SQL module in which the called subprogram is defined.77 is the internal enumerator for the module type of HR.TEST. Examples of module types are procedure, package, and package body."TEST.FOO"TEST.FOO is the name of the called subprogram.#980980e97e42f8ec#980980e97e42f8ec is a hexadecimal value that represents an MD5 hash of the signature of TEST.FOO.#44 is the line number in the PL/SQL module HR.TEST at which TEST.FOO is defined.
DETERMINISTIC function is "optimized away," it is not reported in the profiler output. For information about DETERMINISTIC functions, see Oracle Database PL/SQL Language Reference.
Namespaces of Tracked Subprograms
Special Function Names
Tracked Operation Function Name Namespace
__plsql_vm
__anonymous_block
__pkg_init
line#
__static_sql_exec_lineline#
line#
__dyn_sql_exec_lineline#
FETCH statement at line line#
__sql_fetch_lineline#
Analyzing Profile Data
DBMS_HPROF.analyze, processes the raw profiler output and stores the results in the hierarchical database tables described in Table 8-3.
Table Description
DBMSHP_RUNS
DBMS_HPROF.analyze. For column descriptions, see Table 8-4.
DBMSHP_FUNCTION_INFO
DBMS_HPROF.analyze. For column descriptions, see Table 8-5.
DBMSHP_PARENT_CHILD_INFO
DBMS_HPROF.analyze. For column descriptions, see Table 8-6.
plshprof command-line utility. For details, see "plshprof Utility".
Creating Hierarchical Profiler Tables
dbmshptab.sql (located in the directory rdbms/admin).
dbmshptab.sql drops any previously created hierarchical profiler tables.EXECUTE privilege on the DBMS_HPROF packageREAD privilege on the directory that DBMS_HPROF.analyze specifiesDBMS_HPROF.analyze to analyze a single raw profiler output file and store the results in hierarchical profiler tables.test.trc in "Understanding Raw Profiler Output".)DBMS_HPROF.analyze, see Oracle Database PL/SQL Packages and Types Reference.DBMS_HPROF.analyze function, which:test.trc (from "Understanding Raw Profiler Output"), which is in the directory that is mapped to the directory object PLSHPROF_DIR, and stores the data in the hierarchical profiler tables in Table 8-3.runid, which it prints.
Understanding Hierarchical Profiler Tables
Hierarchical Profiler Database Table Columns
DBMSHP_RUNS, which contains one row of top-level information for each run of DBMS_HPROF.analyze.DBMSHP_RUNS is RUNID.
Column Name Column Data Type Column Contents
RUNID
NUMBER PRIMARY KEY
DBMS_HPROF.analyze, generated from DBMSHP_RUNNUMBER sequence.
RUN_TIMESTAMP
TIMESTAMP
DBMS_HPROF.analyze.
RUN_COMMENT
VARCHAR2(2047)
DBMS_HPROF.analyze.
TOTAL_ELAPSED_TIME
INTEGER
DBMS_HPROF.analyze.DBMSHP_FUNCTION_INFO, which contains one row of information for each subprogram profiled in this run of DBMS_HPROF.analyze. If a subprogram is overloaded, Table 8-5 has a row for each variation of that subprogram. Each variation has its own LINE# and HASH (see "Distinguishing Between Overloaded Subprograms").DBMSHP_FUNCTION_INFO is RUNID, SYMBOLID.
Column Name Column Data Type Column Contents
RUNID
NUMBER
RUNID column of DBMSHP_RUNS table. For a description of that column, see Table 8-4.
SYMBOLID
NUMBER
DBMS_HPROF.analyze).
OWNER
VARCHAR2(32)
SYS or HR).
MODULE
VARCHAR2(2047)
DBMS_LOB, UTL_HTTP, or MY_PACKAGE).
TYPE
VARCHAR2(32)
PACKAGE, PACKAGE_BODY, or PROCEDURE).
FUNCTION
VARCHAR2(4000)
INSERT_ORDER, PROCESS_ITEMS, or TEST).B defined within subprogram A, this name is A.B.X is denoted X@n, where n is the recursion depth. For example, X@1 is the first recursive call to X.
LINE#
NUMBER
OWNER.MODULE at which FUNCTION is defined.
HASH
RAW(32)
DBMS_HPROF.analyze).
NAMESPACE
VARCHAR2(32)
SUBTREE_ELAPSED_TIME
INTEGER
FUNCTION_ELAPSED_TIME
INTEGER
CALLS
INTEGER
DBMSHP_PARENT_CHILD_INFO, which contains one row of parent-child information for each unique parent-child subprogram combination profiled in this run of DBMS_HPROF.analyze.
Column Name Column Data Type Column Contents
RUNID
NUMBER
RUNID column of DBMSHP_FUNCTION_INFO table. For a description of that column, see Table 8-5.
PARENTSYMID
NUMBER
RUNID, PARENTSYMID references DBMSHP_FUNCTION_INFO(RUNID, SYMBOLID).
CHILDSYMID
VARCHAR2(32)
RUNID, CHILDSYMID references DBMSHP_FUNCTION_INFO(RUNID, SYMBOLID).
SUBTREE_ELAPSED_TIME
INTEGER
RUNID, CHILDSYMID when called from RUNID, PARENTSYMID, including time spent in descendant subprograms.
FUNCTION_ELAPSED_TIME
INTEGER
RUNID, CHILDSYMID when called from RUNID, PARENTSYMID, excluding time spent in descendant subprograms.
CALLS
INTEGER
RUNID, CHILDSYMID from RUNID, PARENTSYMID.
Distinguishing Between Overloaded Subprograms
compute—the first at line 50, the second at line 76, and the third at line 100. In the DBMSHP_FUNCTION_INFO table, each of these subprograms has compute in the FUNCTION column. To distinguish between the three subprograms, use either the LINE# column (which has 50 for the first subprogram, 76 for the second, and 100 for the third) or the HASH column (which has a unique value for each subprogram).LINE# and HASH values for a function might differ. The LINE# value of a function changes if you insert or delete lines before the function definition. The HASH value changes only if the signature of the function changes; for example, if you change the parameter list.
Hierarchical Profiler Tables for Sample PL/SQL Procedure
test in "Collecting Profile Data" are shown in Example 8-3 through Example 8-5.
RUNID RUN_TIMESTAMP TOTAL_ELAPSED_TIME RUN_COMMENT
1 10-APR-06 12.01.56.766743 PM 2637 First run of TEST
RUNID SYMBOLID OWNER MODULE TYPE NAMESPACE FUNCTION
1 1 PLSQL __anonymous_block
1 2 PLSQL __plsql_vm
1 3 HR TEST PROCEDURE PLSQL TEST
1 4 HR TEST PROCEDURE PLSQL TEST.FOO
1 5 SYS DBMS_HPROF PACKAGE_BODY PLSQL STOP_PROFILING
1 6 HR TEST PROCEDURE SQL __static_sql_exec_line5
LINE# CALLS HASH SUBTREE_ELAPSED_TIME FUNCTION_ELAPSED_TIME
0 2 980980E97E42F8EC 2554 342
0 2 980980E97E42F8EC 2637 83
1 1 980980E97E42F8EC 2212 28
3 3 980980E97E42F8EC 2184 126
57 1 980980E97E42F8EC 0 0
5 3 980980E97E42F8EC 1998 1998
RUNID PARENTSYMID CHILDSYMID SUBTREE_ELAPSED_TIME FUNCTION_ELAPSED_TIME CALLS
1 2 1 2554 342 2
1 1 3 2212 28 1
1 3 4 2184 126 3
1 1 5 0 0 1
1 4 6 1998 1998 3
DBMSHP_PARENT_CHILD_INFO (Example 8-5). The RUNID column shows that this row corresponds to the first run. The columns PARENTSYMID and CHILDSYMID show that the symbol IDs of the parent (caller) and child (called subprogram) are 3 and 4, respectively. The table DBMSHP_FUNCTION_INFO (Example 8-4) shows that for the first run, the symbol IDs 3 and 4 correspond to procedures TEST and TEST.FOO, respectively. Therefore, the information in this row is about calls from the procedure TEST to the procedure FOO (defined within TEST) in the module HR.TEST. This row shows that, when called from the procedure TEST, the function time for the procedure FOO is 126 microseconds, and the time spent in the FOO subtree (including descendants) is 2184 microseconds.
Examples of Calls to DBMS_HPROF.analyze with Options
DBMS_HPROF.analyze without options, see Example 8-2.DBMS_HRPROF.analyze to analyze the raw profiler output file. The raw profiler output file is in the directory corresponding to the PLSHPROF_DIR directory object.
-- Create package
CREATE OR REPLACE PACKAGE pkg IS
PROCEDURE myproc (n IN out NUMBER);
FUNCTION myfunc (v VARCHAR2) RETURN VARCHAR2;
FUNCTION myfunc (n PLS_INTEGER) RETURN PLS_INTEGER;
END pkg;
/
CREATE OR REPLACE PACKAGE BODY pkg IS
PROCEDURE myproc (n IN OUT NUMBER) IS
BEGIN
n := n + 5;
END;
FUNCTION myfunc (v VARCHAR2) RETURN VARCHAR2 IS
n NUMBER;
BEGIN
n := LENGTH(v);
myproc(n);
IF n > 20 THEN
RETURN SUBSTR(v, 1, 20);
ELSE
RETURN v || '...';
END IF;
END;
FUNCTION myfunc (n PLS_INTEGER) RETURN PLS_INTEGER IS
i PLS_INTEGER;
PROCEDURE myproc (n IN out PLS_INTEGER) IS
BEGIN
n := n + 1;
END;
BEGIN
i := n;
myproc(i);
RETURN i;
END;
END pkg;
/
-- Create procedure that invokes package subprograms
CREATE OR REPLACE PROCEDURE test2 IS
x NUMBER := 5;
y VARCHAR2(32767);
BEGIN
pkg.myproc(x);
y := pkg.myfunc('hello');
END;
-- Profile test2
BEGIN
DBMS_HPROF.START_PROFILING('PLSHPROF_DIR', 'test2.trc');
END;
/
BEGIN
test2;
END;
/
BEGIN
DBMS_HPROF.STOP_PROFILING;
END;
/
-- If not done, create hierarchical profiler tables
-- (see "Creating Hierarchical Profiler Tables".)
-- Call DBMS_HPROF.analyze with options
DECLARE
runid NUMBER;
BEGIN
-- Analyze only subtrees rooted at trace entry "HR"."PKG"."MYPROC"
runid := DBMS_HPROF.analyze('PLSHPROF_DIR', 'test2.trc',
trace => '"HR"."PKG"."MYPROC"');
-- Analyze up to 20 calls to subtrees rooted at trace entry
-- "HR"."PKG"."MYFUNC". Because "HR"."PKG"."MYFUNC" is overloaded,
-- both overloads are considered for analysis.
runid := DBMS_HPROF.analyze('PLSHPROF_DIR', 'test2.trc',
collect => 20,
trace => '"HR"."PKG"."MYFUNC"');
-- Analyze second call to PL/SQL virtual machine
runid := DBMS_HPROF.analyze('PLSHPROF_DIR', 'test2.trc',
skip => 1, collect => 1,
trace => '""."".""__plsql_vm"');
END;
/
plshprof Utility
plshprof command-line utility (located in the directory $ORACLE_HOME/bin/) generates simple HTML reports from either one or two raw profiler output files. (For an example of a raw profiler output file, see test.trc in "Collecting Profile Data".)
plshprof Options
plshprof utility is:
plshprof [option...] profiler_output_filename_1 profiler_output_filename_2
option is one of these:
Option Description Default -skip countSkips first count calls. Use only with -trace symbol.0 -collect countCollects information for count calls. Use only with -trace symbol.1 -output filenameSpecifies name of output file symbol.html or tracefile1.html-summaryPrints only elapsed time None -trace symbolSpecifies function name of tree root Not applicable test.trc, is in the current directory. You want to analyze and generate HTML reports, and you want the root file of the HTML report to be named report.html. Use this command (% is the prompt):
% plshprof -output report test.trc
HTML Report from a Single Raw Profiler Output File
% cd
target_directory
% plshprof -output html_root_filename profiler_output_filename
target_directory is the directory in which you want the HTML files to be created.html_root_filename is the name of the root HTML file to be created.profiler_output_filename is the name of a raw profiler output file.plshprof command generates a set of HTML files. Start browsing them from html_root_filename.html.
First Page of Report
Function-Level Reports
Subtree Ind% Function Descendant Ind% Calls Ind% Function Name 2831 100% 93 2738 96.7% 2 16.7% __plsq_vm 2738 96.7% 310 2428 85.8% 2 16.7% __anonymous_block 2428 85.8% 15 2413 85.2% 1 8.3% HR.TEST.TEST (Line 1) 2413 85.2% 435 1978 69.9% 3 25.0% HR.TEST.TEST.FOO (Line 3) 1978 69.9% 1978 0 0.0% 3 25.0% HR.TEST.__static_sql_exec_line5 (Line 5) 0 0.0% 0 0 0.0% 1 8.3% SYS.DBMS_HPROF.STOP_PROFILING (Line 53)
Module-Level Reports
Module Ind% Cum% Calls Ind% Module Name 84932 50.9% 50.9% 6 0.5% HR.P 67749 40.6% 91.5% 216 19.7% SYS.DBMS_LOB 13340 8.0% 99.5% 660 60.1% SYS.UTL_FILE 839 0.5% 100% 214 19.5% SYS.UTL_RAW 18 0.0% 100% 2 0.2% HR.UTILS 0 0.0% 100% 1 0.1% SYS.DBMS_HPROF
Namespace-Level Reports
Function Ind% Cum% Calls Ind% Namespace 93659 56.1% 56.1% 1095 99.6% PLSQL 73219 43.9% 100% 4 0.4% SQL
Parents and Children Report for a Function
HR.P.UPLOAD. The first row has this summary information:HR.P.UPLOAD.HR.P.UPLOAD, which are HR.UTILS.COPY_IMAGE and HR.UTILS.COPY_FILE.HR.UTILS.COPY_IMAGE, shows:HR.UTILS.COPY_IMAGE calls HR.P.UPLOAD once, which is 50% of the number of calls to HR.P.UPLOAD.HR.P.UPLOAD when called from HR.UTILS.COPY_IMAGE is 106,325 microseconds, which is 63.7% of the total subtree time for HR.P.UPLOAD.HR.P.UPLOAD when called from HR.UTILS.COPY_IMAGE is 6,434 microseconds, which is 54.9% of the total function time for HR.P.UPLOAD.HR.P.UPLOAD when called from HR.P.UPLOAD.SYS.UTL_FILE.GET_RAW, shows:HR.P.UPLOAD calls SYS.UTL_FILE.GET_RAW 216 times.SYS.UTL_FILE.GET_RAW when called from HR.P.UPLOAD are 12,487 microseconds, 3,969 microseconds, and 8,518 microseconds, respectively.HR.P.UPLOAD (155,147 microseconds), the child SYS.UTL_FILE.GET_RAW is responsible for 12,487 microsecs (8.0%).
Subtree Ind% Function Ind% Descendant Ind% Calls Ind% Function Name 166860 100% 11713 7.0% 155147 93.0% 2 0.2% HR.P.UPLOAD (Line 3) Parents: 106325 63.7% 6434 54.9% 99891 64.4% 1 50.0% HR.UTILS.COPY_IMAGE (Line 3) 60535 36.3% 5279 45.1% 55256 35.6% 1 50.0% HR.UTILS.COPY_FILE (Line 8)) Children: 71818 46.3% 71818 100% 0 N/A 2 100% HR.P.__static_sql_exec_line38 (Line 38) 67649 43.6% 67649 100% 0 N/A 214 100% SYS.DBMS_LOB.WRITEAPPEND (Line 926) 12487 8.0% 3969 100% 8518 100% 216 100% SYS.UTL_FILE.GET_RAW (Line 1089) 1401 0.9% 1401 100% 0 N/A 2 100% HR.P.__static_sql_exec_line39 (Line 39) 839 0.5% 839 100% 0 N/A 214 100% SYS.UTL_FILE.GET_RAW (Line 246) 740 0.5% 73 100% 667 100% 2 100% SYS.UTL_FILE.FOPEN (Line 422) 113 0.1% 11 100% 102 100% 2 100% SYS.UTL_FILE.FCLOSE (Line 585) 100 0.1% 100 100% 0 N/A 2 100% SYS.DBMS_LOB.CREATETEMPORARY (Line 536)
HTML Difference Report from Two Raw Profiler Output Files
% cd
target_directory
% plshprof -output html_root_filename profiler_output_filename_1 profiler_output_filename_2
target_directory is the directory in which you want the HTML files to be created.html_root_filename is the name of the root HTML file to be created.profiler_output_filename_1 and profiler_output_filename_2 are the names of raw profiler output files.plshprof command generates a set of HTML files. Start browsing them from html_root_filename.html.
Difference Report Conventions
# after a function name means that the function was called in only one run.
First Page of Difference Report
Function Rel% Ind% Calls Rel% Function Name 2075627 +941% 61.1% 0 HR.P.G (Line 35) 1101384 +54.6% 32.4% 5 +55.6% HR.P.H (Line 18) 222371 6.5% 1 HR.P.J (Line 10)
Function Rel% Ind% Calls Rel% Function Name -467051 -50.0% 67.7% -2 -50.0% HR.P.F (Line 25) -222737 32.3% -1 HR.P.I (Line 2)# -5 -21.7% 0.0% 0 HR.P.TEST (Line 46)
Function-Level Difference Reports
HR.P.G, the function time increased by 2,075,627 microseconds (941%), which accounts for 61.1% of all regressions.HR.P.H, the function time and number of calls increased by 1,101,384 microseconds (54.6%) and 5 (55.6%), respectively, but the mean function time improved by 1,346 microseconds (-0.6%).HR.P.J was called in only one run.
Subtree Function Rel% Ind% Cum% Descendant Calls Rel% Mean Function Rel% Function Name 4075787 2075627 +941% 61.1% 61.1% 2000160 0 2075627 +941% HR.P.G (Line 35) 1101384 1101384 +54.6% 32.4% 93.5% 0 5 +55.6% -1346 -0.6% HR.P.H (Line 18) 222371 222371 6.5% 100% 0 1 HR.P.J (Line 10)#
Subtree Function Rel% Ind% Cum% Descendant Calls Rel% Mean Function Rel% Function Name -1365827 -467051 -50.0% 67.7% 67.7% -898776 -2 -50.0% -32 0.0% HR.P.F (Line 25) -222737 -222737 32.3% 100% 0 -1 HR.P.I (Line 2) 2709589 -5 -21.7% 0.0% 100% 2709594 0 -5 -20.8 HR.P.TEST (Line 46)#
Subtree Function Rel% Ind% Descendant Calls Rel% Mean Function Rel% Function Name 1101384 1101384 +54.6% 32.4% 0 5 +55.6% -1346 -0.6% HR.P.H (Line 18) -1365827 -467051 +50.0% 67.7% -898776 -2 -50.0% -32 -0.0% HR.P.F (Line 25) -222377 -222377 32.3% 0 -1 HR.P.I (Line 2)# 222371 222371 6.5% 0 1 HR.P.J(Line 10)# 4075787 2075627 +941% 61.1% 2000160 0 2075627 +941% HR.P.G (Line 35) 2709589 -5 -21.7% 0.0% 2709594 0 -5 -20.8% HR.P.TEST (Line 46) 0 0 0 0 SYS.DBMS_HPROF.STOP_PROFILING (Line 53)
Module-Level Difference Reports
Module Calls Module Name 2709589 3 HR.P 0 0 SYS.DBMS_HPROF
Namespace-Level Difference Reports
Function Calls Namespace 2709589 3 PLSQL
Parents and Children Difference Report for a Function
HR.P.X.HR.P.G called HR.P.X nine more times in the second run than it did in the first run, while HR.P.F called it four fewer times.HR.P.X called each child five more times in the second run than it did in the first run.
Subtree Function Descendant Calls Function Name 3322196 1094099 2228097 5 HR.P.X (Line 11) Parents: 6037490 1993169 4044321 9 HR.P.G (Line 38) -2715294 -899070 -1816224 -4 HR.P.F (Line 28) Children: 1125489 1125489 0 5 HR.P.J (Line 10) 1102608 1102608 0 5 HR.P.I (Line 2) HR.P.X:
HR.P.X (Line 11) First Trace Ind% Second Trace Ind% Diff Diff% Function Elapsed Time (microsecs) 1999509 26.9% 3093608 24.9% 1094099 +54.7% Descendants Elapsed Time (microsecs) 4095943 55.1% 6324040 50.9% 2228097 +54.4% Subtree Elapsed Time (microsecs) 6095452 81.9% 9417648 75.7% 3322196 +54.5% Function Calls 9 25.0% 14 28.6% 5 +55.6% Mean Function Elapsed Time (microsecs) 222167.7 220972.0 -1195.7 -0.5% Mean Descendants Elapsed Time (microsecs) 455104.8 451717.1 -3387.6 -0.7% Mean Subtree Elapsed Time (microsecs) 677272.4 672689.1 -4583.3 -0.7%
PK 6P P PK |%A OEBPS/adfns_cqn.htm
19 Edition-Based Redefinition
Editions
ora$base.
Editioned and Noneditioned Objects
OBJECT_NAME, OWNER, and EDITION_NAME. A noneditioned object is uniquely identified by its OBJECT_NAME and OWNER—its EDITION_NAME is NULL. (Strictly speaking, the NAMESPACE of an object is also required to uniquely identify the object, but you can ignore this fact, because any statement that references the object implicitly or explicitly specifies its NAMESPACE.)OBJECT_NAME, OWNER, and EDITION_NAME of an object with the static data dictionary views *_OBJECTS and *_OBJECTS_AE (described in Table 19-1).EDITION_NAME of an object to refer to that object (and if you do know it, you cannot specify it). The context of the reference implicitly specifies the edition. If the context is a data definition language (DDL) statement, the edition is the current edition of the session that issued the command (for information about the current edition, see "Current Edition and Session Edition"). If the context is source code, the edition is the one in which the object is actual (see "Inherited and Actual Objects").
Editionable and Noneditionable Schema Object Types
SYNONYMVIEWFUNCTIONLIBRARYPACKAGE and PACKAGE BODYPROCEDURETRIGGERTYPE and TYPE BODY
SYNONYM is an editionable type, a public synonym is a noneditioned object.
Rules for Editioned Objects
FOREIGN KEY constraint.
Enabling Editions for a User
ENABLE EDITIONS clause of either the CREATE USER or ALTER USER statement.EDITIONS_ENABLED column of the static data dictionary view DBA_USERS or USER_USERS shows which users have editions enabled.FORCE:
ALTER USER user_name ENABLE EDITIONS FORCE;
FORCE is useful in the following situation: You must editions-enable users A and B. User A owns potentially editioned objects a1 and a2. User B owns potentially editioned objects b1 and b2. Object a1 depends on object b1. Object b2 depends on object a2. Editions-enable users A and B like this:FORCE, enable editions for user A:
ALTER USER A ENABLE EDITIONS FORCE;
a1 and a2 are editioned objects, and b2 (which depends on a2) is invalid.B:
ALTER USER B ENABLE EDITIONS;
b2, using the appropriate ALTER statement with COMPILE. For a PL/SQL object, also specify REUSE SETTINGS.b2 is a procedure, use this statement:
ALTER PROCEDURE b2 COMPILE REUSE SETTINGS
ALTER statements for PL/SQL objects, see Oracle Database PL/SQL Language Reference.ALTER statements for SQL objects, see Oracle Database SQL Language Reference.FORCE is unnecessary in the following situation: You must editions-enable user C, who owns potentially editioned object c1. Object c1 has dependent d1, a potentially editioned object owned by user D. User D owns no potentially editioned objects that have dependents owned by C. If you editions-enable D first, making d1 an editioned object, then you can editions-enable C without violating the rule that a noneditioned object cannot depend on an editioned object.ALTER TYPE RESET statement to reset its version to 1, so that it is no longer considered to be evolved. (Resetting the version of an ADT to 1 invalidates its dependents.)
CREATE USERand ALTER USER statements*_USERS
Creating an Edition
CREATE EDITION.CREATE EDITION statement is ora$base. This statement creates the edition e2 as the child of ora$base:
CREATE EDITION e2
CREATE EDITION statement, including the privileges required to use it
Inherited and Actual Objects
DROP), the inherited object is copied and the DDL statement affects only the copy—the actual object. The unchanged object in the parent edition is no longer visible in the child edition.
CREATE OR REPLACE object has no effect, it does not actualize object (for details, see "Invalidation of Dependent Objects"). The DDL statement ALTER object COMPILE always actualizes object.hello in the edition ora$base, and then creates the edition e2 as a child of ora$base. When e2 invokes hello, it invokes the inherited procedure. Then e2 changes hello, actualizing it. The procedure hello in the edition ora$base remains unchanged, and is no longer visible in e2. Now when e2 invokes hello, it invokes the actual procedure.
CREATE OR REPLACE PROCEDURE hello IS
BEGIN
DBMS_OUTPUT.PUT_LINE('Hello, edition 1.');
END hello;
/
BEGIN hello(); END;
/
Hello, edition 1.
PL/SQL procedure successfully completed.
CREATE EDITION e2;
ALTER SESSION SET EDITION = e2;
ALTER SESSION SET EDITION, see "Changing Your Session Edition".
BEGIN hello(); END;
/
Hello, edition 1.
PL/SQL procedure successfully completed.
CREATE OR REPLACE PROCEDURE hello IS
BEGIN
DBMS_OUTPUT.PUT_LINE('Hello, edition 2.');
END hello;
/
BEGIN hello(); END;
/
Hello, edition 2.
PL/SQL procedure successfully completed.
ALTER SESSION SET EDITION = ora$base;
BEGIN hello(); END;
/
Hello, edition 1.
PL/SQL procedure successfully completed.
Dropping Inherited Objects
goodbye in the edition ora$base, and then creates edition e2 as a child of ora$base. After e2 drops goodbye, it can no longer invoke it, but ora$base can still invoke it. (For more information about the DROP PROCEDURE statement, including the privileges required to use it, see Oracle Database PL/SQL Language Reference.)
ora$base:
CREATE OR REPLACE PROCEDURE goodbye IS
BEGIN
DBMS_OUTPUT.PUT_LINE('Good-bye!');
END goodbye;
/
BEGIN goodbye; END;
/
Good-bye!
PL/SQL procedure successfully completed.
e2 as a child of ora$base:
CREATE EDITION e2;
e2:
ALTER SESSION SET EDITION = e2;
ALTER SESSION SET EDITION must be a top-level SQL statement. For more information, see "Changing Your Session Edition".e2, invoke procedure:
BEGIN goodbye; END;
/
e2 invokes inherited procedure:
Good-bye!
PL/SQL procedure successfully completed.
e2, drop procedure:
DROP PROCEDURE goodbye;
e2, try to invoke dropped procedure:
BEGIN goodbye; END;
/
BEGIN goodbye; END;
*
ERROR at line 1:
ORA-06550: line 1, column 7:
PLS-00201: identifier 'GOODBYE' must be declared
ORA-06550: line 1, column 7:
PL/SQL: Statement ignored
ALTER SESSION SET EDITION = ora$base;
BEGIN goodbye; END;
/
Good-bye!
PL/SQL procedure successfully completed.
e2 dropped the procedure goodbye:goodbye.goodbye is visible in e2, so e2 can create an object named goodbye of any editionable type. If e2 creates this object, the descendents of e2 inherit that object.e2 creates a function named goodbye and then an edition named e3 as a child of e2. When e3 tries to invoke the procedure goodbye (which e2 dropped), an error occurs, but e3 successfully invokes the function goodbye (which e2 created).
e2:
ALTER SESSION SET EDITION = e2;
ALTER SESSION SET EDITION, see "Changing Your Session Edition".e2, create function named goodbye:
CREATE OR REPLACE FUNCTION goodbye
RETURN BOOLEAN
IS
BEGIN
RETURN(TRUE);
END goodbye;
/
e3:
CREATE EDITION e3 AS CHILD OF e2;
e3:
ALTER SESSION SET EDITION = e3;
e3, try to invoke procedure goodbye:
BEGIN
goodbye;
END;
/
goodbye;
*
ERROR at line 2:
ORA-06550: line 2, column 3:
PLS-00221: 'GOODBYE' is not a procedure or is undefined
ORA-06550: line 2, column 3:
PL/SQL: Statement ignored
e3, invoke function goodbye:
BEGIN
IF goodbye THEN
DBMS_OUTPUT.PUT_LINE('Good-bye!');
END IF;
END;
/
Good-bye!
PL/SQL procedure successfully completed.
Actualizing Referenced Objects
Making an Edition Available to Some Users
USE privilege WITH GRANT OPTION on it. To grant the USE privilege on the edition to other users, use the SQL statement GRANT USE ON EDITION. For information about the GRANT statement, see Oracle Database SQL Language Reference.
Making an Edition Available to All Users
USE privilege on the edition to PUBLIC:
GRANT USE ON EDITION edition_name TO PUBLIC
GRANT statement, see Oracle Database SQL Language Reference.
ALTER DATABASE DEFAULT EDITION = edition_name
USE privilege on edition_name to PUBLIC.ALTER DATABASE statement, see Oracle Database SQL Language Reference.
Current Edition and Session Edition
Your Initial Session Edition
USE privilege. To see the names of the editions that are available to you, use this query:
SELECT EDITION_NAME FROM ALL_EDITIONS;
srvctl add service or srvctl modify service command. To specify the default initial session edition of the service, use the -t option.DBMS_SERVICE.CREATE_SERVICE or DBMS_SERVICE.MODIFY_SERVICE procedure, and specify the default initial session edition of the service with the EDITION attribute.
DBMS_SERVICE.CREATE_SERVICE and DBMS_SERVICE.MODIFY_SERVICE procedures are deprecated in databases managed by Oracle Clusterware and Oracle Restart.
-t option of the srvctl add service command-t option of the srvctl modify service commandEDITION attribute of the DBMS_SERVICE.CREATE_SERVICE procedureEDITION attribute of the DBMS_SERVICE.MODIFY_SERVICE procedure
Changing Your Session Edition
ALTER SESSION SET EDITION. You can change your session edition to any edition on which you have the USE privilege. When you change your session edition, your current edition changes to the same thing.e2 and later to ora$base:
ALTER SESSION SET EDITION = e2
...
ALTER SESSION SET EDITION = ora$base
ALTER SESSION SET EDITION must be a top-level SQL statement. To defer an edition change (in a logon trigger, for example), use the DBMS_SESSION.SET_EDITION_DEFERRED procedure.
ALTER SESSION SET EDITION statementDBMS_SESSION.SET_EDITION_DEFERRED procedure
Displaying the Names of the Current and Session Editions
SELECT SYS_CONTEXT('USERENV', 'CURRENT_EDITION_NAME') FROM DUAL;
SELECT SYS_CONTEXT('USERENV', 'SESSION_EDITION_NAME') FROM DUAL;
SYS_CONTEXT function
When the Current Edition Might Differ from the Session Edition
DBMS_SQL.PARSE procedure, specifying the edition in which the statement is to run, as in Example 19-4.DBMS_SQL.PARSE procedure, see Oracle Database PL/SQL Packages and Types Reference.DBMS_SQL.PARSE procedure.
CREATE OR REPLACE FUNCTION session_and_current_editions
RETURN VARCHAR2
IS
BEGIN
RETURN
'Session: '|| SYS_CONTEXT('USERENV', 'SESSION_EDITION_NAME') ||
' / ' ||
'Current: '|| SYS_CONTEXT('USERENV', 'CURRENT_EDITION_NAME');
END session_and_current_editions;
/
CREATE EDITION e2 AS CHILD OF ora$base;
ALTER SESSION SET EDITION = e2;
BEGIN
DBMS_OUTPUT.PUT_LINE (session_and_current_editions());
END;
/
Session: E2 / Current: E2
PL/SQL procedure successfully completed.
DECLARE
c NUMBER := DBMS_SQL.OPEN_CURSOR();
v VARCHAR2(200);
dummy NUMBER;
stmt CONSTANT VARCHAR2(32767)
:= 'SELECT session_and_current_editions() FROM DUAL';
BEGIN
DBMS_SQL.PARSE (c => c,
statement => stmt,
language_flag => DBMS_SQL.NATIVE,
edition => 'ora$base');
DBMS_SQL.DEFINE_COLUMN (c, 1, v, 200);
dummy := DBMS_SQL.EXECUTE_AND_FETCH (c, true);
DBMS_SQL.COLUMN_VALUE (c, 1, v);
DBMS_SQL.CLOSE_CURSOR(c);
DBMS_OUTPUT.PUT_LINE (v);
END;
/
Session: E2 / Current: ORA$BASE
PL/SQL procedure successfully completed.
Retiring an Edition
SYS can use the retired edition.
ALTER DATABASE DEFAULT EDITION = edition_name
ALTER DATABASE statement, see Oracle Database SQL Language Reference.USE privilege on the edition from every grantee. To list the grantees, use this query, where :e is a placeholder for the name of the edition to be dropped:
SELECT GRANTEE, PRIVILEGE
FROM DBA_TAB_PRIVS
WHERE TABLE_NAME = :e
/
REVOKE statement, see Oracle Database SQL Language Reference.
Dropping an Edition
DROP EDITION statement, described in Oracle Database SQL Language Reference. If the edition has actual objects, you must specify the CASCADE clause, which drops the actual objects.DROP EDITION edition CASCADE statement is interrupted before finishing normally (from a power failure, for example), the static data dictionary view *_EDITIONS shows that the value of USABLE for edition is NO. The only operation that you can perform on such an unusable edition is DROP EDITION CASCADE.ALTER statement with COMPILE. For a PL/SQL object, also specify REUSE SETTINGS.p1:
ALTER PROCEDURE p1 COMPILE REUSE SETTINGS
ALTER statements for PL/SQL objects, see Oracle Database PL/SQL Language Reference.ALTER statements for SQL objects, see Oracle Database SQL Language Reference.
ALTER LIBRARY statementALTER VIEW statementALTER FUNCTION statementALTER PACKAGE statementALTER PROCEDURE statementALTER TRIGGER statementALTER TYPE statement
Editioning Views
INSTEAD OF trigger. On an editioning view, you can define every type of trigger that you can define on a table (except crossedition triggers, which are temporary, and INSTEAD OF triggers). Therefore, and because they can be editioned, editioning views let you treat their base tables as if the base tables were editioned. However, you cannot add indexes or constraints to an editioning view; if your upgraded application requires new indexes or constraints, you must add them to the base table.SELECT, INSERT, UPDATE, DELETE, or MERGE statement uses one or more editioning views, one or more times, and you replace each editioning view name with the name of its base table and adjust the column names if necessary, performance does not change.*_EDITIONING_VIEWS describes every editioning view in the database that is visible (actual or inherited) in the session edition. *_EDITIONING_VIEWS_AE describes every actual object in every editioning view in the database, in every edition.
*_EDITIONING_VIEWS and *_EDITIONING_VIEWS_AE.
Creating an Editioning View
CREATE VIEW with the keyword EDITIONING. To make the editioning view read-only, specify WITH READ ONLY; to make it read-write, omit WITH READ ONLY.CREATE VIEW statement that creates an editioning view has restrictions. Violating the restrictions causes the creation of the view to fail, even if you specify FORCE.
CREATE VIEW statement to create editioning views, including the restrictions
Partition-Extended Editioning View Names
DELETEINSERTSELECTUPDATE
Changing the 'Write-ability' of an Editioning View
ALTER VIEW READ WRITE. To change an existing editioning view from read-write to read-only, use the SQL statement ALTER VIEW READ ONLY.
ALTER VIEW statement
Replacing an Editioning View
CREATE VIEW with the OR REPLACE clause and the keyword EDITIONING.
Dropping or Renaming the Base Table
Adding Indexes and Constraints to the Base Table
INDEX hints.
INDEX hints
SQL Optimizer Index Hints
Crossedition Triggers
Forward Crossedition Triggers
Reverse Crossedition Triggers
Crossedition Trigger Interaction with Editions
Which Triggers Are Visible
What Kind of Triggers Can Fire
APPEND hint on a SQL INSERT statement does not prevent crossedition triggers from firing. For information about the APPEND hint, see Oracle Database SQL Language Reference.
Forward Crossedition Trigger SQL
DBMS_SQL.PARSE procedure with a non-NULL value for the apply_crossedition_trigger parameterNULL value for the apply_crossedition_trigger parameter is the unqualified name of a forward crossedition trigger. For more information about the DBMS_SQL.PARSE procedure, see Oracle Database PL/SQL Packages and Types Reference.DBMS_SQL.PARSE procedure with a non-NULL value for the apply_crossedition_trigger parameter.
Reverse Crossedition Trigger SQL
Application SQL
DBMS_SQL package (for information about these statements, see Oracle Database PL/SQL Language Reference).CALL triggers)
Kind of Trigger Conditions Under Which Trigger Can Fire Noncrossedition Trigger is both visible and enabled in the current edition. Forward crossedition Trigger was created in a descendent of the current edition. Reverse crossedition Trigger was created either in the current edition or in an ancestor of the current edition.
Firing Order
WHEN clause)
FOLLOWS and PRECEDES Clauses
UPDATE OF clause are modifiedWHEN clauses are satisfiedINSERT, UPDATE, or DELETE)
Trigger Type and Edition
FOLLOWS relationships apply; in categories 4 and 5, PRECEDES relationships apply.
Crossedition Trigger Execution
Creating a Crossedition Trigger
CREATE TRIGGER, observing these rules:REVERSE. (Specifying FORWARD is optional.)FOLLOWS clause is allowed only when creating a forward crossedition trigger or a noncrossedition trigger. (The FOLLOWS clause indicates that the trigger being created is to fire after the specified triggers fire.)PRECEDES clause is allowed only when creating a reverse crossedition trigger. (The PRECEDES clause indicates that the trigger being created is to fire before the specified triggers fire.)FOLLOWS or PRECEDES clause must exist, but need not be enabled or successfully compiled.DISABLE. (Specifying ENABLE is optional.)
CREATE TRIGGER statement to create crossedition triggers
Coding the Forward Crossedition Trigger Body
Handling Data Transformation Collisions
UNIQUE constraint. A serendipitous change fires the forward crossedition trigger, which inserts a row in the new table. Later, another serendipitous change fires the forward crossedition trigger, or you apply the transform defined by the trigger. The trigger tries to insert a row in the new table, violating the UNIQUE constraint.APPLYING_CROSSEDITION_TRIGGER. When called directly from a trigger body, this function returns the BOOLEAN value TRUE if the trigger is running because of a serendipitous change and FALSE if the trigger is running because you are applying the transform. (APPLYING_CROSSEDITION_TRIGGER is defined in the package DBMS_STANDARD. It has no parameters.)IGNORE_ROW_ON_DUPKEY_INDEX hint in the INSERT statement.CHANGE_DUPKEY_ERROR_INDEX hint in the INSERT or UPDATE statement, specifying either an index or set of columns. Then, when a unique key violation occurs for that index or set of columns, ORA-38911 is reported instead of ORA-00001. You can write an exception handler for ORA-38911.
IGNORE_ROW_ON_DUPKEY_INDEX and CHANGE_DUPKEY_ERROR_INDEX are mandates. The optimizer always uses them.APPLYING_CROSSEDITION_TRIGGER function and the IGNORE_ROW_ON_DUPKEY_INDEX and CHANGE_DUPKEY_ERROR_INDEX hints to handle data transformation collisions. The trigger transforms old rows in table1 to new rows in table2. The tables were created as follows:
CREATE TABLE table1 (key NUMBER, value VARCHAR2(20));
CREATE TABLE table2 (key NUMBER, value VARCHAR2(20), last_updated TIMESTAMP);
CREATE UNIQUE INDEX i2 on table2(key);
CREATE OR REPLACE TRIGGER trigger1
BEFORE INSERT OR UPDATE ON table1
FOR EACH ROW
CROSSEDITION
DECLARE
row_already_present EXCEPTION;
PRAGMA EXCEPTION_INIT(row_already_present, -38911);
BEGIN
IF APPLYING_CROSSEDITION_TRIGGER THEN
/* Trigger is running because of serendipitous change.
Insert new row into table2 unless it is already there. */
INSERT /*+ IGNORE_ROW_ON_DUPKEY_INDEX(table2(key)) */
INTO table2
VALUES(:new.key, :new.value, to_date('1900-01-01', 'YYYY-MM-DD'));
ELSE
/* Trigger is running because you are applying transform.
If tranform has not yet inserted new row in table2, insert new row;
otherwise, update new row. */
BEGIN
INSERT /*+ CHANGE_DUPKEY_ERROR_INDEX(table2(key)) */
INTO table2
VALUES(:new.key, :new.value, SYSTIMESTAMP);
EXCEPTION WHEN row_already_present THEN
UPDATE table2
SET value = :new.value, last_updated = SYSTIMESTAMP
WHERE key = :new.key;
END;
END IF;
END;
/
IGNORE_ROW_ON_DUPKEY_INDEXCHANGE_DUPKEY_ERROR_INDEX
Handling Changes to Other Tables
Transforming Data from Pre- to Post-Upgrade Representation
DBMS_SQL.PARSE procedure or the subprograms in the DBMS_PARALLEL_EXECUTE package. The latter is recommended if you have a lot of data. The subprograms enable you to incrementally update the data in a large table in parallel, in two high-level steps:UPDATE statement to the chunks in parallel, committing each time you have finished processing a chunk.DBMS_SQL.PARSE procedure and the DBMS_PARALLEL_EXECUTE subprograms, the actual parameter values for apply_crossedition_trigger, fire_apply_trigger, and sql_stmt are the same:apply_crossedition_trigger, specify the name of the forward crossedition trigger that defines the transform to be applied.fire_apply_trigger, specify TRUE.sql_stmt, supply a SQL statement whose only significant effect is to select the forward crossedition trigger to be fired; for example, an UPDATE statement that sets some column to its own existing value in each row.fire_apply_trigger, specify FALSE.sql_stmt, supply a SQL statement that does what the forward crossedition trigger would do, but faster—for example, a PL/SQL anonymous block that calls one or more PL/SQL subprograms.
DBMS_SQL.PARSE procedureDBMS_PARALLEL_EXECUTE package
Preventing Lost Updates
DBMS_UTILITY.WAIT_ON_PENDING_DML, described in Oracle Database PL/SQL Packages and Types Reference.
UPDATE statement against the table when the crossedition trigger is not yet enabled; and that Session Two then enables the crossedition trigger and immediately applies the transformation.
Dropping the Crossedition Triggers
DROP TRIGGER statement, described in Oracle Database PL/SQL Language Reference. Alternatively, you can drop crossedition triggers by dropping the edition in which they are actual, by using the DROP EDITION statement with the CASCADE clause. For information about dropping editions, see "Dropping an Edition".ALTER TABLE statement with the DISABLE CONSTRAINT or DROP CONSTRAINT clause. For information about the ALTER TABLE statement, see Oracle Database SQL Language Reference.
Displaying Information About Editions, Editioning Views, and Crossedition Triggers
V$SQL_SHARED_CURSOR and GV$SQL_SHARED_CURSOR have a CROSSEDITION_TRIGGER_MISMATCH column that tells whether this is true. For information about V$SQL_SHARED_CURSOR, see Oracle Database Reference.
*_OBJECTS and *_OBJECTS_AE include dependent objects that are invalidated by operations in Table 18-2 only after one of the following:
DBMS_UTILITY.COMPILE_SCHEMA (described in Oracle Database PL/SQL Packages and Types Reference)UTL_RECOMP subprogram (described in Oracle Database PL/SQL Packages and Types Reference)
View Description
*_OBJECTS_AE for additional information.
*_OBJECTS_AE, *_TAB_COL, or both, for additional information.
*_EDITIONING_VIEWS matches exactly one row of *_VIEWS, and each row of *_VIEWS that has EDITIONING_VIEW = 'Y' matches exactly one row of *_EDITIONING_VIEWS. Therefore, in this example, the WHERE clause is redundant:
SELECT ...
FROM DBA_EDITIONING_VIEWS INNER JOIN DBA_VIEWS
USING (OWNER, VIEW_NAME)
WHERE EDITIONING_VIEW = 'Y'
AND ...
*_VIEWS that matches a row of *_EDITIONING_VIEWS has EDITIONING_VIEW = 'Y' by definition. Conversely, no row of *_VIEWS that has EDITIONING_VIEW = 'N' has a counterpart in *_ EDITIONING_VIEWS.
Using Edition-Based Redefinition to Upgrade an Application
Preparing Your Application to Use Editioning Views
*_POLICIES, which describe the VPD policies, can have different results in different editions.
*_POLICIESData, the new table name might be Data_1.Name and Number might be changed to Name_1 and Number_1.ALTER TABLE table RENAME column in Table 18-2.
SELECT GRANTEE, PRIVILEGE
FROM DBA_TAB_PRIVS
WHERE TABLE_NAME='table_name';
Procedure for Edition-Based Redefinition Using Only Editions
*_OBJECTS_AE, which describes every actual object in the database, in every edition. If invalid objects remain, recompile them, using any UTL_RECOMP subprogram (described in Oracle Database PL/SQL Packages and Types Reference).SYS use only the upgraded application.
CREATE OR REPLACE PROCEDURE hello IS
BEGIN
DBMS_OUTPUT.PUT_LINE('Hello, edition 1.');
END hello;
/
BEGIN hello(); END;
/
Hello, edition 1.
PL/SQL procedure successfully completed.
CREATE EDITION e2 AS CHILD OF ora$base;
Edition created.
ALTER SESSION SET EDITION = e2;
Session altered.
CREATE OR REPLACE PROCEDURE hello IS
BEGIN
DBMS_OUTPUT.PUT_LINE('Hello, edition 2.');
END hello;
/
Procedure created.
BEGIN hello(); END;
/
Hello, edition 2.
PL/SQL procedure successfully completed.
ALTER DATABASE DEFAULT EDITION = e2;
SELECT GRANTEE, PRIVILEGE
FROM DBA_TAB_PRIVS
WHERE TABLE_NAME = UPPER('ora$base')
/
GRANTEE PRIVILEGE
------------------------------ ---------
PUBLIC USE
1 row selected.
REVOKE USE ON EDITION ora$base FROM PUBLIC;
Procedure for Edition-Based Redefinition Using Editioning Views
*_OBJECTS_AE, which describes every actual object in the database, in every edition. If invalid objects remain, recompile them, using any UTL_RECOMP subprogram (described in Oracle Database PL/SQL Packages and Types Reference).SYS use only the upgraded application.
Procedure for Edition-Based Redefinition Using Crossedition Triggers
*_OBJECTS_AE, which describes every actual object in the database, in every edition. If invalid objects remain, recompile them, using any UTL_RECOMP subprogram (described in Oracle Database PL/SQL Packages and Types Reference).ALTER TRIGGER statement with the ENABLE option. For information about this statement, see Oracle Database PL/SQL Language Reference.DBMS_UTILITY.WAIT_ON_PENDING_DML, described in Oracle Database PL/SQL Packages and Types Reference.
USE privilege on your session edition to the early users of the upgraded application.SYS use only the upgraded application.
Rolling Back the Application Upgrade
Reclaiming Space Occupied by Unused Table Columns
NULL.DBMS_PARALLEL_EXECUTE procedure (described in Oracle Database PL/SQL Packages and Types Reference).UNUSED.ALTER TABLE statement (described in Oracle Database SQL Language Reference) with the SET UNUSED clause (described in Oracle Database SQL Language Reference).ALTER TABLE statement (described in Oracle Database SQL Language Reference) with the SHRINK SPACE clause (described in Oracle Database SQL Language Reference).
Example: Using Edition-Based Redefinition to Upgrade an Application
Existing Application
CREATE TABLE Contacts(
ID NUMBER(6,0) CONSTRAINT Contacts_PK PRIMARY KEY,
Name VARCHAR2(47),
Phone_Number VARCHAR2(20)
);
ALTER TABLE Contacts ENABLE VALIDATE CONSTRAINT Contacts_PK;
DECLARE Max_ID INTEGER;
BEGIN
SELECT MAX(ID) INTO Max_ID FROM Contacts;
EXECUTE IMMEDIATE '
CREATE SEQUENCE Contacts_Seq
START WITH '||To_Char(Max_ID + 1);
END;
/
CREATE TRIGGER Contacts_BI
BEFORE INSERT ON Contacts FOR EACH ROW
BEGIN
:NEW.ID := Contacts_Seq.NEXTVAL;
END;
/
Contacts looks after being populated with data.
SELECT * FROM Contacts
ORDER BY Name;
ID NAME PHONE_NUMBER
---------- ----------------------------------------------- --------------------
174 Abel, Ellen 011.44.1644.429267
166 Ande, Sundar 011.44.1346.629268
130 Atkinson, Mozhe 650.124.6234
105 Austin, David 590.423.4569
204 Baer, Hermann 515.123.8888
116 Baida, Shelli 515.127.4563
167 Banda, Amit 011.44.1346.729268
172 Bates, Elizabeth 011.44.1343.529268
192 Bell, Sarah 650.501.1876
151 Bernstein, David 011.44.1344.345268
129 Bissot, Laura 650.124.5234
169 Bloom, Harrison 011.44.1343.829268
185 Bull, Alexis 650.509.2876
187 Cabrio, Anthony 650.509.4876
148 Cambrault, Gerald 011.44.1344.619268
154 Cambrault, Nanette 011.44.1344.987668
110 Chen, John 515.124.4269
...
120 Weiss, Matthew 650.123.1234
200 Whalen, Jennifer 515.123.4444
149 Zlotkey, Eleni 011.44.1344.429018
107 rows selected.
Contacts, replacing the Name column with the columns First_Name and Last_Name, and adding the column Country_Code. Also suppose that while you are making this structural change, other users must be able to change the data in Contacts.
Preparing the Application to Use Editioning Views
Contacts while you are redefining it in the new edition.
ALTER TABLE Contacts RENAME TO Contacts_Table;
ALTER TABLE Contacts_Table
RENAME COLUMN Name TO Name_1;
ALTER TABLE Contacts_Table
RENAME COLUMN Phone_Number TO Phone_Number_1;
CREATE OR REPLACE EDITIONING VIEW Contacts AS
SELECT
ID ID,
Name_1 Name,
Phone_Number_1 Phone_Number
FROM Contacts_Table;
Contacts_BI from table to editioning view:
DROP TRIGGER Contacts_BI;
CREATE TRIGGER Contacts_BI
BEFORE INSERT ON Contacts FOR EACH ROW
BEGIN
:NEW.ID := Contacts_Seq.NEXTVAL;
END;
/
Using Edition-Based Redefinition to Upgrade the Application
CREATE EDITION Post_Upgrade AS CHILD OF Ora$Base;
ALTER SESSION SET EDITION = Post_Upgrade;
SELECT
SYS_CONTEXT('Userenv', 'Current_Edition_Name') "Current_Edition"
FROM DUAL;
Current_Edition
-----------------------------------------------------------------------------
POST_UPGRADE
1 row selected.
Post_Upgrade edition, Example 19-11 shows how to add the new columns to the physical table and recompile the trigger that was invalidated by adding the columns. Then, it shows how to replace the editioning view Contacts so that it selects the columns of the table by their desired logical names.
ALTER TABLE Contacts_Table ADD (
First_Name_2 varchar2(20),
Last_Name_2 varchar2(25),
Country_Code_2 varchar2(20),
Phone_Number_2 varchar2(20)
);
ALTER TRIGGER Contacts_BI COMPILE REUSE SETTINGS;
CREATE OR REPLACE EDITIONING VIEW Contacts AS
SELECT
ID ID,
First_Name_2 First_Name,
Last_Name_2 Last_Name,
Country_Code_2 Country_Code,
Phone_Number_2 Phone_Number
FROM Contacts_Table;
Post_Upgrade edition, Example 19-12 shows how to create two procedures for the forward crossedition trigger to use, create both the forward and reverse crossedition triggers in the disabled state, and enable them.
CREATE OR REPLACE PROCEDURE Set_First_And_Last_Name (
Name IN VARCHAR2,
First_Name OUT VARCHAR2,
Last_Name OUT VARCHAR2)
IS
Comma_Pos NUMBER := INSTR(Name, ',');
BEGIN
IF Comma_Pos IS NULL OR Comma_Pos < 2 THEN
RAISE Program_Error;
END IF;
Last_Name := SUBSTR(Name, 1, Comma_Pos-1);
Last_Name := RTRIM(Ltrim(Last_Name));
First_Name := SUBSTR(Name, Comma_Pos+1);
First_Name := RTRIM(LTRIM(First_Name));
END Set_First_And_Last_Name;
/
CREATE OR REPLACE PROCEDURE Set_Country_Code_And_Phone_No (
Phone_Number IN VARCHAR2,
Country_Code OUT VARCHAR2,
Phone_Number_V2 OUT VARCHAR2)
IS
Char_To_Number_Error EXCEPTION;
PRAGMA EXCEPTION_INIT(Char_To_Number_Error, -06502);
Bad_Phone_Number EXCEPTION;
Nmbr VARCHAR2(30) := REPLACE(Phone_Number, '.', '-');
FUNCTION Is_US_Number(Nmbr IN VARCHAR2)
RETURN BOOLEAN
IS
Len NUMBER := LENGTH(Nmbr);
Dash_Pos NUMBER := INSTR(Nmbr, '-');
n PLS_INTEGER;
BEGIN
IF Len IS NULL OR Len <> 12 THEN
RETURN FALSE;
END IF;
IF Dash_Pos IS NULL OR Dash_Pos <> 4 THEN
RETURN FALSE;
END IF;
BEGIN
n := TO_NUMBER(SUBSTR(Nmbr, 1, 3));
EXCEPTION WHEN Char_To_Number_Error THEN
RETURN FALSE;
END;
Dash_Pos := INSTR(Nmbr, '-', 5);
IF Dash_Pos IS NULL OR Dash_Pos <> 8 THEN
RETURN FALSE;
END IF;
BEGIN
n := TO_NUMBER(SUBSTR(Nmbr, 5, 3));
EXCEPTION WHEN Char_To_Number_Error THEN
RETURN FALSE;
END;
BEGIN
n := TO_NUMBER(SUBSTR(Nmbr, 9));
EXCEPTION WHEN Char_To_Number_Error THEN
RETURN FALSE;
END;
RETURN TRUE;
END Is_US_Number;
BEGIN
IF Nmbr LIKE '011-%' THEN
DECLARE
Dash_Pos NUMBER := INSTR(Nmbr, '-', 5);
BEGIN
Country_Code := '+'|| TO_NUMBER(SUBSTR(Nmbr, 5, Dash_Pos-5));
Phone_Number_V2 := SUBSTR(Nmbr, Dash_Pos+1);
EXCEPTION WHEN Char_To_Number_Error THEN
raise Bad_Phone_Number;
END;
ELSIF Is_US_Number(Nmbr) THEN
Country_Code := '+1';
Phone_Number_V2 := Nmbr;
ELSE
RAISE Bad_Phone_Number;
END IF;
EXCEPTION WHEN Bad_Phone_Number THEN
Country_Code := '+0';
Phone_Number_V2 := '000-000-0000';
END Set_Country_Code_And_Phone_No;
/
CREATE OR REPLACE TRIGGER Contacts_Fwd_Xed
BEFORE INSERT OR UPDATE ON Contacts_Table
FOR EACH ROW
FORWARD CROSSEDITION
DISABLE
BEGIN
Set_First_And_Last_Name(
:NEW.Name_1,
:NEW.First_Name_2,
:NEW.Last_Name_2
);
Set_Country_Code_And_Phone_No(
:NEW.Phone_Number_1,
:NEW.Country_Code_2,
:NEW.Phone_Number_2
);
END Contacts_Fwd_Xed;
/
ALTER TRIGGER Contacts_Fwd_Xed ENABLE;
CREATE OR REPLACE TRIGGER Contacts_Rvrs_Xed
BEFORE INSERT OR UPDATE ON Contacts_Table
FOR EACH ROW
REVERSE CROSSEDITION
DISABLE
BEGIN
:NEW.Name_1 := :NEW.Last_Name_2||', '||:NEW.First_Name_2;
:NEW.Phone_Number_1 :=
CASE :New.Country_Code_2
WHEN '+1' THEN
REPLACE(:NEW.Phone_Number_2, '-', '.')
ELSE
'011.'||LTRIM(:NEW.Country_Code_2, '+')||'.'||
REPLACE(:NEW.Phone_Number_2, '-', '.')
END;
END Contacts_Rvrs_Xed;
/
ALTER TRIGGER Contacts_Rvrs_Xed ENABLE;
DECLARE
scn NUMBER := NULL;
timeout CONSTANT INTEGER := NULL;
BEGIN
IF NOT DBMS_UTILITY.WAIT_ON_PENDING_DML(Tables => 'Contacts_Table',
timeout => timeout,
scn => scn)
THEN
RAISE_APPLICATION_ERROR(-20000,
'Wait_On_Pending_DML() timed out. CETs were enabled before SCN: '||SCN);
END IF;
END;
/
DBMS_UTILITY.WAIT_ON_PENDING_DML procedure, see Oracle Database PL/SQL Packages and Types Reference.Post_Upgrade edition, Example 19-13 shows how to apply the transforms.
DECLARE
c NUMBER := DBMS_SQL.OPEN_CURSOR();
x NUMBER;
BEGIN
DBMS_SQL.PARSE(
c => c,
Language_Flag => DBMS_SQL.NATIVE,
Statement => 'UPDATE Contacts_Table SET ID = ID',
Apply_Crossedition_Trigger => 'Contacts_Fwd_Xed'
);
x := DBMS_SQL.EXECUTE(c);
DBMS_SQL.CLOSE_CURSOR(c);
COMMIT;
END;
/
Post_Upgrade edition, Example 19-14 shows how to check that the change worked as intended. Compare Example 19-14 to Example 19-8.
COLUMN ID FORMAT 999
COLUMN Last_Name FORMAT A15
COLUMN First_Name FORMAT A15
COLUMN Country_Code FORMAT A12
COLUMN Phone_Number FORMAT A12
SELECT * FROM Contacts
ORDER BY Last_Name;
ID FIRST_NAME LAST_NAME COUNTRY_CODE PHONE_NUMBER
---- --------------- --------------- ------------ ------------
174 Ellen Abel +44 1644-429267
166 Sundar Ande +44 1346-629268
130 Mozhe Atkinson +1 650-124-6234
105 David Austin +1 590-423-4569
204 Hermann Baer +1 515-123-8888
116 Shelli Baida +1 515-127-4563
167 Amit Banda +44 1346-729268
172 Elizabeth Bates +44 1343-529268
192 Sarah Bell +1 650-501-1876
151 David Bernstein +44 1344-345268
129 Laura Bissot +1 650-124-5234
169 Harrison Bloom +44 1343-829268
185 Alexis Bull +1 650-509-2876
187 Anthony Cabrio +1 650-509-4876
154 Nanette Cambrault +44 1344-987668
148 Gerald Cambrault +44 1344-619268
110 John Chen +1 515-124-4269
...
120 Matthew Weiss +1 650-123-1234
200 Jennifer Whalen +1 515-123-4444
149 Eleni Zlotkey +44 1344-429018
107 rows selected.
PKNIy e PK |%A OEBPS/content.opfd<
11 Using Continuous Query Notification (CQN)
Object Change Notification (OCN)
EMPLOYEES table, the database sends the application an OCN, even if the changed row or rows did not satisfy the query predicate (for example, if DEPARTMENT_ID = 5).
Query Result Change Notification (QRCN)
COMPATIBLE initialization parameter of the database must be at least 11.0.0, and Automatic Undo Management (AUM) must be enabled (as it is by default).
COMPATIBLE initialization parameter, see Oracle Database Administrator's Guide.INSERT or DELETE of a row that satisfies the query predicate (DEPARTMENT_ID = 10).UPDATE to the EMPLOYEE_ID or SALARY column of a row that satisfied the query predicate (DEPARTMENT_ID = 10).UPDATE to the DEPARTMENT_ID column of a row that changed its value from 10 to a value other than 10, causing the row to be deleted from the result set.UPDATE to the DEPARTMENT_ID column of a row that changed its value to 10 from a value other than 10, causing the row to be added to the result set.QOS_QUERY in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
Guaranteed Mode
UPDATE EMPLOYEES
SET SALARY = SALARY + 10
WHERE EMPLOYEE_ID = 201;
UPDATE EMPLOYEES
SET SALARY = SALARY - 10
WHERE EMPLOYEE_ID = 201;
COMMIT;
UPDATE statement in the preceding transaction changes the query result set, but together they have no effect on the query result set; therefore, the database does not send the application a QRCN for the transaction.QOS_QUERY, but not QOS_BEST_EFFORT, in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
Best-Effort Mode
SUM.
SELECT SUM(SALARY)
FROM EMPLOYEES
WHERE DEPARTMENT_ID = 20;
SELECT SALARY
FROM EMPLOYEES
WHERE DEPARTMENT_ID = 20;
SELECT SALARY
FROM EMPLOYEES
WHERE DEPARTMENT_ID IN (
SELECT DEPARTMENT_ID
FROM DEPARTMENTS
WHERE LOCATION_ID = 1700
);
SELECT * FROM EMPLOYEES, DEPARTMENTS;
SELECT SALARY
FROM EMPLOYEES, DEPARTMENTS
WHERE EMPLOYEES.DEPARTMENT_ID = DEPARTMENTS.DEPARTMENT_ID
AND DEPARTMENTS.LOCATION_ID = 1700;
QOS_BEST_EFFORT in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
Events that Generate Notifications
Committed DML Transactions
INSERT, UPDATE, or DELETE)ROWID of each changed row, if the registration was created with the ROWID option and the number of modified rows was not too large. For more information, see "ROWID Option".
Committed DDL Statements
ALTER TABLETRUNCATE TABLEFLASHBACK TABLEDROP TABLE
DROP TABLE statement generates a DROP NOTIFICATION.
SELECT COL1 FROM TEST_TABLE
WHERE COL2 = 1;
TEST_TABLE has this schema:
(COL1 NUMBER, COL2 NUMBER, COL3 NUMBER)
ALTER TABLE DROP COLUMN COL2;
Deregistration
TIMEOUT is specified with a nonzero value when the queries are registered, the database purges the registration after the specified time interval.QOS_DEREG_NFY is specified when the queries are registered, the database purges the registration after it generates its first notification.
Global Events
EVENT_STARTUP and EVENT_SHUTDOWN generate notifications.EVENT_STARTUP when the first instance of the database startsEVENT_SHUTDOWN when the last instance of the database shuts downEVENT_SHUTDOWN_ANY when any instance of the database shuts downDBMS_CQ_NOTIFICATION package.
DBMS_CQ_NOTIFICATION package
Notification Contents
ROWID option was specified, ROWIDs of changed rowsINSERT or UPDATE)
Good Candidates for CQN
Description of "Figure 11-2 Basic Process of Continuous Query Notification (CQN)"
HR.EMPLOYEES):HR.EMPLOYEES table in the back-end database and commits the update, causing the query result to change. The data for HR.EMPLOYEES cached in the middle tier is now outdated.JOBQ background process of a notification message.JOBQ process runs the stored procedure specified by the client application. In this example, JOBQ passes the data to a server-side PL/SQL procedure. The implementation of the PL/SQL notification handler determines how the notification is handled.ROWID of the changed row in HR.EMPLOYEES.
Creating CQN Registrations
PL/SQL CQN Registration Interface
DBMS_CQ_NOTIFICATION package. You use the DBMS_CQ_NOTIFICATION.NEW_REG_START function to open a registration block. You specify the registration details, including the notification type and notification handler, as part of the CQ_NOTIFICATION$_REG_INFO object, which is passed as an argument to the NEW_REG_START procedure. Every query that you run while the registration block is open is registered with CQN. If you specified notification type QRCN, the database assigns a query ID to each query. You can retrieve these query IDs with the DBMS_CQ_NOTIFICATION.CQ_NOTIFICATION_QUERYID function. To close the registration block, you use the DBMS_CQ_NOTIFICATION.REG_END function.
DBMS_CQ_NOTIFICATION package
CQN Registration Options
Option Description
ROWID
ROWID pseudocolumn for each changed row in the notification.
< td align="left" headers="r6c1-t7 r1c2-t7" rowspan="1" colspan="1">
Notification Type Option
QRCN Mode (QRCN Notification Type Only)
QOS_BEST_EFFORT in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
ROWID Option
ROWID option includes the value of the ROWID pseudocolumn (the rowid of the row) for each changed row in the notification. To include the ROWID option of each changed row in the notification, specify QOS_ROWIDS in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
ROWID of the row changes. HCC, a feature of certain Oracle storage systems, is described in Oracle Database Concepts.ROWID information in the notification, the application can retrieve the contents of the changed rows by performing queries of this form:
SELECT * FROM table_name_from_notification
WHERE ROWID = rowid_from_notification;
ROWIDs are published in the external string format. For a regular heap table, the length of a ROWID is 18 character bytes. For an Index Organized Table (IOT), the length of the ROWID depends on the size of the primary key, and might exceed 18 bytes.ROWIDs, the notification might be "rolled up" into a FULL-TABLE-NOTIFICATION, indicated by a special flag in the notification descriptor. Possible reasons for a FULL-TABLE-NOTIFICATION are:ROWIDs exceeds 1% of the dynamic shared pool size.ROWIDs of modified rows for an IOT is too large (the upper limit is approximately 1800 bytes).NTFN_GROUPING_TYPE with the value DBMS_CQ_NOTIFICATION.NTFN_GROUPING_TYPE_SUMMARY, described in "Notification Grouping Options".FULL-TABLE-NOTIFICATION does not include ROWIDs, the application that receives it must assume that the entire table (that is, all rows) might have changed.
Operations Filter Option (OCN Notification Type Only)
OPERATIONS_FILTER attribute of the CQ_NOTIFICATION$_REG_INFO object. With the OPERATIONS_FILTER attribute, specify the type of operation with the constant that represents it, which is defined in the DBMS_CQ_NOTIFICATION package, as follows:
Operation Constant INSERTDBMS_CQ_NOTIFICATION.INSERTOPUPDATEDBMS_CQ_NOTIFICATION.UPDATEOPDELETEDBMS_CQ_NOTIFICATION.DELETEOPALTEROPDBMS_CQ_NOTIFICATION.ALTEROPDROPOPDBMS_CQ_NOTIFICATION.DROPOPUNKNOWNOPDBMS_CQ_NOTIFICATION.UNKNOWNOPAll (default) DBMS_CQ_NOTIFICATION.ALL_OPERATIONSOR. For example:
DBMS_CQ_NOTIFICATION.INSERTOP + DBMS_CQ_NOTIFICATION.DELETEOP
OPERATIONS_FILTER has no effect if you also specify QOS_QUERY in the QOSFLAGS attribute, because QOS_QUERY specifies notification type QRCN.
DBMS_CQ_NOTIFICATION package
Transaction Lag Option (OCN Notification Type Only)
TRANSACTION_LAG, then notifications do not include ROWIDs, even if you also specified QOS_ROWIDS.
Notification Grouping Options
CQ_NOTIFICATION$_REG_INFO object, are:
Attribute Description NTFN_GROUPING_CLASSSpecifies the class by which to group notifications. The only allowed values are DBMS_CQ_NOTIFICATION.NTFN_GROUPING_CLASS_TIME, which groups notifications by time, and zero, which is the default (notifications are generated immediately after the event that causes them).NTFN_GROUPING_VALUESpecifies the time interval that defines the group, in seconds. For example, if this value is 900, notifications generated in the same 15-minute interval are grouped. NTFN_GROUPING_TYPESpecifies the type of grouping, which is either of:
DBMS_CQ_NOTIFICATION.NTFN_GROUPING_TYPE_SUMMARY: All notifications in the group are summarized into a single notification.ROWIDs, even if you specified the ROWID option.DBMS_CQ_NOTIFICATION.NTFN_GROUPING_TYPE_LAST: Only the last notification in the group is published and the earlier ones discarded.NTFN_GROUPING_START_TIMESpecifies when to start generating notifications. If specified as NULL, it defaults to the current system-generated time.NTFN_GROUPING_REPEAT_COUNTSpecifies how many times to repeat the notification. Set to DBMS_CQ_NOTIFICATION.NTFN_GROUPING_FOREVER to receive notifications for the life of the registration. To receive at most n notifications during the life of the registration, set to n.
Reliable Option
QOS_RELIABLE in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.
Purge-on-Notify and Timeout Options
QOS_DEREG_NFY in the QOSFLAGS attribute of the CQ_NOTIFICATION$_REG_INFO object.TIMEOUT attribute of the CQ_NOTIFICATION$_REG_INFO object.
Prerequisites for Creating CQN Registrations
EXECUTE privilege on the DBMS_CQ_NOTIFICATION package, whose subprograms you use to create a registrationCHANGE NOTIFICATION system privilegeSELECT privileges on all objects to be registereddml_locks init.ora parameter must have a nonzero value (as its default value does).
COMPATIBLE setting of the database must be at least 11.0.0.
Queries that Can Be Registered for Object Change Notification (OCN)
REF cursors.
Queries that Can Be Registered for Query Result Change Notification (QRCN)
Queries that Can Be Registered for QRCN in Guaranteed Mode
NUMBER data type or a VARCHAR2 data type.+ (addition)- (subtraction, not unary minus)* (multiplication)/ (division)< (less than)<= (less than or equal to)= (equal to)>= (greater than or equal to)> (greater than)<> or != (not equal to)IS NULLIS NOT NULLAND, OR, and NOT.SUM, COUNT, AVERAGE, MIN, and MAX).
SELECT SALARY FROM EMPLOYEES, DEPARTMENTS
WHERE EMPLOYEES.DEPARTMENT_ID = DEPARTMENTS.DEPARTMENT_ID
AND DEPARTMENTS.LOCATION_ID = 1700;
OR-expansion). For information about the query optimizer, see Oracle Database Performance Tuning Guide.
Queries that Can Be Registered for QRCN Only in Best-Effort Mode
SELECT listSUBSTR, LTRIM, and RTRIM)TRUNC, ABS, and SQRT)LIKE and REGEXP_LIKEEXISTS or NOT EXISTS condition
SELECT EMPLOYEE_ID, DEPARTMENT_ID
FROM EMPLOYEES, DEPARTMENTS
WHERE EMPLOYEES.EMPLOYEE_ID = 10
OR DEPARTMENTS.DEPARTMENT_ID = 'IT';
SELECT DEPARTMENT_ID
FROM DEPARTMENTS
WHERE ROWID = 'AAANkdAABAAALinAAF';
UNION ALL or CONCATENATIONOR-expansion execution plan chosen by the query optimizer.)ORDER BY or GROUP BYSORT operation with an ORDER BY option in the execution plan chosen by the query optimizer.)
Queries that Cannot Be Registered for QRCN in Either Mode
DUAL (in the SELECT list)COUNT
SELECT SALARY FROM EMPLOYEES
WHERE USER = SYS_CONTEXT('USERENV', 'SESSION_USER');
SYSDATE, SYSTIMESTAMP, or CURRENT TIMESTAMP
Using PL/SQL to Register Queries for CQN
CQ_NOTIFICATION$_REG_INFO object that specifies the name of the notification handler, the notification type, and other attributes of the registration.DBMS_CQ_NOTIFICATION.NEW_REG_START function to open a registration block.DBMS_CQ_NOTIFICATION.REG_END function.
CQ_NOTIFICATION$_REG_INFO object and the functions NEW_REG_START and REG_END, all of which are defined in the DBMS_CQ_NOTIFICATION package
Creating a PL/SQL Notification Handler
PROCEDURE schema_name.proc_name(ntfnds IN CQ_NOTIFICATION$_DESCRIPTOR)
schema_name is the name of the database schema, proc_name is the name of the stored procedure, and ntfnds is the notification descriptor.CQ_NOTIFICATION$_DESCRIPTOR object, whose attributes describe the details of the change (transaction ID, type of change, queries affected, tables modified, and so on).JOBQ process passes the notification descriptor, ntfnds, to the notification handler, proc_name, which handles the notification according to its application requirements. (This is step 6 in Figure 11-2.)
JOB_QUEUE_PROCESSES initialization parameter specifies the maximum number of processes that can be created for the execution of jobs. You must set JOB_QUEUE_PROCESSES to a nonzero value to receive PL/SQL notifications.
Creating a CQ_NOTIFICATION$_REG_INFO Object
CQ_NOTIFICATION$_REG_INFO specifies the notification handler that the database runs when a registered objects changes. In SQL*Plus, you can view its type attributes by running this statement:
DESC CQ_NOTIFICATION$_REG_INFO
SYS.CQ_NOTIFICATION$_REG_INFO.
Attribute Description
CALLBACK
schema_name.procedure_name, for example, hr.dcn_callback.
QOSFLAGS
DBMS_CQ_NOTIFICATION package. For their names and descriptions, see Table 11-3.OR. For example: DBMS_CQ_NOTIFICATION.QOS_RELIABLE + DBMS_CQ_NOTIFICATION.QOS_ROWIDS
TIMEOUT
0 or NULL, then the registration persists until the client explicitly deregisters it.QOSFLAGS attribute with its QOS_DEREG_NFY flag.
OPERATIONS_FILTER
QOS_FLAGS attribute with its QOS_QUERY flag.DBMS_CQ_NOTIFICATION package:ALL_OPERATIONS notifies on all changesINSERTOP notifies on insertsUPDATEOP notifies on updatesDELETEOP notifies on deletesALTEROP notifies on ALTER TABLE operationsDROPOP notifies on DROP TABLE operationsUNKNOWNOP notifies on unknown operationsOR. For example: DBMS_CQ_NOTIFICATION.INSERTOP + DBMS_CQ_NOTIFICATION.DELETEOP.
TRANSACTION_LAG
NTFN_GROUPING_* attributes.QOS_FLAGS attribute with its QOS_QUERY flag.TRANSACTION_LAG, then the ROWID level granularity is not available in the notification messages even if you specified QOS_ROWIDS during registration.
NTFN_GROUPING_CLASS
DBMS_CQ_NOTIFICATION.NTFN_GROUPING_CLASS_TIME, which groups notifications by time.
NTFN_GROUPING_VALUE
NTFN_GROUPING_TYPE
DBMS_CQ_NOTIFICATION.NTFN_GROUPING_TYPE_SUMMARY: All notifications in the group are summarized into a single notification.DBMS_CQ_NOTIFICATION.NTFN_GROUPING_TYPE_LAST: Only the last notification in the group is published and the earlier ones discarded.
NTFN_GROUPING_START_TIME
NULL, it defaults to the current system-generated time.
NTFN_GROUPING_REPEAT_COUNT
DBMS_CQ_NOTIFICATION.NTFN_GROUPING_FOREVER to receive notifications for the life of the registration. To receive at most n notifications during the life of the registration, set to n.DBMS_CQ_NOTIFICATION package. You can specify them with the QOS_FLAGS attribute of CQ_NOTIFICATION$_REG_INFO (see Table 11-2).
Flag Description
QOS_DEREG_NFY
QOS_RELIABLE
QOS_ROWIDS
ROWID of each changed row in the notification.
QOS_QUERY
QOS_BEST_EFFORT.
QOS_BEST_EFFORT
QOS_QUERY. Registers simplified versions of queries that are too complex for query result change evaluation; in other words, registers queries for QRCN in best-effort mode, described in "Best-Effort Mode".DBA_CQ_NOTIFICATION_QUERIES or USER_CQ_NOTIFICATION_QUERIES. These views give the QUERYID and the text of each registered query.HR.dcn_callback whenever a registered object changes. In Example 11-4, you create a CQ_NOTIFICATION$_REG_INFO object that specifies that HR.dcn_callback receives notifications. To create the object you must have EXECUTE privileges on the DBMS_CQ_NOTIFICATION package.
DECLARE
v_cn_addr CQ_NOTIFICATION$_REG_INFO;
BEGIN
-- Create object:
v_cn_addr := CQ_NOTIFICATION$_REG_INFO (
'HR.dcn_callback', -- PL/SQL notification handler
DBMS_CQ_NOTIFICATION.QOS_QUERY -- notification type QRCN
+ DBMS_CQ_NOTIFICATION.QOS_ROWIDS, -- include rowids of changed objects
0, -- registration persists until unregistered
0, -- notify on all operations
0 -- notify immediately
);
-- Register queries: ...
END;
/
Identifying Individual Queries in a Notification
DBMS_CQ_NOTIFICATION.CQ_NOTIFICATION_QUERYID function in the SELECT list of that query. For example:
SELECT EMPLOYEE_ID, SALARY, DBMS_CQ_NOTIFICATION.CQ_NOTIFICATION_QUERYID
FROM EMPLOYEES
WHERE DEPARTMENT_ID = 10;
EMPLOYEE_ID SALARY CQ_NOTIFICATION_QUERYID
----------- ---------- -----------------------
200 2800 0
1 row selected.
Adding Queries to an Existing Registration
*_CHANGE_NOTIFICATION_REGS.DBMS_CQ_NOTIFICATION.ENABLE_REG with the registration ID as the parameter.DBMS_CQ_NOTIFICATION.REG_END function.
DECLARE
v_cursor SYS_REFCURSOR;
BEGIN
-- Open existing registration
DBMS_CQ_NOTIFICATION.ENABLE_REG(21);
OPEN v_cursor FOR
-- Run query to be registered
SELECT DEPARTMENT_ID
FROM HR.DEPARTMENTS; -- register this query
CLOSE v_cursor;
-- Close registration
DBMS_CQ_NOTIFICATION.REG_END;
END;
/
Best Practices for CQN Registrations
Troubleshooting CQN Registrations
JOB_QUEUE_PROCESSES parameter is not set to a nonzero value.*_CHANGE_NOTIFICATION_REGS. For example, this statement displays all registrations and registered objects for the current user:
SELECT REGID, TABLE_NAME FROM USER_CHANGE_NOTIFICATION_REGS;
JOBQ process that tried to run the procedure. The name of the trace file usually has this form:
ORACLE_SID_jnumber_PID.trc
dbs1 and the process ID (PID) of the JOBQ process is 12483, the name of the trace file is usually dbs1_j000_12483.trc.'chnf_callback' as the notification handler and registration ID 100. Suppose that 'chnf_callback' was not defined in the database. Then the JOBQ trace file might contain a message of the form:
****************************************************************************
Run-time error during execution of PL/SQL cbk chnf_callback for reg CHNF100.
Error in PLSQL notification of msgid:
Queue :
Consumer Name :
PLSQL function :chnf_callback
Exception Occured, Error msg:
ORA-00604: error occurred at recursive SQL level 2
ORA-06550: line 1, column 7:
PLS-00201: identifier 'CHNF_CALLBACK' must be declared
ORA-06550: line 1, column 7:
PL/SQL: Statement ignored
****************************************************************************
REM Create table in HR schema to hold count of notifications received.
CREATE TABLE nfcount(cnt NUMBER);
INSERT INTO nfcount (cnt) VALUES(0);
COMMIT;
CREATE OR REPLACE PROCEDURE chnf_callback
(ntfnds IN CQ_NOTIFICATION$_DESCRIPTOR)
IS
BEGIN
UPDATE nfcount SET cnt = cnt+1;
COMMIT;
END;
/
Querying CQN Registrations
*_CHANGE_NOTIFICATION_REGS.HR, use this query:
SELECT regid, table_name FROM USER_CHANGE_NOTIFICATION_REGS;
USER_CQ_NOTIFICATION_QUERIES or DBA_CQ_NOTIFICATION_QUERIES. These views include information about any bind values that the queries use. In these views, bind values in the original query are included in the query text as constants. The query text is equivalent, but maybe not identical, to the original query that was registered.
USER_CHANGE_NOTIFICATION_REGS and DBA_CQ_NOTIFICATION_QUERIES
Interpreting Notifications
Interpreting a CQ_NOTIFICATION$_DESCRIPTOR Object
CQ_NOTIFICATION$_DESCRIPTOR object to the notification handler. The notification handler can find the details of the database change in the attributes of the CQ_NOTIFICATION$_DESCRIPTOR object.SYS and running this statement:
DESC CQ_NOTIFICATION$_DESCRIPTOR
CQ_NOTIFICATION$_DESCRIPTOR.
Attribute Description
REGISTRATION_ID
TRANSACTION_ID
DBNAME
EVENT_TYPE
EVENT_NONEEVENT_STARTUP (Instance startup)EVENT_SHUTDOWN (Instance shutdown - last instance shutdown for Oracle RAC)EVENT_SHUTDOWN_ANY (Any instance shutdown for Oracle RAC)EVENT_DEREG (Registration was removed)EVENT_OBJCHANGE (Change to a registered table)EVENT_QUERYCHANGE (Change to a registered result set)
NUMTABLES
TABLE_DESC_ARRAY
NULL.EVENT_TYPE is EVENT_OBJCHANGE]: a VARRAY of table change descriptors of type CQ_NOTIFICATION$_TABLE, each of which corresponds to a changed table. For attributes of CQ_NOTIFICATION$_TABLE, see Table 11-5.NULL.
QUERY_DESC_ARRAY
NULL.EVENT_TYPE is EVENT_QUERYCHANGE]: a VARRAY of result set change descriptors of type CQ_NOTIFICATION$_QUERY, each of which corresponds to a changed result set. For attributes of CQ_NOTIFICATION$_QUERY, see Table 11-6.NULL.
Interpreting a CQ_NOTIFICATION$_TABLE Object
CQ_NOTIFICATION$_DESCRIPTOR type contains an attribute called TABLE_DESC_ARRAY, which holds a VARRAY of table descriptors of type CQ_NOTIFICATION$_TABLE.SYS and running this statement:
DESC CQ_NOTIFICATION$_TABLE
CQ_NOTIFICATION$_TABLE.
Attribute Specifies . . .
OPFLAGS
ALL_ROWS signifies that either the entire table is modified, as in a DELETE *, or row-level granularity of information is not requested or not available in the notification, and the recipient must assume that the entire table has changedUPDATEOP signifies an updateDELETEOP signifies a deletionALTEROP signifies an ALTER TABLEDROPOP signifies a DROP TABLEUNKNOWNOP signifies an unknown operation
TABLE_NAME
NUMROWS
ROW_DESC_ARRAY
VARRAY of row descriptors of type CQ_NOTIFICATION$_ROW, which Table 11-7 describes. If ALL_ROWS was set in the opflags, then the ROW_DESC_ARRAY member is NULL.
Interpreting a CQ_NOTIFICATION$_QUERY Object
CQ_NOTIFICATION$_DESCRIPTOR type contains an attribute called QUERY_DESC_ARRAY, which holds a VARRAY of result set change descriptors of type CQ_NOTIFICATION$_QUERY.SYS and running this statement:
DESC CQ_NOTIFICATION$_QUERY
CQ_NOTIFICATION$_QUERY.
Attribute Specifies . . .
QUERYID
QUERYOP
EVENT_QUERYCHANGE or EVENT_DEREG).
TABLE_DESC_ARRAY
VARRAY of table change descriptors of type CQ_NOTIFICATION$_TABLE, each of which corresponds to a changed table that caused a change in the result set. For attributes of CQ_NOTIFICATION$_TABLE, see Table 11-5.
Interpreting a CQ_NOTIFICATION$_ROW Object
ROWID option was specified during registration, the CQ_NOTIFICATION$_TABLE type has a ROW_DESC_ARRAY attribute, a VARRAY of type CQ_NOTIFICATION$_ROW that contains the ROWIDs for the changed rows. If ALL_ROWS was set in the OPFLAGS field of the CQ_NOTIFICATION$_TABLE object, then ROWID information is not available.CQ_NOTIFICATION$_ROW.
Attribute Specifies . . .
OPFLAGS
OPFLAGS in Table 11-5.
ROW_ID
ROWID of the changed row.
Deleting Registrations
DBMS_CQ_NOTIFICATION.DEREGISTER with the registration ID as the parameter. For example, this statement deregisters the registration whose registration ID is 21:
DBMS_CQ_NOTIFICATION.DEREGISTER(21);
Configuring CQN: Scenario
HR.EMPLOYEES and HR.DEPARTMENTS tables in the back-end database. Because these tables change relatively infrequently, the application can improve performance by caching the query results. Caching avoids a round trip to the back-end database and server-side execution latency.DBMS_CQ_NOTIFICATION package to register queries based on HR.EMPLOYEES and HR.DEPARTMENTS tables. To configure CQN, you follow these steps:HR.EMPLOYEES and HR.DEPARTMENTS tables for QRCN, as instructed in "Registering the Queries".
Creating a PL/SQL Notification Handler
AS SYSDBA.HR:
GRANT EXECUTE ON DBMS_CQ_NOTIFICATION TO HR;
GRANT CHANGE NOTIFICATION TO HR;
JOB_QUEUE_PROCESSES parameter to receive notifications:
ALTER SYSTEM SET "JOB_QUEUE_PROCESSES"=4;
HR).
-- Create table to record notification events.
DROP TABLE nfevents;
CREATE TABLE nfevents (
regid NUMBER,
event_type NUMBER
);
-- Create table to record notification queries:
DROP TABLE nfqueries;
CREATE TABLE nfqueries (
qid NUMBER,
qop NUMBER
);
-- Create table to record changes to registered tables:
DROP TABLE nftablechanges;
CREATE TABLE nftablechanges (
qid NUMBER,
table_name VARCHAR2(100),
table_operation NUMBER
);
-- Create table to record ROWIDs of changed rows:
DROP TABLE nfrowchanges;
CREATE TABLE nfrowchanges (
qid NUMBER,
table_name VARCHAR2(100),
row_id VARCHAR2(2000)
);
HR.chnf_callback, as shown in Example 11-6.
CREATE OR REPLACE PROCEDURE chnf_callback (
ntfnds IN CQ_NOTIFICATION$_DESCRIPTOR
)
IS
regid NUMBER;
tbname VARCHAR2(60);
event_type NUMBER;
numtables NUMBER;
operation_type NUMBER;
numrows NUMBER;
row_id VARCHAR2(2000);
numqueries NUMBER;
qid NUMBER;
qop NUMBER;
BEGIN
regid := ntfnds.registration_id;
event_type := ntfnds.event_type;
INSERT INTO nfevents (regid, event_type)
VALUES (chnf_callback.regid, chnf_callback.event_type);
numqueries :=0;
IF (event_type = DBMS_CQ_NOTIFICATION.EVENT_QUERYCHANGE) THEN
numqueries := ntfnds.query_desc_array.count;
FOR i IN 1..numqueries LOOP -- loop over queries
qid := ntfnds.query_desc_array(i).queryid;
qop := ntfnds.query_desc_array(i).queryop;
INSERT INTO nfqueries (qid, qop)
VALUES(chnf_callback.qid, chnf_callback.qop);
numtables := 0;
numtables := ntfnds.query_desc_array(i).table_desc_array.count;
FOR j IN 1..numtables LOOP -- loop over tables
tbname :=
ntfnds.query_desc_array(i).table_desc_array(j).table_name;
operation_type :=
ntfnds.query_desc_array(i).table_desc_array(j).Opflags;
INSERT INTO nftablechanges (qid, table_name, table_operation)
VALUES (
chnf_callback.qid,
tbname,
operation_type
);
IF (bitand(operation_type, DBMS_CQ_NOTIFICATION.ALL_ROWS) = 0) THEN
numrows := ntfnds.query_desc_array(i).table_desc_array(j).numrows;
ELSE
numrows :=0; -- ROWID info not available
END IF;
-- Body of loop does not run when numrows is zero.
FOR k IN 1..numrows LOOP -- loop over rows
Row_id :=
ntfnds.query_desc_array(i).table_desc_array(j).row_desc_array(k).row_id;
INSERT INTO nfrowchanges (qid, table_name, row_id)
VALUES (chnf_callback.qid, tbname, chnf_callback.Row_id);
END LOOP; -- loop over rows
END LOOP; -- loop over tables
END LOOP; -- loop over queries
END IF;
COMMIT;
END;
/
Registering the Queries
HR.chnf_callback as the notification handler, as in Example 11-7.
DECLARE
reginfo CQ_NOTIFICATION$_REG_INFO;
mgr_id NUMBER;
dept_id NUMBER;
v_cursor SYS_REFCURSOR;
regid NUMBER;
BEGIN
/* Register two queries for QRNC: */
/* 1. Construct registration information.
chnf_callback is name of notification handler.
QOS_QUERY specifies result-set-change notifications. */
reginfo := cq_notification$_reg_info (
'chnf_callback',
DBMS_CQ_NOTIFICATION.QOS_QUERY,
0, 0, 0
);
/* 2. Create registration. */
regid := DBMS_CQ_NOTIFICATION.new_reg_start(reginfo);
OPEN v_cursor FOR
SELECT dbms_cq_notification.CQ_NOTIFICATION_QUERYID, manager_id
FROM HR.EMPLOYEES
WHERE employee_id = 7902;
CLOSE v_cursor;
OPEN v_cursor FOR
SELECT dbms_cq_notification.CQ_NOTIFICATION_QUERYID, department_id
FROM HR.departments
WHERE department_name = 'IT';
CLOSE v_cursor;
DBMS_CQ_NOTIFICATION.reg_end;
END;
/
SELECT queryid, regid, TO_CHAR(querytext)
FROM user_cq_notification_queries;
QUERYID REGID TO_CHAR(QUERYTEXT)
------- ----- ------------------------------------------------
22 41 SELECT HR.DEPARTMENTS.DEPARTMENT_ID
FROM HR.DEPARTMENTS
WHERE HR.DEPARTMENTS.DEPARTMENT_NAME = 'IT'
21 41 SELECT HR.EMPLOYEES.MANAGER_ID
FROM HR.EMPLOYEES
WHERE HR.EMPLOYEES.EMPLOYEE_ID = 7902
QUERYID 22:
UPDATE DEPARTMENTS
SET DEPARTMENT_NAME = 'FINANCE'
WHERE department_name = 'IT';
chnf_callback (which you created in Example 11-6) runs.
SELECT * FROM nfevents;
REGID EVENT_TYPE
----- ----------
61 7
EVENT_TYPE 7 corresponds to EVENT_QUERYCHANGE (query result change).
SELECT * FROM nftablechanges;
REGID TABLE_NAME TABLE_OPERATION
----- -------------- ---------------
42 HR.DEPARTMENTS 4
TABLE_OPERATION 4 corresponds to UPDATEOP (update operation).ROWIDs of changed rows are recorded:
SELECT * FROM nfrowchanges;
REGID TABLE_NAME ROWID
----- -------------- ------------------
61 HR.DEPARTMENTS AAANkdAABAAALinAAF
PKTYG PK |%A
OEBPS/lof.htm
2 Using SQL Data Types in Database Applications
*_OBJECTS, the OBJECT_TYPE of an ADE is TYPE. In the static data dictionary view *_TYPES, the TYPECODE of an ADE is OBJECT.
Overview of SQL Data Types
NUMBER data type, but cannot add values of RAW data type.
Representing Character Data
Data Types Values Stored
DBMS_LOB.GETCHUNKSIZE)
DBMS_LOB.GETCHUNKSIZE)
CHAR, VARCHAR2, and LONG data from the database character set (determined by the NLS_LANGUAGE parameter) to the character set defined for the user session.
CHAR, VARCHAR2, NCHAR, and NVARCHAR2 data typesCLOB and NCLOB data typesLONG data type
Specifying Column Lengths as Bytes or Characters
CHAR and VARCHAR2 columns as either bytes or characters. The lengths of NCHAR and NVARCHAR2 columns are always specified in characters, making them ideal for storing Unicode character literals, where a character might consist of multiple bytes. This table shows some column length specifications and their meanings:
Column Length Specification Meaning id VARCHAR2(32 BYTE)The id column contains up to 32 single-byte characters.name VARCHAR2(32 CHAR)The name column contains up to 32 characters of the database character set. If the database character set includes multibyte characters, then the 32 characters can occupy more than 32 bytes.biography NVARCHAR2(2000)The biography column contains up to 2000 characters of any Unicode-representable language. The encoding depends on the national character set. The column can contain multibyte values even if the database character set is single-byte.comment VARCHAR2(2000)The comment column contains up to 2000 bytes or characters, depending on the value of the initialization parameter NLS_LENGTH_SEMANTICS.NCHAR or NVARCHAR2 if it might use a Unicode encoding that is different from the database character set.
NCHAR and NVARCHAR2NCHAR and NVARCHAR2
Choosing Between CHAR and VARCHAR2 Data Types
CHAR columns but not values stored in VARCHAR2 columns. Therefore, VARCHAR2 columns use space more efficiently than CHAR columns.VARCHAR2 columns might read fewer data blocks than a full table scan on a table containing the same data stored in CHAR columns. If your application often performs full table scans on large tables containing character data, then you might be able to improve performance by storing data in VARCHAR2 columns rather than in CHAR columns.CHAR data type. When trailing blanks are important in string comparisons, use the VARCHAR2 data type.
CHAR and VARCHAR2 data types are fully supported. Today, the VARCHAR data type automatically corresponds to the VARCHAR2 data type and is reserved for future use.
Representing Numeric Data
NUMBER, BINARY_FLOAT, and BINARY_DOUBLE.NUMBER data type stores real numbers in either a fixed-point or floating-point format. NUMBER offers up to 38 decimal digits of precision. In a NUMBER column, you can store positive and negative numbers of magnitude 1 x 10-130 through 9.99 x10125, and 0. All Oracle Database platforms support NUMBER values.BINARY_FLOAT and BINARY_DOUBLE data types store floating-point numbers in the single-precision (32-bit) IEEE 754 format and the double-precision (64-bit) IEEE 754 format, respectively. High-precision values use less space when stored as BINARY_FLOAT and BINARY_DOUBLE than when stored as NUMBER. Arithmetic operations on floating-point numbers are usually faster for BINARY_FLOAT and BINARY_DOUBLE values than for NUMBER values.BINARY_FLOAT and BINARY_DOUBLE values are performed by the native instruction set that the hardware vendor supplies. The term native floating-point data type includes BINARY_FLOAT and BINARY_DOUBLE data types and all implementations of these types in supported client interfaces.
NUMBER data typeBINARY_FLOAT and BINARY_DOUBLE data types
Floating-Point Number Components
(-1)sign.significand.baseexponent
(-1)0.431.10-2
Component Name Component Value Sign 0 Significand 431 Base 10 Exponent -2
Floating-Point Number Formats
NUMBER values are stored in decimal format. For calculations that need decimal rounding, use the NUMBER data type.
Binary Floating-Point Formats
(-1)sign 2E (bit0 bit1 bit2 ... bitp-1)
Component Component Value
sign
E (exponent)
biti
p (precision)
Data Type Sign Bit Exponent Bits Significand Bits Total Bits
NUMBER. Range limits are expressed as positive numbers, but they also apply to absolute values of negative numbers. (The notation "number e exponent" means number * 10exponent.)
Special Values for Native Floating-Point Formats
NaN. NaN, the result of any undefined operation, is represented by many bit patterns. Some of these bits patterns have the sign bit set and some do not, but the sign bit has no meaning.NaNs (which do not raise additional exceptions as they propagate through most operations) and signaling NaNs (which do). The IEEE 754 standard specifies action for when exceptions are enabled and action for when they are disabled.NaNs. You can use Oracle Call Interface (OCI) to retrieve NaN values from Oracle Database, but whether a retrieved NaN value is signaling or quiet depends on the client platform and is beyond the control of Oracle Database.NaNNaN. NaN is unordered with other classes of special values and with itself.NaNs are quiet.NaN value < NaNNaN == any other NaNNaNs are converted to the same bit pattern.
NaN).
Comparison Operators for Native Floating-Point Data Types
-0 equals +0).
Arithmetic Operations with Native Floating-Point Data Types
NaN, all platforms produce a value for which IS NAN is true. However, all platforms do not have to use the same bit pattern.
Conversion Functions for Floating-Point Data Types
TO_BINARY_DOUBLE, described in Oracle Database SQL Language ReferenceTO_BINARY_FLOAT, described in Oracle Database SQL Language ReferenceTO_CHAR, described in Oracle Database SQL Language ReferenceTO_NUMBER, described in Oracle Database SQL Language Reference
Client Interfaces for Native Floating-Point Data Types
OCI Native Floating-Point Data Types SQLT_BFLOAT and SQLT_BDOUBLE
SQLT_BFLOAT and SQLT_BDOUBLE, respectively. Conversions between these types and the SQL types BINARY_FLOAT and BINARY_DOUBLE are exact on platforms that implement the IEEE 754 standard for the C data types FLOAT and DOUBLE.
Native Floating-Point Data Types Supported in ADTs
BINARY_FLOAT and BINARY_DOUBLE as attributes of ADTs.
Pro*C/C++ Support for Native Floating-Point Data Types
FLOAT and DOUBLE data types using the column data types BINARY_FLOAT and BINARY_DOUBLE. You can use these data types in the same way that Oracle Database NUMBER data type is used. You can bind FLOAT and DOUBLE to BINARY_FLOAT and BINARY_DOUBLE, respectively, by setting the Pro*C/C++ precompiler command line option NATIVE_TYPES to Y (yes) when you compile your application.
Representing Date and Time Data
Date Type Usage
Displaying Current Date and Time
SELECT SYSDATE FROM DUAL
NLS_DATE_FORMAT.DD-MON-RR. The RR datetime format element lets you store 20th century dates in the 21st century by specifying only the last two digits of the year. For example, in the datetime format DD-MON-YY, 13-NOV-54 refers to the year 1954 in a query issued between 1950 and 2049, but to the year 2054 in a query issued between 2050 and 2099.SYSDATE in a nondefault format, use the TO_CHAR function with a datetime format model.TO_CHAR with a format model to display SYSDATE in a nondefault format, which includes the qualifier BC or AD. (By default, SYSDATE is displayed without this qualifier.)
SELECT TO_CHAR(SYSDATE, 'DD-MON-YYYY BC') NOW FROM DUAL;
NOW
-----------------------
18-MAR-2009 AD
1 row selected.
SYSDATE, it can be helpful to set SYSDATE to a constant. Do this with the initialization parameter FIXED_DATE, described in Oracle Database Reference.
SYSDATENLS_DATE_FORMATTO_CHARRR datetime format element
Displaying and Inserting Dates in Nondefault Formats
NLS_DATE_FORMAT), you can display and insert dates in nondefault formats by using the TO_CHAR and TO_DATE functions, respectively, with datetime format models.DATE column and inserts into it a date specified in a nondefault format. The date is stored in the default format, as the first SELECT statement shows. The second SELECT statement displays the date in a nondefault format.
DROP TABLE dates;
CREATE TABLE dates (d DATE);
INSERT INTO dates VALUES (TO_DATE('OCT 27, 1998', 'MON DD, YYYY'));
SELECT d FROM dates;
D
---------
27-OCT-98
1 row selected.
SELECT TO_CHAR(d, 'YYYY-MON-DD') D FROM dates;
D
--------------------
1998-OCT-27
1 row selected.
NLS_DATE_FORMATTO_CHARTO_DATERR datetime format element
Displaying and Inserting Times in Nondefault Formats
HH24:MI:SS, you can display and insert times in nondefault formats by using the TO_CHAR and TO_DATE functions, respectively, with datetime format models.DATE column:DATE column and inserts into it three dates specified in nondefault formats—one with both date and time portions, one with no time portion, and one with no date portion. The first SELECT statement shows the current date. The second SELECT statement displays the three dates in a nondefault format that includes both date and time portions.
DROP TABLE birthdays;
CREATE TABLE birthdays (name VARCHAR2(20), day DATE);
INSERT INTO birthdays (name, day)
VALUES ('Annie',
TO_DATE('13-NOV-92 10:56 A.M.','DD-MON-RR HH:MI A.M.')
);
INSERT INTO birthdays (name, day)
VALUES ('Bobby',
TO_DATE('5-APR-02','DD-MON-RR')
);
INSERT INTO birthdays (name, day)
VALUES ('Cindy',
TO_DATE('8:25 P.M.','HH:MI A.M.')
);
SELECT SYSDATE FROM DUAL;
SYSDATE
---------
05-NOV-10
1 row selected.
SELECT name,
TO_CHAR(day, 'Mon DD, RRRR') DAY,
TO_CHAR(day, 'HH:MI A.M.') TIME
FROM birthdays;
NAME DAY TIME
-------------------- --------------------- ----------
Annie Nov 13, 1992 10:56 A.M.
Bobby Apr 05, 2002 12:00 A.M.
Cindy Nov 01, 2010 08:25 P.M.
3 rows selected.
Arithmetic Operations with Datetime Data Types
ADD_MONTHS returns the date that is a specified number of months from a specified date. For the complete list of datetime functions, see Oracle Database SQL Language Reference.
Conversion Functions for Datetime Data Types
Function Converts ... To ...
NUMBER
INTERVAL DAY TO SECOND
NUMBER
INTERVAL DAY TO MONTH
DATETIMESTAMPTIMESTAMP WITH TIME ZONETIMESTAMP WITH LOCAL TIME ZONEINTERVAL DAY TO SECONDINTERVAL YEAR TO MONTH
VARCHAR2
CHARVARCHAR2NCHARNVARCHAR2
DATE
CHARVARCHAR2NCHARNVARCHAR2
INTERVAL DAY TO SECOND
CHARVARCHAR2NCHARNVARCHAR2
TIMESTAMP
CHARVARCHAR2NCHARNVARCHAR2
TIMESTAMP WITH TIME ZONE
CHARVARCHAR2NCHARNVARCHAR2
INTERVAL DAY TO MONTH
Importing, Exporting, and Comparing Datetime Types
TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE values without worrying about time zone offsets, because the database stores these values in normalized format.DATE and TIMESTAMP values, you must adjust them to account for any time zone differences between source and target databases, because the database does not store their time zones.
Representing Specialized Data
Representing Geographic Data
MDSYS.SDO_GEOMETRY. You can store the data in the database by using either an object-relational or a relational model. You can use a set of PL/SQL packages to query and manipulate the data.
Representing Multimedia Data
BLOB or BFILE values, or store it externally on a web server or other kind of server, you can use Oracle Multimedia to access the data using either an object-relational or a relational model, and manipulate and query the data using a set of ADTs.ORDAudio, ORDDoc, ORDImage, ORDImageSignature, ORDVideo, and SI_StillImage ADTs (including methods) for these purposes:
Representing Large Amounts of Data
Large Objects (LOBs)
BLOB, CLOB, or NCLOB can be either temporary (declared in the scope of your application) or persistent (created and stored in the database).
LONG and LONG RAW Data Types
LONG columns store variable-length character strings containing up to 2 gigabytes - 1 bytes. LONG columns have many of the characteristics of VARCHAR2 columns. You can use LONG columns to store long text strings. The length of LONG values may be limited by the memory available on your computer. For more information about the LONG data type, including its many restrictions, see Oracle Database SQL Language Reference.LONG RAW (and RAW) data types store data that is not to be explicitly converted by Oracle Database when moving data between different systems. These data types are intended for binary data or byte strings. For example, you can use LONG RAW to store graphics, sound, documents, or arrays of binary data, for which the interpretation is dependent on the use. You can index RAW data, but not LONG RAW data. For more information about the RAW and LONG RAW data types, see Oracle Database SQL Language Reference.
Representing Searchable Text
Representing XML Data
XMLType.XMLType column in a table, you can store the XML data in any of these ways:CLOB columnCLOB)XMLType has member functions that access, extract, and query the XML data using W3C XPath expressions (see Oracle XML DB Developer's Guide). Also, Oracle provides SQL XML functions that manipulate or return whole or partial XML documents (see Oracle Database SQL Language Reference) and these PL/SQL packages (described in Oracle Database PL/SQL Packages and Types Reference):DBMS_XMLDOM, for accessing XMLType objectsDBMS_XMLGEN, for converting the results of a SQL query to a canonical XML formatDBMS_XMLINDEX, for implementing asynchronous indexingDBMS_XMLPARSER, for accessing the contents and structure of XML documentsDBMS_XMLQUERY, for database-to-XMLType functionalityDBMS_XMLSAVE, for XML-to-database-type functionalityDBMS_XMLSCHEMA, for managing XML schemasDBMS_XMLSTORE, for storing XML data in relational tablesDBMS_XMLTRANSLATIONS, for translating strings so that they can be searched or displayed in various languages
Representing Dynamically Typed Data
union keyword and the void * pointer, and Java has the typeof operator and wrapper types such as Number.SYS.ANYDATA to represent values of any scalar type or ADT. SYS.ANYDATA has methods that accept scalar values of any type, and turn them back into scalars or objects. Similarly, you can use the Oracle-supplied ADT SYS.ANYDATASET to represent values of any collection type. For more information about these ADTs, see Oracle Database Object-Relational Developer's Guide.DBMS_TYPES package, as in Example 2-4. For more information about this package, see Oracle Database PL/SQL Packages and Types Reference.OCIAnyData and OCIAnyDataSet interfaces, described in Oracle Call Interface Programmer's Guide.
CREATE OR REPLACE TYPE employee_type AS
OBJECT (empno NUMBER, ename VARCHAR2(10));
/
DROP TABLE mytab;
CREATE TABLE mytab (id NUMBER, data SYS.ANYDATA);
INSERT INTO mytab (id, data)
VALUES (1, SYS.ANYDATA.ConvertNumber(5));
INSERT INTO mytab (id, data)
VALUES (2, SYS.ANYDATA.ConvertObject(Employee_type(5555, 'john')));
CREATE OR REPLACE PROCEDURE p IS
CURSOR cur IS SELECT id, data FROM mytab;
v_id mytab.id%TYPE;
v_data mytab.data%TYPE;
v_type SYS.ANYTYPE;
v_typecode PLS_INTEGER;
v_typename VARCHAR2(60);
v_dummy PLS_INTEGER;
v_n NUMBER;
v_employee employee_type;
non_null_anytype_for_NUMBER exception;
unknown_typename exception;
BEGIN
OPEN cur;
LOOP
FETCH cur INTO v_id, v_data;
EXIT WHEN cur%NOTFOUND;
/* typecode signifies type represented by v_data.
GetType also produces a value of type SYS.ANYTYPE with methods you
can call to find precision and scale of a number, length of a
string, and so on. */
v_typecode := v_data.GetType (v_type /* OUT */);
/* Compare typecode to DBMS_TYPES constants to determine type of data
and decide how to display it. */
CASE v_typecode
WHEN DBMS_TYPES.TYPECODE_NUMBER THEN
IF v_type IS NOT NULL THEN -- This condition should never happen.
RAISE non_null_anytype_for_NUMBER;
END IF;
-- For each type, there is a Get method.
v_dummy := v_data.GetNUMBER (v_n /* OUT */);
DBMS_OUTPUT.PUT_LINE
(TO_CHAR(v_id) || ': NUMBER = ' || TO_CHAR(v_n) );
WHEN DBMS_TYPES.TYPECODE_OBJECT THEN
v_typename := v_data.GetTypeName();
IF v_typename NOT IN ('HR.EMPLOYEE_TYPE') THEN
RAISE unknown_typename;
END IF;
v_dummy := v_data.GetObject (v_employee /* OUT */);
DBMS_OUTPUT.PUT_LINE
(TO_CHAR(v_id) || ': user-defined type = ' || v_typename ||
' ( ' || v_employee.empno || ', ' || v_employee.ename || ' )' );
END CASE;
END LOOP;
CLOSE cur;
EXCEPTION
WHEN non_null_anytype_for_NUMBER THEN
RAISE_Application_Error (-20000,
'Paradox: the return AnyType instance FROM GetType ' ||
'should be NULL for all but user-defined types');
WHEN unknown_typename THEN
RAISE_Application_Error( -20000, 'Unknown user-defined type ' ||
v_typename || ' - program written to handle only HR.EMPLOYEE_TYPE');
END;
/
SELECT t.data.gettypename() AS "Type Name" FROM mytab t;
Type Name
--------------------------------------------------------------------------------
SYS.NUMBER
HR.EMPLOYEE_TYPE
2 rows selected.
Representing ANSI, DB2, and SQL/DS Data
TIME, GRAPHIC, VARGRAPHIC, and LONG VARGRAPHIC, because they have no equivalent Oracle data types.
Representing Conditional Expressions as Data
DROP TABLE traders;
CREATE TABLE traders (
name VARCHAR2(10),
email VARCHAR2(20),
interest VARCHAR2(30)
);
CREATE OR REPLACE TYPE ticker AS OBJECT (
symbol VARCHAR2(20),
price NUMBER,
change NUMBER
);
/
ticker:
BEGIN
DBMS_EXPFIL.DROP_ATTRIBUTE_SET (attr_set => 'ticker');
END;
/
BEGIN
DBMS_EXPFIL.CREATE_ATTRIBUTE_SET
(attr_set => 'ticker',
from_type => 'YES');
END;
/
trader.interest:
BEGIN
DBMS_EXPFIL.ASSIGN_ATTRIBUTE_SET
(attr_set => 'ticker',
expr_tab => 'traders',
expr_col => 'interest');
END;
/
interest column stores valid conditional expressions.
INSERT INTO traders (name, email, interest)
VALUES ('Vishu', 'vishu@example.com', 'symbol = ''ABC'' AND price > 25');
EVALUATE operator to identify the conditional expressions that evaluate to TRUE for a given data item. For example, this query returns traders who are interested in the stock quote (symbol='ABC', price=31, change=5.2):
SELECT name, email
FROM traders
WHERE EVALUATE (
interest,
'symbol=>''ABC'',
price=>31,
change=>5.2'
) = 1;
NAME EMAIL
---------- --------------------
Vishu vishu@example.com
1 row selected.
interest column.
Identifying Rows by Address
ROWID pseudocolumn, whose value is a string that represents the address of the row. The string has the data type ROWID or UROWID.
ROWID of the row changes. HCC, a feature of certain Oracle storage systems, is described in Oracle Database Concepts.
Querying the ROWID Pseudocolumn
ROWID, which can appear in a query in either the SELECT list or WHERE clause.ROWID, populates it with rowids by querying the ROWID pseudocolumn inside an INSERT statement, and then displays it. The rowids of the table rows show how they are stored.
DROP TABLE t_tab; -- in case it exists
CREATE TABLE t_tab (col1 ROWID);
INSERT INTO t_tab (col1)
SELECT ROWID
FROM employees
WHERE employee_id > 199;
SELECT employee_id, rowid
FROM employees
WHERE employee_id > 199;
ROWID varies, but result is similar to:
EMPLOYEE_ID ROWID
----------- ------------------
200 AAAPeSAAFAAAABTAAC
201 AAAPeSAAFAAAABTAAD
202 AAAPeSAAFAAAABTAAE
203 AAAPeSAAFAAAABTAAF
204 AAAPeSAAFAAAABTAAG
205 AAAPeSAAFAAAABTAAH
206 AAAPeSAAFAAAABTAAI
7 rows selected.
SELECT * FROM t_tab;
COL1 varies, but result is similar to:
COL1
------------------
AAAPeSAAFAAAABTAAC
AAAPeSAAFAAAABTAAD
AAAPeSAAFAAAABTAAE
AAAPeSAAFAAAABTAAF
AAAPeSAAFAAAABTAAG
AAAPeSAAFAAAABTAAH
AAAPeSAAFAAAABTAAI
7 rows selected.
ROWID Data Type
ROWID pseudocolumn have the data type ROWID. Internally, this data type is a structure that stores information that the database server needs to access a row. The format of this structure is either restricted, extended, or external binary.
ROWID (like col1 in Example 2-5) does not guarantee that its values will be valid rowids.
Restricted Internal ROWID Format
ROWID structure with the restricted internal format has these components:ROWID pseudocolumn value to the client application as an 18-character string with a hexadecimal encoding of each component.
Extended Internal ROWID Format
ROWID structure with the extended internal format has the same components as the restricted format and a data object number, which identifies a database segment. On most platforms, the size of this structure is 10 bytes.ROWID pseudocolumn value to the client application as an 18-character string with a base-64 encoding of each component. For example, the string might be "AAAA8mAALAAAAQkAAA", which represents a base-64 encoding of the components of the extended ROWID in a four-piece format, OOOOOOFFFBBBBBBRRR.DBMS_ROWID package, described in Oracle Database PL/SQL Packages and Types Reference.
External Binary Internal ROWID Format
ROWID structure. For example, OCI and some precompiler applications can map the ROWID data type to a 3GL structure on bind or define calls.ROWID structure is the same size for restricted and extended rowids. For a restricted rowid, the data object number is stored in an unused field.ROWID, expressed as a C struct, is:
struct riddef {
ub4 ridobjnum; /* data obj#--this field is
unused in restricted ROWIDs */
ub2 ridfilenum;
ub1 filler;
ub4 ridblocknum;
ub2 ridslotnum;
}
UROWID Data Type
ROWID pseudocolumn have the data type UROWID. This data type stores a universal rowid (urowid).UROWID for the table and then retrieve the value of the ROWID pseudocolumn into that column.
How Oracle Database Converts Data Types
Data Type Conversion During Assignments
variable := expression
expression differs from that of variable, then Oracle Database tries to convert the data type of expression to that of variable. For information about when that is possible, see Oracle Database SQL Language Reference.NUMBER conversion succeeds only if the character string represents a valid number. A character-to-DATE conversion succeeds only if the character string satisfies the session default date format. (For information about the default date format, see "Displaying Current Date and Time".)test_package, its public variable var1, and table1_tab are declared as follows:
CREATE OR REPLACE PACKAGE test_package AS
var1 CHAR(5);
END;
/
DROP TABLE table1_tab;
CREATE TABLE table1_tab (col1 NUMBER);
variable := expression
expression must be either the same as, or implicitly convertible to, the data type of variable. For example, for this assignment, Oracle Database automatically converts zero to the data type of var1, which is CHAR(5):
var1 := 0;
INSERT INTO table1_tab (col1) VALUES (expression)
expression must be either the same as, or implicitly convertible to, the data type of col1. For example, for this statement, Oracle Database automatically converts the string '19' to the data type of col1, which is NUMBER:
INSERT INTO table1_tab (col1) VALUES ('19')
UPDATE table1_tab SET column = expression
expression must be either the same as, or implicitly convertible to, the data type of column. For example, for this statement, Oracle Database automatically converts the string '30' to the data type of col1, which is NUMBER:
UPDATE table1_tab SET col1 = '30';
SELECT column INTO variable FROM table1_tab
column must be either the same as, or convertible to, the data type of variable. For example, for this statement, Oracle Database automatically converts the value selected from col1, which is 30, to the data type of var1, which is CHAR(5):
SELECT col1 INTO var1 FROM table1_tab WHERE col1 = 30;
Data Type Conversion During Expression Evaluation
NUMBER; if the expression is the operand of a string function, then Oracle Database tries to convert the value of the expression to VARCHAR2.
variable := expression
expression, using the conversion rules for expressions. If the evaluation succeeds, the result is a single value of a single data type, which Oracle Database tries to assign to variable, using the conversion rules for assignments.
Metadata for SQL Operators and Functions
V$SQLFN_METADATA contains metadata about SQL operators and functions. For every function in V$SQLFN_METADATA, the dynamic performance view V$SQLFN_ARG_METADATA has one row of metadata about each function argument. If a function argument can be repeated (as in the functions LEAST and GREATEST), then V$SQLFN_ARG_METADATA has only one row for each repeating argument. You can join these two views on the column FUNCID.
V$SQLFN_METADATAV$SQLFN_ARG_METADATA
ARGn Data Type
V$SQLFN_METADATA, the column DATATYPE is the data type of the function (that is, the data type that the function returns). This data type can be an Oracle data type, data type family (see "Data Type Families"), or ARGn. ARGn is the data type of the nth argument of the function. For example:MAX function (described in Oracle Database SQL Language Reference) returns a value that has the data type of its first argument, so the MAX function has return data type ARG1.DECODE function (described in Oracle Database SQL Language Reference) returns a value that has the data type of its third argument, so the DECODE function has data type ARG3.
DISP_TYPE Data Type
V$SQLFN_METADATA, DISP_TYPE is the data type of an argument that can be any expression. An expression is either a single value or a combination of values and SQL functions that has a single value.
Data Type Families
PKEk
PK |%A OEBPS/dcommon/prodbig.gif GIF87a !!!)))111BBBZZZsss{{ZRRcZZ!!1!91)JB9B9)kkcJJB991ssc絽Zcc!! {祽BZc!9B!c{ !)c{9{Z{{cZB1)s Jk {{Z{kBsZJ91)Z{!{ BcsRsBc{ 9Z Zk甽k Bk R!BZ 9c )JJc{!))BZks{BcR{JsBk9k)Zck ! !B Z1k!ZcRBZc ZJkBk1Z9c!R!c9kZRZR B Z9{ 9 9 !R 1{ 99R{ 1!1)c 1 J)1B ! B J Rkk{ƽ絵ތkk絵RRs{{{{JJsssBBkkk!!9ss{{ZZssccJJZZRRccRRZZ))cBBJJ99JJ!!c11991199Z11!c!!))Z!! ! 1 B R c k { )!cJBkZRZ , HP)XRÇEZ֬4jJ0 @ "8p YҴESY3CƊ @* U:lY0_0#
5tX1E: C_xޘeK TList of Figures
g C)rr9+c:b Жf*s^ fKS7^}
*{zq_@8# p F~
[VPe(nw0MW=3#kȵ z晨cy PpG#W:% drMh] 3HH<\]ԁ |_ W
HHҡb}P >k {ZErxMX@8C&qs kLۙOnO^sCk7ql2XCw5VG.S~ H 8=(s 1~ cV5z
%v|U2QF=NoW]ո?<`~}=ӬfԵ,=; "~Iy7K#g{ñJ?5$y`
zz @-~ m7 mG宝Gٱ>G&K#]y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6S gp~;4W+חc"=|ř9bc5 > *r g {~cj1rnI#G|8v4wĿhFb><^ pJLm[Dl1;Vx5IZ: 1* p)إ1Z bAK(1ׅ|S& 5{^
KG ^ 5r>;X K^?
s fk^8O/"J)3K]N)iL
