Oracle Built−in Packages- P161 ppsx

In this case, we issue the TRANSACTION call without parameters: CREATE OR REPLACE PROCEDURE TenPctPriceHike IS BEGIN DBMS_DEFER.TRANSACTION; DBMS_DEFER.CALL schema_name => 'SPROCKET',

PROCEDURE TenPctIncrease IS

BEGIN

UPDATE prices

SET price_wholesale = price_wholesale * 1.10,

price_retail = price_retail * 1.10;

END TenPctIncrease;

END PriceMaint;

/

Now, suppose that we wish to make a 10% price increase at all of our locations (i.e., all locations in the DEFDEFAULTDEST data dictionary view) We could create a procedure that queues a call to

PriceMaint.TenPctIncrease to all of these sites In this case, we issue the TRANSACTION call without parameters:

CREATE OR REPLACE PROCEDURE TenPctPriceHike IS

BEGIN

DBMS_DEFER.TRANSACTION;

DBMS_DEFER.CALL( schema_name => 'SPROCKET',

package_name => 'PRICEMAINT',

proc_name => 'TENPCTINCREASE'

arg_count => 0 );

DBMS_DEFER.COMMIT_WORK(commit_work_comment=>'No nodes or args needed'); END;

Because the nodes parameter isn't specified in either the call to TRANSACTION or the call to CALL, Oracle resolves the destinations by using all sites in the DEFDEFAULTDEST data dictionary view

Here is how you might use the TenPctPriceHike Procedure

Confirm the default destinations:

SQL> SELECT * FROM defdefaultdest;

DBLINK

−−−−−−−−−−−−−−−−−−−−

D7NY.BIGWHEEL.COM

D7OH.BIGWHEEL.COM

D7OR.BIGWHEEL.COM

D7WA.BIGWHEEL.COM

D7TX.BIGWHEEL.COM

5 rows selected.

Now use TenPctPriceHike to queue the RPC to all five destinations:

SQL> EXECUTE TenPctPriceHike

PL/SQL procedure successfully completed.

Figure 17−1 graphically illustrates how a deferred call is queued

Figure 17.1: Queueing up a deferred call to TenPctIncrease

Now check the entries in DEFTRAN (this call was made from D7CA BIGWHEEL.COM):

SQL> select * from deftrandest;

DEFERRED_TRAN_ID DEFERRED_TRAN_DB DBLINK

−−−−−−−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−

2.44.13 D7CA.BIGWHEEL.COM D7NY.BIGWHEEL.COM

2.44.13 D7CA.BIGWHEEL.COM D7OH.BIGWHEEL.COM

2.44.13 D7CA.BIGWHEEL.COM D7OR.BIGWHEEL.COM

2.44.13 D7CA.BIGWHEEL.COM D7WA.BIGWHEEL.COM

2.44.13 D7CA.BIGWHEEL.COM D7TX.BIGWHEEL.COM

5 rows selected.

For an additional example, see the deftdest.sql file on the companion disk The example queries the

DEFTRANDEST data dictionary view and lists destination databases for deferred RPC calls

NOTE: Procedure TenPctPriceHike queues the deferred RPC only if the owner of the

procedure has EXECUTE privileges on DBMS_DEFER

17.3.2.3.4 Specifying nondefault destinations with TRANSACTION

What if we wanted to apply the 10% price hike only to our West Coast sites (i.e., D7CA.BIGWHEEL.COM, D7OR.BIGWHEEL.COM, and D7WA.BIGWHEEL.COM)? The following example does just that by

specifying the nodes parameter in the TRANSACTION procedure:

CREATE OR REPLACE PROCEDURE TenPctPriceHikeWest IS

vNodes DBMS_DEFER.NODE_LIST_T;

BEGIN

vNodes(1) := 'D7CA.BIGWHEEL.COM';

vNodes(2) := 'D7OR.BIGWHEEL.COM';

vNodes(3) := 'D7WA.BIGWHEEL.COM';

DBMS_DEFER.TRANSACTION( vNodes );

DBMS_DEFER.CALL( schema_name => 'SPROCKET',

package_name => 'PRICEMAINT',

proc_name => 'TENPCTINCREASE'

arg_count => 0 );

DBMS_DEFER.COMMIT_WORK(commit_work_comment=>'West Coast Price Hike');

END;

17.3.2.3.5 Committing deferred RPC calls with COMMIT_WORK

Notice that the last two examples include a call to DBMS_DEFER.COMMIT_WORK All deferred RPCs

queued with the CALL procedure must be followed by a call to COMMIT_WORK; an explicit COMMIT or

COMMIT WORK is not sufficient The reason for this restriction is that COMMIT_WORK not only commits the transaction, but also updates the commit_comment and delivery_order field in the DEFTRANS data dictionary view The commit_comment is updated with the optional string passed to COMMIT_WORK, and the delivery_order field is updated with the transaction's SCN

Remember that the TRANSACTION procedure is not required to queue deferred calls It is used only to specify destinations The real power and flexibility of deferred transactions is in the CALL procedure

For an additional example, see the defcdest.sql file on the companion disk The example queries the

DEFCALLDEST data dictionary view and lists the destination databases of all calls in the deferred call queue

17.3.3 Parameterized RPCs

The preceding sections describe the simple version of building deferred RPCs with the DBMS_DEFER package We saw in those sections that the DBMS_DEFER.CALL procedure is the program that actually queues deferred RPCs Most of the examples we have seen so far use it in its simplest incarnation, without the nodes parameter and with an arg_count parameter of 0 This is fine when making deferred calls to procedures that take no parameters, and when the default destinations are acceptable, but sooner or later you will want to defer calls to procedures that require parameters, and you will want to specify the destinations for each call individually The steps to accomplish these more complex operations follow:

