Oracle Built−in Packages- P160 pot

Remote Procedure Calls17.3 DBMS_DEFER: Building Deferred Calls The DBMS_DEFER package builds deferred remote procedure calls.. Table 17.11: DBMS_DEFER Programs COMMIT_WORK Commits deferr

Trang 1

Remote Procedure Calls

17.3 DBMS_DEFER: Building Deferred Calls

The DBMS_DEFER package builds deferred remote procedure calls

WARNING: DBMS_DEFER can execute procedures at remote sites under a highly

privileged account, such as the replication administrator account Therefore, EXECUTE

privileges on DBMS_DEFER should not be widely granted As a general rule, you should

restrict it to DBA accounts If you want to provide end users with the ability to create their

own deferred calls, you should create a cover package and grant EXECUTE on it to end users

or end user roles

17.3.1 Getting Started with DBMS_DEFER

The DBMS_DEFER package is created when the Oracle database is installed The dbmsdefr.sql script (found

in the built−in packages source directory, as described in Chapter 1) contains the source code for this

package's specification This script is called by catrep.sql, which must be run to install the advanced

replication packages The script creates the public synonym DBMS_DEFER EXECUTE privileges on

DBMS_DEFER are not granted The following procedures grant EXECUTE privilege on DBMS_DEFER to the specified grantees:

DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPGROUP

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPSCHEMA

DBMS_REPCAT_ADMIN.GRANT_ADMIN_REPGROUP

DBMS_REPCAT_ADMIN.GRANT_ADMIN_REPSCHEMA

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPGROUP

17.3.1.1 DBMS_DEFER programs

Table 17.11 lists the programs available in the DBMS_DEFER package

Table 17.11: DBMS_DEFER Programs

COMMIT_WORK Commits deferred RPC transaction No

<datatype>_ARG Adds parameter of specified datatype to a deferred call;

<datatype> may be CHAR, DATE, NUMBER, RAW, ROWID, or VARCHAR2

No

786

Trang 2

TRANSACTION Marks a transaction as deferred No

17.3.1.2 DBMS_DEFER exceptions

The DBMS_DEFER package may raise any of the exceptions listed in Table 17.12

Table 17.12: DBMS_DEFER Exceptions

Name Number Description

bad_param_type −23325 Parameter type does not match actual type

deferred_rpc_quiesce −23326 Database is quiescing

dbms_defererror −23305 Generic internal errors

malformedcall −23304 Argument count mismatches, etc

updateconflict −23303 Remote update failed due to conflict

commfailure −23302 Remote update failed due to communication failure

mixeddest −23301 Destinations for transaction not specified consistently

parameterlength −23323 Parameter length exceeds limits (2000 for CHAR/VARCHAR, 255 for

RAW) executiondisabled −23354 Deferred RPC execution is disabled

17.3.1.3 DBMS_DEFER nonprogram elements

Table 17.13 lists the constants and other nonprogram elements defined in the DBMS_DEFER package The DBMS_DEFER.NODE_LIST_T element is a PL/SQL table whose first entry is always placed in row 1 It is filled sequentially, with each subsequent entry placed in row DBMS_DEFER.NODE_LIST_T.LAST + 1

Table 17.13: DBMS_DEFER Other Elements

CONSTANT arg_csetid_none

(Oracle8)

Internal Character Set ID Value = 0 Includes types DATE, NUMBER, ROWID, RAW, and BLOB

CONSTANT arg_form_none

(Oracle8)

Internal Character Set ID Value = 0 Includes types DATE, NUMBER, ROWID, RAW, and BLOB

CONSTANT arg_form_implicit

(Oracle8)

Internal Character Set ID Value = 1 Includes types CHAR, VARCHAR2, and CLOB

CONSTANT arg_form_nchar

(Oracle8)

Internal Character Set ID Value = 2 Includes types NCHAR, NVARCHAR2, and NCLOB

CONSTANT arg_form_any

(Oracle8)

Internal Character Set ID Value = 4

CONSTANT arg_type_num Used in arg_type column of def$_args table Value = 2

CONSTANT arg_type_char Used in arg_type column of def$_args table Value = 96

CONSTANT arg_type_varchar2 Used in arg_type column of def$_args table Value = 1

CONSTANT arg_type_date Used in arg_type column of def$_args table Value = 12

Trang 3

CONSTANT arg_type_rowid Used in arg_type column of def$_args table Value = 11.

CONSTANT arg_type_raw Used in arg_type column of def$_args table Value = 23

CONSTANT arg_type_blob

(Oracle8)

Used in arg_type column of def$_args table Value = 113

(Oracle8)

CONSTANT repcat_status_normal Signals normal successful completion Value = 0.0

TYPE node_list_t Table of VARCHAR2(128)

17.3.2 Basic RPCs

The simplest RPC calls use default destinations and take no parameters The basic procedure for building a parameterless deferred transaction or a deferred remote procedure call is to follow these steps:

1

Call DBMS_DEFER.TRANSACTION (optional)

2

Make one or more calls to DBMS_DEFER.CALL

3

