Oracle Built−in Packages- P160 pot

Chapter 17 Deferred Transactions and 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 Name Description Use in SQL? CALL Defines a remote procedure call No 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 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 Type/Name Description 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. [Appendix A] What's on the Companion Disk? 17.3.1 Getting Started with DBMS_DEFER 787 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. CONSTANT arg_type_blob (Oracle8) Used in arg_type column of def$_args table. Value = 112. CONSTANT arg_type_blob (Oracle8) Used in arg_type column of def$_args table. Value = 114. CONSTANT arg_type_blob (Oracle8) Used in arg_type column of def$_args table. Value = 115. 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); [Appendix A] What's on the Companion Disk? 17.3.2 Basic RPCs 788 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: Name Number Description 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. 17.3.2.2.1 Exceptions The CALL procedure may raise the following exceptions: Name Number Description [Appendix A] What's on the Companion Disk? 17.3.2 Basic RPCs 789 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. 17.3.2.3.1 Exceptions The COMMIT_WORK procedure may raise the following exception: Name Number Description 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 [Appendix A] What's on the Companion Disk? 17.3.2 Basic RPCs 790 . arg_type_blob (Oracle8 ) Used in arg_type column of def$_args table. Value = 113. CONSTANT arg_type_blob (Oracle8 ) Used in arg_type column of def$_args table. Value = 112. CONSTANT arg_type_blob (Oracle8 ) Used. Description 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 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