1

Specify the destination nodes, either with DBMS_CALL.TRANSACTION or by supplying the nodes parameter to DBMS_DEFER.CALL

2

Execute DBMS_DEFER.CALL, supplying the schema name, package name, procedure name,

number of arguments to the procedure, and (if you do not use DBMS_CALL.TRANSACTION) the nodes parameter

3

Call DBMS_DEFER.<datatype>_arg arg_count times, where arg_count is the value passed to

DBMS_DEFER.CALL The order in which you call DBMS_DEFER.<datatype>_arg must be the same order as the parameters are listed in the procedure definition

4

Call DBMS_DEFER.COMMIT_WORK with an optional comment

17.3.3.1 The DBMS_DEFER.<datatype>_ARG procedure

This procedure specifies an argument for a deferred call The argument is of the datatype specified in

<datatype> Here is the specification:

PROCEDURE DBMS_DEFER.<datatype>ARG (arg IN <datatype>

specifications differ for different datatypes, depending on whether you are using Oracle7 or Oracle8

<datatype> can be one of the following:

NUMBER

DATE

VARCHAR2

CHAR

ROWID

RAW

NVARCHAR2 (Oracle8 only)

ANY_VARCHAR2 (Oracle8 only)

NCHAR (Oracle8 only)

ANY_CHAR (Oracle8 only)

BLOB (Oracle8 only)

CLOB (Oracle8 only)

ANY_CLOB (Oracle8 only)

NCLOB (Oracle8 only)

The arg parameter is the value to pass to the parameter of the same datatype in the procedure previously queued via DBMS_DEFER.CALL

The various alternatives are listed here

The following specifications apply to both Oracle7 and Oracle8:

PROCEDURE NUMBER_ARG (arg IN NUMBER);

PROCEDURE DATE_ARG (arg IN DATE);

PROCEDURE VARCHAR2_ARG (arg IN VARCHAR2);

PROCEDURE CHAR_ARG (arg IN CHAR);

PROCEDURE ROWID_ARG (arg IN ROWID);

PROCEDURE RAW_ARG (arg IN raw);

These specifications apply only to Oracle8:

PROCEDURE NVARCHAR2_ARG (arg IN NVARCHAR2);

PROCEDURE ANY_VARCHAR2_ARG (arg IN VARCHAR2 CHARACTER SET ANY_CS);

PROCEDURE NCHAR_ARG (arg IN NCHAR);

PROCEDURE ANY_CHAR_ARG (arg IN CHAR CHARACTER SET ANY_CS);

PROCEDURE BLOB_ARG (arg IN BLOB);

PROCEDURE CLOB_ARG (arg IN CLOB);

PROCEDURE ANY_CLOB_ARG (arg IN CLOB CHARACTER SET ANY_CS);

PROCEDURE NCLOB_ARG (arg IN NCLOB);

17.3.3.1.1 Exceptions

This procedure may raise the following exception:

Name Number Description

paramlen_num −23323 Parameter is too long

17.3.3.1.2 Example

The following scenario describes how to perform the steps required to construct a deferred RPC that takes parameters

Suppose that we have a PRODUCTS table and a procedure that adds new products to it, as follows:

SQL> desc products

Name Null? Type

−−−−−−−−−−−−−−−−−−− −−−−−−−− −−−−

PRODUCT_ID NOT NULL NUMBER(9)

PRODUCT_TYPE NOT NULL NUMBER(6)

CATALOG_ID NOT NULL VARCHAR2(15)

DESCRIPTION NOT NULL VARCHAR2(30)

REV_LEVEL NOT NULL VARCHAR2(15)

PRODUCTION_DATE NOT NULL DATE

PRODUCTION_STATUS NOT NULL VARCHAR2(10)

AUDIT_DATE NOT NULL DATE

AUDIT_USER NOT NULL VARCHAR2(30)

GLOBAL_NAME NOT NULL VARCHAR2(20)

Procedure ProductMaint.AddProduct populates this table We will queue deferred calls to the this procedure

CREATE OR REPLACE PACKAGE ProductMaint IS

PROCEDURE AddProduct(product_type_ININ NUMBER,

catalog_id_IN IN VARCHAR2,

description_IN IN VARCHAR2,

rev_level_IN IN VARCHAR2,

production_date_ININ DATE,

product_status_ININ VARCHAR);

END ProductMaint;

/

CREATE OR REPLACE PACKAGE BODY ProductMaint IS

PROCEDURE AddProduct(product_type_ININ NUMBER,

catalog_id_IN IN VARCHAR2,

description_IN IN VARCHAR2,

rev_level_IN IN VARCHAR2,

production_date_IN IN DATE,

product_status_IN IN VARCHAR) IS

BEGIN

INSERT INTO products (product_id,

product_type,

catalog_id,

description,

rev_level,

production_date,

production_status,

audit_date,

audit_user,

global_name )

VALUES (seq_products.nextval,

product_type_IN,

catalog_id_IN,

description_IN,

rev_level_IN,

production_date_IN,

product_status_IN,

SYSDATE,

USER,

DBMS_REPUTIL.GLOBAL_NAME);

END AddProduct;

END ProductMaint;

Since the procedure ProductMaint.AddProduct accepts parameters, we must supply values for these

parameters when building a deferred call The following procedure does just that:

CREATE OR REPLACE PROCEDURE qAddProduct IS

vNodes DBMS_DEFER.NODE_LIST_T;

BEGIN