Oracle supplies many PL/SQL packages with the Oracle server to extend database functionality and provide PL/SQL access to SQL features. You can use the supplied packages when creating your applications or for ideas in creating your own stored procedures.
Note:
This manual covers the packages provided with the Oracle database server. Packages supplied with other products, such as Oracle Developer or the Oracle Application Server, are not covered.This chapter contains the following topics:
Summary of Oracle Supplied PL/SQL Packages
See Also:
Oracle Database Application Developer's Guide - Fundamentals for information on how to create your own packagesA package is an encapsulated collection of related program objects stored together in the database. Program objects are procedures, functions, variables, constants, cursors, and exceptions.
Packages have many advantages over standalone procedures and functions. 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 to read multiple package objects into memory at once.
Let you overload procedures or functions. Overloading means creating multiple procedures with the same name in the same package, each taking arguments of different number or datatype.
Can contain global variables and cursors that are available to all procedures and functions in the package.
PL/SQL packages have two parts: the specification and the body, although sometimes the body is unnecessary. The specification is the interface to your application; it declares the types, variables, constants, exceptions, cursors, and subprograms available for use. The body fully defines cursors and subprograms, and so implements the specification.
Unlike subprograms, packages cannot be called, parameterized, or nested. However, the formats of a package and a subprogram are similar:
CREATE PACKAGE name AS -- specification (visible part) -- public type and item declarations -- subprogram specifications END [name]; CREATE PACKAGE BODY name AS -- body (hidden part) -- private type and item declarations -- subprogram bodies [BEGIN -- initialization statements] END [name];
The specification holds public declarations that are visible to your application. The body holds implementation details and private declarations that are hidden from your application. You can debug, enhance, or replace a package body without changing the specification. You can change a package body without recompiling calling programs because the implementation details in the body are hidden from your application.
Most Oracle supplied packages are automatically installed when the database is created and the CATPROC
.SQL
script is run. For example, to create the DBMS_ALERT
package, the DBMSALRT
.SQL
and PRVTALRT
.PLB
scripts must be run when connected as the user SYS
. These scripts are run automatically by the CATPROC
.SQL
script.
Certain packages are not installed automatically. Special installation instructions for these packages are documented in the individual chapters.
To call a PL/SQL function from SQL, you must either own the function or have EXECUTE
privileges on the function. To select from a view defined with a PL/SQL function, you must have SELECT
privileges on the view. No separate EXECUTE
privileges are needed to select from the view. Instructions on special requirements for packages are documented in the individual chapters.
To create packages and store them permanently in an Oracle database, use the CREATE
PACKAGE
and CREATE
PACKAGE
BODY
statements. You can execute these statements interactively from SQL*Plus or Enterprise Manager.
To create a new package, do the following:
Create the package specification with the CREATE
PACKAGE
statement.
You can declare program objects in the package specification. Such objects are called public objects. Public objects can be referenced outside the package, as well as by other objects in the package.
Create the package body with the CREATE
PACKAGE
BODY
statement.
You can declare and define program objects in the package body.
You must define public objects declared in the package specification.
You can declare and define additional package objects, called private objects. Private objects are declared in the package body rather than in the package specification, so they can be referenced only by other objects in the package. They cannot be referenced outside the package.
See Also:
Oracle Database Application Developer's Guide - Fundamentalsfor more information on creating new packages
for more information on storing and executing packages
The specification 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 the objects declared in the specification, as well as private objects that are not visible to applications outside the package.
Oracle stores the specification and body of a package separately in the database. Other schema objects that call or reference public program objects depend only on the package specification, not on the package body. Using this distinction, you can change the definition of a program object in the package body without causing Oracle to invalidate other schema objects that call or reference the program object. Oracle invalidates dependent schema objects only if you change the declaration of the program object in the package specification.
The following example shows a package specification for a package named EMPLOYEE_MANAGEMENT
. The package contains one stored function and two stored procedures.
CREATE PACKAGE employee_management AS FUNCTION hire_emp (name VARCHAR2, job VARCHAR2, mgr NUMBER, hiredate DATE, sal NUMBER, comm NUMBER, deptno NUMBER) RETURN NUMBER; PROCEDURE fire_emp (emp_id NUMBER); PROCEDURE sal_raise (emp_id NUMBER, sal_incr NUMBER); END employee_management;
The body for this package defines the function and the procedures:
CREATE PACKAGE BODY employee_management AS FUNCTION hire_emp (name VARCHAR2, job VARCHAR2, mgr NUMBER, hiredate DATE, sal NUMBER, comm NUMBER, deptno NUMBER) RETURN NUMBER IS
The function accepts all arguments for the fields in the employee table except for the employee number. A value for this field is supplied by a sequence. The function returns the sequence number generated by the call to this function.
new_empno NUMBER(10); BEGIN SELECT emp_sequence.NEXTVAL INTO new_empno FROM dual; INSERT INTO emp VALUES (new_empno, name, job, mgr, hiredate, sal, comm, deptno); RETURN (new_empno); END hire_emp; PROCEDURE fire_emp(emp_id IN NUMBER) AS
The procedure deletes the employee with an employee number that corresponds to the argument emp_id
. If no employee is found, then an exception is raised.
BEGIN DELETE FROM emp WHERE empno = 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) AS
The procedure accepts two arguments. Emp_id
is a number that corresponds to an employee number. Sal_incr
is the amount by which to increase the employee's salary.
BEGIN -- If employee exists, then update salary with increase. UPDATE emp SET sal = sal + sal_incr WHERE empno = 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;
Note:
If you want to try this example, then first create the sequence numberemp_sequence
. You can do this using the following SQL*Plus statement:
SQL> CREATE SEQUENCE emp_sequence > START WITH 8000 INCREMENT BY 10;
To reference the types, items, and subprograms declared in a package specification, use the dot notation. For example:
package_name.type_name package_name.item_name package_name.subprogram_name
Table 1-1 lists the supplied PL/SQL server packages. These packages run as the invoking user, rather than the package owner. Unless otherwise noted, the packages are callable through public synonyms of the same name.
Caution:
The procedures and functions provided in these packages and their external interfaces are reserved by Oracle and are subject to change.
Modifying Oracle supplied packages can cause internal errors and database security violations. Do not modify supplied packages.
Table 1-1 Summary of Oracle Supplied PL/SQL Packages
Package Name | Description |
---|---|
|
Lets you administer servers and the data dictionary. |
|
Lets you generate CTXRULE rules for a set of documents. |
|
Lets you create and manage the preferences, section lists and stopgroups required for Text indexes. |
|
Lets you request document services. |
|
Lets you manage the index log. |
|
Lets you generate query feedback, count hits, and create stored query expressions. |
|
Lets you create various index reports. |
|
Lets you to manage and browse thesauri. |
|
For use with the user-lexer. |
|
Contains interfaces for advanced query rewrite users to create, drop, and maintain functional equivalence declarations for query rewrite. |
|
Part of the SQLAccess Advisor, an expert system that identifies and helps resolve performance problems relating to the execution of SQL statements. |
|
Provides support for the asynchronous notification of database events. |
|
Lets you register an application name with the database for auditing or performance tracking purposes. |
|
Provides administrative procedures to start, stop, and configure an apply process. |
|
Lets you add a message (of a predefined object type) onto a queue or to dequeue a message. |
|
Lets you perform administrative functions on a queue or queue table for messages of a predefined object type. |
|
Provides procedures to manage the configuration of Advanced Queuing asynchronous notification by e-mail and HTTP. |
|
Plays a part in providing secure access to the Oracle JMS interfaces. |
|
Describes administrative procedures to start, stop, and configure a capture process; used in Streams. |
|
Identifies new data that has been added to, modified, or removed from, relational tables and publishes the changed data in a form that is usable by an application. |
|
Lets you view and query the change data that was captured and published with the DBMS_LOGMNR_CDC_PUBLISH package. |
|
Is part of a set of features that clients use to receive notifications when result sets of a query have changed. The package contains interfaces that can be used by mid-tier clients to register objects and specify delivery mechanisms. |
|
Lets you encrypt and decrypt stored data, can be used in conjunction with PL/SQL programs running network communications, and supports encryption and hashing algorithms. |
|
Lets you use data mining to discover hidden patterns and use that knowledge to make predictions. |
|
Provides set of data transformation utilities available for use with the DBMS_DATA_MINING package for preparing mining data. |
|
Lets you move all, or part of, a database between databases, including both data and metadata. |
|
Specifies the Oracle version numbers and other information useful for simple conditional compilation selections based on Oracle versions. |
|
Provides access to some SQL DDL statements from stored procedures, and provides special administration operations not available as DDLs. |
|
Implements server-side debuggers and provides a way to debug server-side PL/SQL program units. |
|
Provides the user interface to a replicated transactional deferred remote procedure call facility. Requires the Distributed Option. |
|
Permits querying the deferred remote procedure calls (RPC) queue data that is not exposed through views. Requires the Distributed Option. |
|
Provides the system administrator interface to a replicated transactional deferred remote procedure call facility. Requires the Distributed Option. |
|
Describes the arguments of a stored procedure with full name translation and security checking. |
|
Enables you to verify dimension relationships and provides an alternative to the Enterprise Manager Dimension Wizard for displaying a dimension definition |
|
Maintains the Trusted Database List, which is used to determine if a privileged database link from a particular server can be accepted. |
|
Implements the embedded PL/SQL gateway that enables a web browser to invoke a PL/SQL stored procedure through an HTTP listener. |
|
Provides a procedure that enables you to create an error logging table so that DML operations can continue after encountering errors rather than abort and roll back. |
|
Contains all the procedures used to manage attribute sets, expression sets, expression indexes, optimizer statistics, and privileges by Expression Filter. |
|
Provides fine-grained security functions. |
|
One of a set of Streams packages, provides administrative interfaces for managing file groups, file group versions, files and file group repositories. |
|
Lets you copy a binary file within a database or to transfer a binary file between databases. |
|
Lets you flash back to a version of the database at a specified wall-clock time or a specified system change number (SCN). |
|
Enables frequent itemset counting. |
|
Lets you use Heterogeneous Services to send pass-through SQL statements to non-Oracle systems. |
|
Creates a table into which references to the chained rows for an Index Organized Table can be placed using the |
|
Provides a PL/SQL interface for accessing database functionality from Java |
|
Lets you schedule administrative procedures that you want performed at periodic intervals; it is also the interface for the job queue. |
|
Provides functions and procedures to access data from LDAP servers. |
|
Provides the Oracle Extension utility functions for LDAP. |
|
Prepares the library cache on an Oracle instance by extracting SQL and PL/SQL from a remote instance and compiling this SQL locally without execution. |
|
Provides general purpose routines for operations on Oracle Large Object ( |
|
Lets you request, convert and release locks through Oracle Lock Management services. |
|
Provides functions to initialize and run the log reader. |
|
Queries the dictionary tables of the current database, and creates a text based file containing their contents. |
|
Describes procedures for configuring and managing the logical standby database environment. |
|
Lets callers easily retrieve complete database object definitions (metadata) from the dictionary. |
|
Describes the Messaging Gateway administrative interface; used in Advanced Queuing. |
|
Describes object types—used by the canonical message types to convert message bodies—and helper methods, constants, and subprograms for working with the Messaging Gateway message types; used in Advanced Queuing. |
|
Let you use PL/SQL for controlling additional tracing and statistics gathering. |
|
Lets you refresh snapshots that are not part of the same refresh group and purge logs. |
|
Provides procedures for Data Encryption Standards. |
|
Returns the CPU cost of a user function based on the elapsed time of the function. |
|
Provides public APIs for offline instantiation of master groups. |
|
Provides procedures for summaries, dimensions, and query rewrites. |
|
Provides the interface for procedures and functions associated with management of stored outlines. Synonymous with |
|
Lets you edit an invoker's rights package. |
|
Accumulates information in a buffer so that it can be retrieved later. |
|
Provides intra-partition parallelism for creating partition-wise local indexes. |
|
Provides a DBMS pipe service which enables messages to be sent between sessions. |
|
Automates the data mining process from data preprocessing through model building to scoring new data. |
|
Provides an interface to print or retrieve the source text of a PL/SQL unit in its post-processed form. |
|
Provides a Probe Profiler API to profile existing PL/SQL applications and identify performance bottlenecks. |
|
Provides administrative procedures for configuring propagation from a source queue to a destination queue. |
|
Provides a built-in random number generator. |
|
Provides APIs used to detect and resolve data inconsistencies between two replicated sites. |
|
Lets you perform an online reorganization of tables. |
|
Lets you create groups of snapshots that can be refreshed together to a transactionally consistent point in time. Requires the Distributed Option. |
|
Provides data corruption repair procedures. |
|
Provides routines to administer and update the replication catalog and environment. Requires the Replication Option. |
|
Lets you create users with the privileges needed by the symmetric replication facility. Requires the Replication Option. |
|
Instantiates deployment templates. Requires the Replication Option. |
|
Controls the maintenance and definition of refresh group templates. Requires the Replication Option. |
|
Provides routines to generate shadow tables, triggers, and packages for table replication. |
|
Maintains plans, consumer groups, and plan directives; it also provides semantics so that you may group together changes to the plan schema. |
|
Maintains privileges associated with resource consumer groups. |
|
Lets you suspend large operations that run out of space or reach space limits after executing for a long time, fix the problem, and make the statement resume execution. |
|
Contains various procedures to create and manage rules and rule sessions by the Rules Manager. |
|
Provides row level security administrative interface. |
|
Provides procedures to create rowids and to interpret their contents. |
|
Describes the |
|
Describes the administrative interface for creating and managing rules, rule sets, and rule evaluation contexts; used in Streams. |
|
Provides a collection of scheduling functions that are callable from any PL/SQL program. |
|
Lets you issue alerts when some threshold has been violated. |
|
Lets you create, delete, activate and deactivate services for a single instance. |
|
Provides access to SQL |
|
Lets you keep objects in shared memory, so that they will not be aged out with the normal LRU mechanism. |
|
Provides segment space information not available through standard SQL. |
|
Provides tablespace and segment space administration not available through the standard SQL. |
|
Lets you use dynamic SQL to access the database. |
|
Provides the interface to tune SQL statements. |
|
Provides statistical functions. |
|
Provides a mechanism for users to view and modify optimizer statistics gathered for database objects. |
|
Communicates with FMON to invoke mapping operations. |
|
Describes the interface to convert |
|
Describes administrative procedures for adding and removing simple rules, without transformations, for capture, propagation, and apply at the table, schema, and database level. |
|
Provides interfaces for granting privileges to Streams administrators and revoking privileges from Streams administrators. |
|
Provides interfaces to enqueue messages into and dequeue messages from a |
|
Provides administrative procedures for copying tablespaces between databases and moving tablespaces from one database to another. |
|
Provides routines to start and stop PL/SQL tracing. |
|
Provides access to SQL transaction statements from stored procedures and monitors transaction activities. |
|
Provides an interface to the message format transformation features of Oracle Advanced Queuing. |
|
Reports whether a database can be transported between platforms using the RMAN |
|
Checks if the transportable set is self-contained. |
|
Consists of constants, which represent the built-in and user-defined types. |
|
Provides various utility routines. |
|
Provides the interface to query, modify and delete current system or session settings. |
|
lets you manage the Workload Repository, performing operations such as managing snapshots and baselines. |
|
Describes how to use the programming interface to Oracle Database Workspace Manager to work with long transactions. |
|
Describes Resource Management and Access Control APIs for PL/SQL |
|
Describes versioning APIs |
|
Describes how an administrator can create a ConText index on the XML DB hierarchy and configure it for automatic maintenance |
|
Controls the Oracle XML DB repository security, which is based on Access Control Lists (ACLs). |
|
Explains access to XMLType objects |
|
Converts the results of a SQL query to a canonical XML format. |
|
Explains access to the contents and structure of XML documents. |
|
Provides database-to-XMLType functionality. |
|
Provides XML-to-database-type functionality. |
|
Explains procedures to register and delete XML schemas. |
|
Provides the ability to store XML data in relational tables. |
|
Describes how to format the output of the |
|
Explains access to the contents and structure of XML documents. |
|
Lets you debug external procedures on platforms with debuggers that attach to a running process. |
|
Hypertext functions generate HTML tags. |
|
Enables users to take advantage of global variables |
|
Enables users to create form elements dynamically based on a SQL query instead of creating individual items page by page. |
|
Enables users to create form elements dynamically based on a SQL query instead of creating individual items page by page. |
|
Provides utilities for getting and setting session state, getting files, checking authorizations for users, resetting different states for users, and also getting and setting preferences for users. |
|
Hypertext procedures generate HTML tags. |
|
Provides an interface that enables the |
|
Provides an interface for sending and retrieving HTTP cookies from the client's browser. |
|
Provides a Global PLSQL Agent Authorization callback function |
|
Provides an interface to access the coordinates where a user clicked on an image. |
|
Contains subprograms that impose optimistic locking strategies so as to prevent lost updates. |
|
Provides an interface to locate text patterns within strings and replace the matched string with another string. |
|
Provides an interface for custom authentication. |
|
Contains subprograms used by |
|
Contains utility subprograms for performing operations such as getting the value of CGI environment variables, printing the data that is returned to the client, and printing the results of a query in an HTML table. |
|
Provides functions for coordinate system transformation. |
|
Contains the Oracle Spatial geocoding subprograms, which let you geocode unformatted postal addresses. |
|
Provides functions implementing geometric operations on spatial objects. |
|
Contains functions and procedures for the Spatial GeoRaster feature, which lets you store, index, query, analyze, and deliver raster image data and its associated Spatial vector geometry data and metadata. |
|
Contains utility functions and procedures for the Spatial GeoRaster feature, including those related to using triggers with GeoRaster data. |
|
Provides functions for linear referencing system support. |
|
Provides functions for migrating spatial data from previous releases. |
|
Provides functions and procedures for working with data modeled as nodes and links in a network. |
|
Contains functions and procedures for performing editing and analysis operations on network data using a network memory object |
|
Contains functions and procedures for spatial analysis and data mining. |
|
Provides procedures for creating and managing Spatial topologies. |
|
Contains subprograms for editing Spatial topologies using a cache (TopoMap object). |
|
Provides functions for selecting parameters that determine the behavior of the spatial indexing scheme used in Oracle Spatial. |
|
Provides utility functions and procedures for Oracle Spatial. |
|
Enables PL/SQL programs to use collection locators to query and update. |
|
Provides a set of data compression utilities. |
|
Provides database web services. |
|
Provides functions that encode RAW data into a standard encoded format so that the data can be transported between hosts. |
|
Enables your PL/SQL programs to read and write operating system text files and provides a restricted version of standard operating system stream file I/O. |
|
Enables HTTP callouts from PL/SQL and SQL to access data on the Internet or to call Oracle Web Server Cartridges. |
|
Provides a set of services (Oracle Globalization Service) that help developers build multilingual applications. |
|
Provides a procedure to support internet addressing. |
|
Retrieves and formats error messages in different languages. |
|
A utility for managing email which includes commonly used email features, such as attachments, CC, BCC, and return receipt. |
|
Exposes a subset of the BLAS and LAPACK (Version 3.0) operations on vectors and matrices represented as |
|
Provides SQL functions for |
|
Recompiles invalid PL/SQL modules, Java classes, indextypes and operators in a database, either sequentially or in parallel. |
|
Enables a PL/SQL program to access an object by providing a reference to the object. |
|
Provides PL/SQL functionality to send emails. |
|
Provides PL/SQL functionality to support simple TCP/IP-based communications between servers and the outside world. |
|
Provides escape and unescape mechanisms for URL characters. |
|
Provides an interface to download files, both BLOBs and BFILEs |
|
A self-describing data instance type containing an instance of the type plus a description |
|
Contains a description of a given type plus a set of data instances of that type |
|
Contains a type description of any persistent SQL type, named or unnamed, including object types and collection types; or, it can be used to construct new transient type descriptions |
|
Describes the types used in Advanced Queuing |
|
Contains URI Support, UriType Super Type, HttpUriType Subtype, DBUriType Subtype, XDBUriType Subtype, UriFactory Package |
|
Describes JMS types so that a PL/SQL application can use JMS queues of JMS types |
|
Describes LCR types, which are message payloads that contain information about changes to a database, used in Streams |
|
Supports the storage and management of audio data. |
|
Supports the storage and management of heterogeneous media data including image, audio, and video. |
|
Supports the storage, management, and manipulation of image data. |
|
Supports content-based retrieval of images (image matching). |
|
Provides support for the SQL/MM Still Image Standard, which lets you store, retrieve, and modify images in the database and locate images using visual predicates. |
|
Supports the storage and management of video data. |
|
Describes the types used with rules, rule sets, and evaluation contexts |
|
Describes the types and functions used for native XML support in the server. |