Issue a COMMIT with DBMS_DEFER.COMMIT_WORK

The following sections describe in some detail how these procedures work Later sections describe more complex RPC calls

17.3.2.1 The DBMS_DEFER.TRANSACTION procedure

The TRANSACTION procedure allows you to specify destination sites for the ensuing call(s) to the

DBMS_DEFER.CALL procedure There are two main reasons why you might wish to identify destinations this way:

•

You might wish to override the destinations in the DBA_REPSITES data dictionary view

•

You might be making several calls to DBMS_DEFER.CALL and not wish to specify the destinations

in the nodes parameter individually each time

The TRANSACTION procedure is overloaded such that the nodes parameter is optional You can specify either,

PROCEDURE DBMS_DEFER.TRANSACTION;

or:

PROCEDURE DBMS_DEFER.TRANSACTION

(nodes IN node_list_t);

Trang 4

If specified, nodes is a PL/SQL table containing the list of nodes that should receive the RPC call If you do not specify the nodes parameter, the ensuing call(s) to DBMS_DEFER.CALL will queue the calls to

destinations in DEFDEFAULTDEST If you do specify the nodes parameter, you must populate it with the global name of target destinations

17.3.2.1.1 Exceptions

DBMS_DEFER.TRANSACTION may raise the following exceptions:

malformedcall −23304 Transaction is not properly formed, or transaction terminated

ORA−23319 −23319 Parameter value is not appropriate

ORA−23352 −23352 node_list_t contains duplicates

17.3.2.1.2 Restrictions

You can call the TRANSACTION procedure only in conjunction with DBMS_DEFER.CALL

17.3.2.1.3 Example

At the end of the DBMS_DEFER section (in the COMMIT_ WORK subsection) is an example that

incorporates the TRANSACTION procedure and the other DBMS_DEFER procedures

17.3.2.2 The DBMS_DEFER.CALL procedure

The CALL procedure queues a call to the destination specified in the DEFDEFAULTDEST data dictionary view Here is the specification:

PROCEDURE DBMS_DEFER.CALL

(schema_name IN VARCHAR2,

package_name IN VARCHAR2,

proc_name IN VARCHAR2,

arg_count IN NATURAL,

{group_name IN VARCHAR2 := ''|

nodes IN node_list_t});

Parameters are summarized in the following table

Name Description

package_name Name of the package containing the procedure that is being queued

proc_name Name of the procedure being queued

arg_count Number of parameters being passed to the procedure You must have one call to

DBMS_DEFER.<datatype>_ARG for each parameter

group_name Optional Reserved for internal use

nodes Optional List of destination nodes (global_names) where the procedure is to be executed If

nodes is not specified, destinations are determined by the list passed to DBMS_DEFER.TRANSACTION

The CALL procedure may raise the following exceptions:

Trang 5

malformedcall −23304 Number of arguments in call does not match value of arg_count

ORA−23319 −23319 The parameter is either NULL, misspelled, or not allowed

ORA−23352 −23352 The nodes list contains a duplicate

17.3.2.2.2 Restrictions

The procedures used in deferred RPC calls must be part of a package; it is not possible to queue standalone procedures

17.3.2.2.3 Example

At the end of the DBMS_DEFER section (in the COMMIT_WORK subsection) is an example that

incorporates the CALL procedure and the other DBMS_DEFER procedures

For an additional example, see the defcall.sql file on the companion disk The example lists all entries in the

deferred call queue (DEFCALL), including the originating database and the package name

17.3.2.3 The DBMS_DEFER.COMMIT_WORK procedure

The COMMIT_WORK procedure issues a COMMIT command to commit the transaction constructed by the preceding TRANSACTION and CALL procedures The specification is,

PROCEDURE DBMS_DEFER.COMMIT_WORK

(commit_work_comment IN VARCHAR2);

where commit_work_comment is a description of the transaction The comment may be up to 50 characters There are no restrictions on calling COMMIT_WORK

The COMMIT_WORK procedure may raise the following exception:

malformedcall −23304 Number of arguments in the CALL procedure does not match value arg_count; or

missing calls to the <datatype>_ARG procedure, or the TRANSACTION procedure was not called for this transaction

17.3.2.3.2 Example:

The DBMS_DEFER.TRANSACTION, CALL, <datatype>_ARG, and COMMIT_WORK procedures work together to construct a deferred transaction or deferred RPC call, as described in the following examples

17.3.2.3.3 Using DBMS_DEFER.TRANSACTION

To illustrate the way that you might use the TRANSACTION procedure, consider the following example The schema SPROCKET has a package called PriceMaint, which contains procedure TenPctIncrease This

package exists at all sites in the DEFDEFAULTDEST data dictionary view The TenPctIncrease procedure increases the wholesale and retail prices of products in our PRICES table by 10%

CREATE OR REPLACE PACKAGE PriceMaint IS

PROCEDURE TenPctIncrease;

END PriceMaint;

/

CREATE OR REPLACE PACKAGE BODY PriceMaint IS

Định dạng
Số trang	5
Dung lượng	87,61 KB