78 DBMS_EPG
The DBMS_EPG
package implements the embedded PL/SQL gateway that enables a Web browser to invoke a PL/SQL stored procedure through an HTTP listener.
This chapter contains the following topics:
78.1 DBMS_EPG Overview
The DBMS_EPG
package is a platform on which PL/SQL users develop and deploy PL/SQL Web applications. The embedded PL/SQL gateway is an embedded version of the gateway that runs in the XML database HTTP server in the Oracle database. It provides the core features of mod_plsql
in the database but does not require the Oracle HTTP server powered by Apache.
In order to make a PL/SQL application accessible from a browser by way of HTTP, a Database Access Descriptor (DAD) must be created and mapped to a virtual path. A DAD is a set of configuration values used for database access and the virtual path mapping makes the application accessible under a virtual path of the XML DB HTTP Server. A DAD is represented as a servlet in XML DB HTTP Server.
78.2 DBMS_EPG Security Model
The XDBADMIN
role is required to invoke the configuration interface. It may invoked by the database user "XDB
".
The authorization interface can be invoked by any user.
78.3 DBMS_EPG Exceptions
The table in this topic lists the exceptions raised by the DBMS_EPG
package.
Table 78-1 DBMS_EPG Exceptions
Exception | Error Code | Description |
---|---|---|
|
20000 |
Database Access Descriptor (DAD) %s not found. Ensure that the name of the DAD is correct and that it exists. |
78.4 DBMS_EPG Data Structures
The DBMS_EPG
package defines a TABLE
type.
VARCHAR2_TABLE Table Type
This type is used by the procedures GET_ALL_GLOBAL_ATTRIBUTES
, GET_ALL_DAD_ATTRIBUTES
, GET_ALL_DAD_MAPPINGS
, and GET_DAD_LIST
to return lists of attribute names, attribute values, virtual paths, and database access descriptors (DAD).
TYPE VARCHAR2_TABLE IS TABLE OF VARCHAR2(4000) INDEX BY BINARY_INTEGER;
78.5 DBMS_EPG Subprogram Groups
The DBMS_EPG consists of two interfaces: configuration subprograms and authorization subprograms.
78.5.1 DBMS_EPG Configuration Subprograms
The Configuration subprogram group contain the subprogram interfaces to examine and modify the global and database access descriptor (DAD) specific settings of the embedded PL/SQL gateway.
Table 78-2 Configuration Subprogram Group
Subprogram | Description |
---|---|
Creates a new DAD |
|
Deletes a DAD attribute |
|
Deletes a global attribute |
|
Drops a DAD |
|
Retrieves all the attributes of a DAD. |
|
Retrieves all virtual paths to which the specified DAD is mapped. |
|
Retrieves all global attributes and values |
|
Retrieves the value of a DAD attribute |
|
Retrieves a list of all DADs for an Embedded Gateway instance. |
|
Retrieves the value of a global attribute |
|
Maps a DAD to the specified virtual path. |
|
Sets the value for a DAD |
|
Sets the value of a global attribute |
|
Unmaps a DAD from the specified virtual path |
78.5.2 DBMS_EPG Authorization Subprograms
The Authorization subprogram group contains the subprogram interfaces to authorize and deauthorize the use of a database user's privileges by the embedded PL/SQL gateway through a specific database access descriptor (DAD)
Table 78-3 Authorization Subprogram Group
Subprogram | Description |
---|---|
Authorizes a DAD to invoke procedures and access document tables with a database user's privileges |
|
Deauthorizes a DAD with regard to invoking procedures and accessing document tables with a database user's privileges |
78.6 Summary of DBMS_EPG Subprograms
This table lists the DBMS_ALERT
subprograms and briefly describes them.
Table 78-4 DBMS_EPG Package Subprograms
Subprogram | Description |
---|---|
authorizes a DAD to invoke procedures and access document tables with a database user's privileges |
|
Creates a new DAD |
|
Deauthorizes a DAD with regard to invoking procedures and accessing document tables with a database user's privileges |
|
Deletes a DAD attribute |
|
Deletes a global attribute |
|
Drops a DAD |
|
Retrieves all the attributes of a DAD. |
|
Retrieves all virtual paths to which the specified DAD is mapped. |
|
Retrieves all global attributes and values |
|
Retrieves the value of a DAD attribute |
|
Retrieves a list of all DADs for an Embedded Gateway instance. |
|
Retrieves the value of a global attribute |
|
Maps a DAD to the specified virtual path. |
|
Sets the value for a DAD |
|
Sets the value of a global attribute |
|
Unmaps a DAD from the specified virtual path |
78.6.1 AUTHORIZE_DAD Procedure
This procedure authorizes a DAD to invoke procedures and access document tables with a database user's privileges. The invoker can always authorize the use of her/his own privileges.
See Also:
Authorization Subprograms for other subprograms in this group
Syntax
DBMS_EPG.AUTHORIZE_DAD ( dad_name IN VARCHAR2, path IN VARCHAR2 DEFAULT NULL);
Parameters
Table 78-5 AUTHORIZE_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD to create |
|
The user whose privileges to deauthorize. If use, the invoker is assumed. |
Usage Notes
-
To authorize the use of another user's privileges, the invoker must have the
ALTER
USER
system privilege. -
The DAD must exist but its "database-username" DAD attribute does not have to be set to user to authorize.
-
Multiple users can authorize the same DAD and it is up to the DAD's "database-username" setting to decide which user's privileges to use.
Exceptions
Raises an error if the DAD or user does not exist, or the invoker does not have the needed system privilege.
Examples
DBMS_EPG.AUTHORIZE_DAD('HR');
78.6.2 CREATE_DAD Procedure
This procedure creates a new DAD.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.CREATE_DAD ( dad_name IN VARCHAR2, path IN VARCHAR2 DEFAULT NULL);
Parameters
Table 78-6 CREATE_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD to create |
|
The virtual path to which to map the DAD |
78.6.3 DEAUTHORIZE_DAD Procedure
This procedure deauthorizes a DAD with regard to invoking procedures and accessing document tables with a database user's privileges. The invoker can always deauthorize the use of his own privileges.
See Also:
Authorization Subprograms for other subprograms in this group
Syntax
DBMS_EPG.DEAUTHORIZE_DAD ( dad_name IN VARCHAR2, path IN VARCHAR2 DEFAULT NULL);
Parameters
Table 78-7 DEAUTHORIZE_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD for which to deauthorize use |
|
The user whose privileges to deauthorize. If use, the invoker is assumed. |
Usage Notes
To deauthorize the use of another user's privileges, the invoker must have the ALTER
USER
system privilege.
Exceptions
Raises an error if the DAD or user does not exist, or the invoker does not have the needed system privilege.
Examples
DBMS_EPG.DEAUTHORIZE_DAD('HR');
78.6.4 DELETE_DAD_ATTRIBUTE Procedure
This procedure deletes a DAD attribute.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.DELETE_DAD_ATTRIBUTE ( dad_name IN VARCHAR2, attr_name IN VARCHAR2);
Parameters
Table 78-8 DELETE_DAD_ATTRIBUTE Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD for which to delete a DAD attribute |
|
The name of the DAD attribute to delete |
Exceptions
Raises an error if DAD does not exist
78.6.5 DELETE_GLOBAL_ATTRIBUTE Procedure
This procedure deletes a global attribute.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.DELETE_GLOBAL_ATTRIBUTE ( attr_name IN VARCHAR2);
Parameters
Table 78-9 DELETE_GLOBAL_ATTRIBUTE Procedure Parameters
Parameter | Description |
---|---|
|
The global attribute to delete |
78.6.6 DROP_DAD Procedure
This procedure drops a DAD. All the virtual-path mappings of the DAD will be dropped also.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.DROP_DAD ( dadname IN VARCHAR2);
Parameters
Table 78-10 DROP_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The DAD to drop |
Exceptions
Raises an error if the DAD does not exist.
78.6.7 GET_ALL_DAD_ATTRIBUTES Procedure
This procedure retrieves all the attributes of a DAD. The outputs are 2 correlated index-by tables of the name/value pairs.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_ALL_DAD_ATTRIBUTES ( dad_name IN VARCHAR2, attr_names OUT NOCOPY VARCHAR2_TABLE, attr_values OUT NOCOPY VARCHAR2_TABLE);
Parameters
Table 78-11 GET_ALL_DAD_ATTRIBUTES Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD |
|
The attribute names |
|
The attribute values |
Exceptions
Raises an error if DAD does not exist.
Usage Notes
If the DAD has no attributes set, then attr_names
and attr_values
will be set to empty arrays.
78.6.8 GET_ALL_DAD_MAPPINGS Procedure
This procedure retrieves all the virtual paths to which the specified DAD is mapped.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_ALL_DAD_MAPPINGS ( dad_name IN VARCHAR2, paths OUT NOCOPY VARCHAR2_TABLE);
Parameters
Table 78-12 GET_ALL_DAD_MAPPINGS Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD |
|
The virtual paths to which h the DAD is mapped |
Exceptions
Raises an error if DAD does not exist.
Usage Notes
If the DAD is not mapped to any virtual path, paths
will be set to empty arrays.
78.6.9 GET_ALL_GLOBAL_ATTRIBUTES Procedure
This procedure retrieves all global attributes and values. The outputs are 2 correlated index-by tables of the name/value pairs.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_ALL_GLOBAL_ATTRIBUTES ( attr_names OUT NOCOPY VARCHAR2_TABLE, attr_values OUT NOCOPY VARCHAR2_TABLE);
Parameters
Table 78-13 GET_ALL_GLOBAL_ATTRIBUTES Procedure Parameters
Parameter | Description |
---|---|
|
The global attribute names |
|
The values of the global attributes |
Usage Notes
If the gateway instance has no global attributes set, then attr_names
and attr_values
will be set to empty arrays.
78.6.10 GET_DAD_ATTRIBUTE Function
This procedure retrieves the value of a DAD attribute.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_DAD_ATTRIBUTE ( dad_name IN VARCHAR2, attr_name IN VARCHAR2) RETURN VARCHAR2;
Parameters
Table 78-14 GET_DAD_ATTRIBUTE Function Parameters
Parameter | Description |
---|---|
|
The name of the DAD for which to delete an attribute |
|
The name of the attribute to delete |
Return values
Returns the DAD attribute value. Returns NULL
if attribute is unknown or has not been set.
Exceptions
Raises an error if DAD does not exist.
78.6.11 GET_DAD_LIST Procedure
This procedure retrieves a list of all DADs for an Embedded Gateway instance.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_DAD_LIST ( dad_names OUT NOCOPY VARCHAR2_TABLE);
Parameters
Table 78-15 GET_DAD_LIST Procedure Parameters
Parameter | Description |
---|---|
|
The list of all DADs |
Usage Notes
If no DADs exist then dad_names
will be set to an empty array.
78.6.12 GET_GLOBAL_ATTRIBUTE Function
This function retrieves the value of a global attribute.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.GET_GLOBAL_ATTRIBUTE ( attr_name IN VARCHAR2) RETURN VARCHAR2;
Parameters
Table 78-16 GET_GLOBAL_ATTRIBUTE Procedure Parameters
Parameter | Description |
---|---|
|
The global attribute to retrieve |
Return Values
Returns the global attribute value. Returns NULL
if attribute has not been set or is not a valid attribute.
78.6.13 MAP_DAD Procedure
This procedure maps a DAD to the specified virtual path. If the virtual path exists already, the old virtual-path mapping will be overridden.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.MAP_DAD ( dad_name IN VARCHAR2, path IN VARCHAR2);
Parameters
Table 78-17 MAP_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD to map |
|
The virtual path to map |
Exceptions
Raises and error if the DAD does not exist.
78.6.14 SET_DAD_ATTRIBUTE Procedure
This procedure sets the value for a DAD.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.SET_DAD_ATTRIBUTE ( dad_name IN VARCHAR2, attr_name IN VARCHAR2, attr_value IN VARCHAR2);
Parameters
Table 78-18 SET_DAD_ATTRIBUTE Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD for which to set the attribute |
|
The name of the attribute to set |
|
The attribute value to set |
Table 78-19 Mapping Between mod_plsql and Embedded PL/SQL Gateway DAD Attributes
mod_plsql DAD Attribute | Embedded PL/SQL Gateway DAD Attribute | Allows Multiple Occurr-ences | Legal Values |
---|---|---|---|
|
|
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 |
|
i |
No |
Enumeration of InfoDebug |
|
|
No |
Enumeration of On, Off |
|
|
No |
Unsigned integer |
|
|
No |
String |
|
|
No |
String |
|
|
No |
String |
|
|
No |
String |
|
|
No |
String |
|
|
No |
Enumeration of StatelessWithResetPackageState, StatelessWithFastRestPackageState, StatelessWithPreservePackageState |
|
|
No |
Enumeration of Char, Raw |
|
|
No |
String |
Exceptions
Raises an error if DAD does not exist or the attribute is unknown.
Usage Notes
-
If
attr_name
attribute has been set before, then the old value will be overwritten with the newattr_value
argument. -
The embedded gateway assumes default values when the attributes are not set. The default values of the DAD attributes should be sufficient for most users of the embedded gateway. mod_plsql users should note the following
-
The
PlsqlDatabasePassword
attribute is not needed. -
The
PlsqlDatabaseConnectString
attribute is not needed because the embedded gateway does not support logon to external databases.
-
Examples
DBMS_EPG.SET_DAD_ATTRIBUTE('HR', 'default-page', 'HRApp.home');
78.6.15 SET_GLOBAL_ATTRIBUTE Procedure
This procedure sets the value of a global attribute.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.SET_GLOBAL_ATTRIBUTE ( attr_name IN VARCHAR2, attr_value IN VARCHAR2);
Parameters
Table 78-20 SET_GLOBAL_ATTRIBUTE Procedure Parameters
Parameter | Description |
---|---|
|
The global attribute to set |
|
The attribute value to set |
Table 78-21 Mapping Between mod_plsql and Embedded PL/SQL Gateway Global Attributes
mod_plsql Global Attribute | Embedded PL/SQL Gateway Global Attribute | Allows Multiple Occurr-ences | Legal Values |
---|---|---|---|
|
|
No |
Unsigned integer |
|
|
No |
Unsigned integer |
Usage Notes
-
The attribute name is case sensitive. The value may or may not be case-sensitive depending on the attribute.
-
If
attr_name
attribute has been set before, then the old value will be overwritten with the newattr_value
argument.
Exceptions
Raises an error if the attribute is unknown.
Examples
dbms_epg.set_global_attribute('max-parameters', '100');
78.6.16 UNMAP_DAD Procedure
This procedure unmaps a DAD from the specified virtual path. If path is NULL
, the procedure removes all virtual-path mappings for the DAD but keeps the DAD.
See Also:
Configuration Subprograms for other subprograms in this group
Syntax
DBMS_EPG.UNMAP_DAD ( dad_name IN VARCHAR2, path IN VARCHAR2 DEFAULT NULL);
Parameters
Table 78-22 UNMAP_DAD Procedure Parameters
Parameter | Description |
---|---|
|
The name of the DAD to unmap |
|
The virtual path to unmap |
Usage Notes
Raises and error if the DAD does not exist.