Oracle Built−in Packages- P76 ppt

7. Defining an Application Profile Contents: Getting Started with DBMS_APPLICATION_INFO DBMS_APPLICATION_INFO Interface DBMS_APPLICATION_INFO Examples The DBMS_APPLICATION_INFO package provides procedures that allow applications to "register" their current execution status with the Oracle database. Once registered, information about the status of an application can be monitored externally through several of the V$ virtual tables. DBMS_APPLICATION_INFO is used to develop applications that can be monitored in various ways, including the following: • Module usage (where do users spend their time in the application?) • Resource accounting by transaction and module • End−user tracking and resource accounting in three−tier architectures • Incremental recording of long−running process statistics When applications register themselves using DBMS_APPLICATION_INFO, DBAs and developers are able to analyze their performance and resource consumption much more closely. This facilitates better application tuning and enables more accurate usage−based cost accounting. WARNING: Oracle explicitly warns that DBMS_APPLICATION_INFO should not be used in Trusted Oracle databases. 7.1 Getting Started with DBMS_APPLICATION_INFO In Oracle 7.3, the DBMS_APPLICATION_INFO package is created when the Oracle database is installed. The dbmsutil.sql script found in the built−in packages source code directory (as described in Chapter 1, Introduction) contains the source code for this package's specification. In Oracle 8.0, the script dbmsapin.sql (also found in the source code directory) creates the package. In either case, the scripts are called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_APPLICATION_INFO for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. 7.1.1 DBMS_APPLICATION_INFO Programs Table 7.1 lists the programs available from DBMS_APPLICATION_INFO. Table 7.1: DBMS_APPLICATION_INFO Programs Name Description Use in 7. Defining an Application Profile 366 SQL? READ_CLIENT_INFO Reads client information for session No READ_MODULE Reads module and action for current session No SET_ACTION Sets action within module No SET_CLIENT_INFO Sets client information for session No SET_MODULE Sets name of module executing No SET_SESSION_LONGOPS Sets row in LONGOPS table (Oracle 8.0 only) No DBMS_APPLICATION_INFO does not declare any exceptions. 7.1.2 The V$ Virtual Tables Most of the programs in DBMS_APPLICATION_INFO modify the V$ virtual tables to register application status. Table 7.2 lists the V$ tables and columns that each program modifies. Table 7.2: V$ Tables and Columns Modified by DBMS_APPLICATION_INFO Program V$ Table.Column SET_ACTION V$SQLAREA.ACTION SET_CLIENT_INFO V$SESSION.CLIENT_INFO SET_MODULE V$SESSION.MODULE V$SQLAREA.MODULE V$SESSION.ACTION V$SQLAREA.ACTION SET_SESSION_LONGOPS V$SESSION_LONGOPS.APPLICATION_DATA_3 7.1.3 DBMS_APPLICATION_INFO Nonprogram Elements The DBMS_APPLICATION_INFO package contains a single constant: set_session_longops_nohint. This constant is defined like this: set_session_longops_nohint CONSTANT BINARY_INTEGER := −1; This constant is used as a special value for the hint parameter of the SET_SESSION_LONGOPS procedure. When this value is passed, a new row in the V$SESSION_LONGOPS virtual table is acquired for tracking long operations. (See the example in the section, "Section 7.2.6, "The DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS procedure".") 6.2 UTL_FILE: Reading and Writing Server−side Files 7.2 DBMS_APPLICATION_INFO Interface [Appendix A] What's on the Companion Disk? 7.1.2 The V$ Virtual Tables 367 Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 7.1.2 The V$ Virtual Tables 368 Chapter 7 Defining an Application Profile 7.2 DBMS_APPLICATION_INFO Interface This section describes all the programs available in the DBMS_APPLICATION_INFO package. 7.2.1 The DBMS_APPLICATION_INFO.READ_CLIENT_INFO procedure The READ_CLIENT_INFO procedure returns the currently registered client information for the session. The program header is, PROCEDURE DBMS_APPLICATION_INFO.READ_CLIENT_INFO (client_info OUT VARCHAR2); where the client_info parameter contains the client information currently registered in V$SESSION. The program does not raise any exceptions, nor does it assert a purity level with the RESTRICT_REFERENCES pragma. 7.2.1.1 Example The following function calls DBMS_APPLICATION_INFO.READ_CLIENT_INFO and returns the client information. This function is part of the register_app package discussed in "Section 7.3, "DBMS_APPLICATION_INFO Examples "" later in this chapter. FUNCTION current_client_info RETURN VARCHAR2 IS /* || calls DBMS_APPLICATION_INFO.READ_CLIENT_INFO || and returns the client info */ temp_client_info VARCHAR2(64); BEGIN SYS.DBMS_APPLICATION_INFO.READ_CLIENT_INFO (temp_client_info); RETURN temp_client_info; END current_client_info; In this example, I have fully qualified the package name with the package owner (SYS), insuring that the SYS version of the package is called. This is not normally necessary, as there is (usually) a public synonym pointing to SYS.DBMS_APPLICATION_INFO. The reason for using a fully qualified reference in this specific case is discussed in "Section 7.3.6, "Covering DBMS_APPLICATION_INFO"." 7.2.2 The DBMS_APPLICATION_INFO.READ_MODULE procedure The READ_MODULE procedure returns the currently registered module and action names for the session. Here's the program header: 369 PROCEDURE DBMS_APPLICATION_INFO.READ_MODULE (module_name OUT VARCHAR2 ,action_name OUT VARCHAR2); Parameters are summarized in the following table. Parameter Description module_name Name of the module currently registered in V$SESSION action_name Name of the action currently registered in V$SESSION The READ_MODULE procedure does not raise any exceptions, nor does it assert a purity level with the RESTRICT_REFERENCES pragma. 7.2.2.1 Example The following function calls DBMS_APPLICATION_INFO.READ_MODULE and returns the value of the current action. This function is part of the register_app package discussed in "Section 7.3." FUNCTION current_action RETURN VARCHAR2 IS /* || calls DBMS_APPLICATION_INFO.READ_MODULE || and returns the action name */ temp_module_name VARCHAR2(64); temp_action_name VARCHAR2(64); BEGIN SYS.DBMS_APPLICATION_INFO.READ_MODULE (temp_module_name, temp_action_name); RETURN temp_action_name; END current_action; See the section "Section 7.3.6" for an explanation of why the procedure call is qualified by SYS, the package owner's name. 7.2.3 The DBMS_APPLICATION_INFO.SET_ACTION procedure The SET_ACTION procedure is used to set, or register, the current transaction or logical unit of work currently executing within the module. The registered action name appears in the ACTION column of the V$SESSION and V$SQLAREA virtual tables. The program header is, PROCEDURE DBMS_APPLICATION_INFO.SET_ACTION (action_name IN VARCHAR2); where the action_name parameter provides the name of the action to register into V$SESSION. The SET_ACTION procedure does not raise any exceptions. 7.2.3.1 Restrictions Note the following restrictions on calling SET_ACTION: • The action_name parameter is limited to 32 bytes. Longer values will be truncated to this maximum size. • [Appendix A] What's on the Companion Disk? 7.2.2 The DBMS_APPLICATION_INFO.READ_MODULE procedure 370 . accounting. WARNING: Oracle explicitly warns that DBMS_APPLICATION_INFO should not be used in Trusted Oracle databases. 7.1 Getting Started with DBMS_APPLICATION_INFO In Oracle 7.3, the DBMS_APPLICATION_INFO. Oracle 7.3, the DBMS_APPLICATION_INFO package is created when the Oracle database is installed. The dbmsutil.sql script found in the built−in packages source code directory (as described in Chapter. procedures that allow applications to "register" their current execution status with the Oracle database. Once registered, information about the status of an application can be monitored