MINI MINI MANI MO
Rem
Rem $Header: rdbms/admin/dbmssess.sql /main/16 2017/05/17 16:39:14 rankalik Exp $
Rem
Rem dbmssess.sql
Rem
Rem Copyright (c) 2005, 2017, Oracle and/or its affiliates.
Rem All rights reserved.
Rem
Rem NAME
Rem dbmssess.sql - DBMS_SESSION
Rem
Rem DESCRIPTION
Rem DBMS_SESSION - Package to control the current session in a programmatic
Rem manner. Note that in some cases, there are analogous
Rem alter session commands.
Rem
Rem NOTES
Rem DBMS_SESSION - this package was originally located in dbmsutil.sql
Rem
Rem
Rem BEGIN SQL_FILE_METADATA
Rem SQL_SOURCE_FILE: rdbms/admin/dbmssess.sql
Rem SQL_SHIPPED_FILE: rdbms/admin/dbmssess.sql
Rem SQL_PHASE: DBMSSESS
Rem SQL_STARTUP_MODE: NORMAL
Rem SQL_IGNORABLE_ERRORS: NONE
Rem SQL_CALLING_FILE: rdbms/admin/catpstrt.sql
Rem END SQL_FILE_METADATA
Rem
Rem MODIFIED (MM/DD/YY)
Rem orortega 04/04/17 - Bug 23557076: Add sleep procedure
Rem rankalik 03/07/17 - Bug25536381: Adding dbms_sess proc for plan maint
Rem dalpern 06/08/15 - DBMS_SESSION.USE_DEFAULT_EDITION_ALWAYS
Rem lvbcheng 07/07/14 - deferred alter session set current_schema
Rem surman 12/29/13 - 13922626: Update SQL metadata
Rem jooskim 12/26/12 - XbranchMerge jooskim_bug-15891599 from
Rem st_rdbms_12.1.0.1
Rem jooskim 12/11/12 - bug 15891599: remove dbms_session.cancel_sql
Rem surman 03/27/12 - 13615447: Add SQL patching tags
Rem jooskim 08/24/11 - proj 32499: pqq usability
Rem jmuller 06/06/11 - Fix bug 11664193: support
Rem package_memory_utilization > 2G
Rem mahrajag 11/19/10 - Fix for bug 10305078.
Rem achoi 12/16/08 - bug7576540
Rem dbronnik 02/13/08 - ER 6805576: psd_get_package_memory_utilization
Rem rcolle 04/16/07 - change session_trace_enable to accept plan_stat
Rem dalpern 10/23/06 - dbms_session.set_edition
Rem achoi 10/28/05 - performance related comment
Rem lvbcheng 08/17/05 - lvbcheng_split_dbms_util
Rem lvbcheng 07/29/05 - moved here from dbmsutil.sql
Rem gviswana 10/24/01 - dbms_ddl, dbms_session: AUTHID CURRENT_USER
Rem kmuthukk 03/19/01 - add dbms_session.modify_package_state
Rem
@@?/rdbms/admin/sqlsessstart.sql
Rem ********************************************************************
Rem THESE PACKAGES MUST NOT BE MODIFIED BY THE CUSTOMER. DOING SO
Rem COULD CAUSE INTERNAL ERRORS AND SECURITY VIOLATIONS IN THE
Rem RDBMS. SPECIFICALLY, THE PSD* AND EXECUTE_SQL ROUTINES MUST NOT BE
Rem CALLED DIRECTLY BY ANY CLIENT AND MUST REMAIN PRIVATE TO THE PACKAGE BODY.
Rem ********************************************************************
create or replace package dbms_session AUTHID CURRENT_USER is
------------
-- OVERVIEW
--
-- This package provides access to SQL "alter session" statements, and
-- other session information from, stored procedures.
----------------------------
-- PROCEDURES AND FUNCTIONS
--
procedure set_role(role_cmd varchar2);
-- Equivalent to SQL "SET ROLE ...".
-- Input arguments:
-- role_cmd
-- This text is appended to "set role " and then executed as SQL.
procedure set_sql_trace(sql_trace boolean);
-- Equivalent to SQL "ALTER SESSION SET SQL_TRACE ..."
-- Note:
-- Using "execute immediate 'alter session'" has better performance
-- than using dbms_session.set_sql_trace.
-- Input arguments:
-- sql_trace
-- TRUE or FALSE. Turns tracing on or off.
procedure set_nls(param varchar2, value varchar2);
-- Equivalent to SQL "ALTER SESSION SET <nls_parameter> = <value>"
-- Note:
-- Using "execute immediate 'alter session'" has better performance
-- than using dbms_session.set_nls. Further, when setting multiple
-- parameters, EXEC IMMEDIATE allows user to set all of them in one
-- statement, which is much more efficient than calling
-- dbms_session.set_nls in multiple statements.
-- Input arguments:
-- param
-- The NLS parameter. The parameter name must begin with 'NLS'.
-- value
-- The value to set the parameter to. If the parameter is a
-- text literal then it will need embedded single-quotes. For
-- example "set_nls('nls_date_format','''DD-MON-YY''')"
procedure close_database_link(dblink varchar2);
-- Equivalent to SQL "ALTER SESSION CLOSE DATABASE LINK <name>"
-- Input arguments:
-- name
-- The name of the database link to close.
procedure reset_package;
-- Deinstantiate all packages in this session. In other words, free
-- all package state. This is the situation at the beginning of
-- a session.
--------------------------------------------------------------------
-- action_flags (bit flags) for MODIFY_PACKAGE_STATE procedure ---
--------------------------------------------------------------------
FREE_ALL_RESOURCES constant PLS_INTEGER := 1;
REINITIALIZE constant PLS_INTEGER := 2;
procedure modify_package_state(action_flags IN PLS_INTEGER);
-- The MODIFY_PACKAGE_STATE procedure can be used to perform
-- various actions (as specified by the 'action_flags' parameter)
-- on the session state of ALL PL/SQL program units active in the
-- session. This takes effect only after the PL/SQL call that
-- made the current invokation finishes running.
--
-- Parameter(s):
-- action_flags:
-- Determines what action is taken on the program units.
-- The following action_flags are supported:
--
-- * DBMS_SESSION.FREE_ALL_RESOURCES:
-- This frees all the memory associated with each of the
-- previously run PL/SQL programs from the session, and,
-- consequently, clears the current values of any package
-- globals and closes any cached cursors. On subsequent use,
-- the PL/SQL program units are re-instantiated and package
-- globals are reinitialized. This is essentially the
-- same as DBMS_SESSION.RESET_PACKAGE() interface.
--
-- * DBMS_SESSION.REINITIALIZE:
-- In terms of program semantics, the DBMS_SESSION.REINITIALIZE
-- flag is similar to the DBMS_SESSION.FREE_ALL_RESOURCES flag
-- in that both have the effect of re-initializing all packages.
--
-- However, DBMS_SESSION.REINITIALIZE should exhibit much better
-- performance than the DBMS_SESSION.FREE_ALL_RESOURCES option
-- because:
--
-- - packages are reinitialized without actually being freed
-- and recreated from scratch. Instead the package memory gets
-- reused.
--
-- - any open cursors are closed, semantically speaking. However,
-- the cursor resource is not actually freed. It is simply
-- returned to the PL/SQL cursor cache. And more importantly,
-- the cursor cache is not flushed. Hence, cursors
-- corresponding to frequently accessed static SQL in PL/SQL
-- will remain cached in the PL/SQL cursor cache and the
-- application will not incur the overhead of opening, parsing
-- and closing a new cursor for those statements on subsequent use.
--
-- - the session memory for PL/SQL modules without global state
-- (such as types, stored-procedures) will not be freed and
-- recreated.
--
--
-- Usage Example:
-- begin
-- dbms_session.modify_package_state(DBMS_SESSION.REINITIALIZE);
-- end;
--
function unique_session_id return varchar2;
pragma restrict_references(unique_session_id,WNDS,RNDS,WNPS);
-- Return an identifier that is unique for all sessions currently
-- connected to this database. Multiple calls to this function
-- during the same session will always return the same result.
-- Output arguments:
-- unique_session_id
-- can return up to 24 bytes.
function is_role_enabled(rolename varchar2) return boolean;
-- Determine if the named role is enabled for this session.
-- Input arguments:
-- rolename
-- Name of the role.
-- Output arguments:
-- is_role_enabled
-- TRUE or FALSE depending on whether the role is enabled.
function is_session_alive(uniqueid varchar2) return boolean;
-- Determine if the specified session is alive.
-- Input arguments:
-- uniqueid
-- Uniqueid of the session.
-- Output arguments:
-- is_session_alive
-- TRUE or FALSE depending on whether the session is alive.
procedure set_close_cached_open_cursors(close_cursors boolean);
-- Equivalent to SQL "ALTER SESSION SET CLOSE_CACHED_OPEN_CURSORS ..."
-- Input arguments:
-- close_cursors
-- TRUE or FALSE. Turns close_cached_open_cursors on or off.
procedure free_unused_user_memory;
-- Procedure for users to reclaim unused memory after performing operations
-- requiring large amounts of memory (where large is >100K). Note that
-- this procedure should only be used in cases where memory is at a
-- premium.
--
-- Examples operations using lots of memory are:
--
-- o large sorts where entire sort_area_size is used and
-- sort_area_size is hundreds of KB
-- o compiling large PL/SQL packages/procedures/functions
-- o storing hundreds of KB of data within PL/SQL indexed tables
--
-- One can monitor user memory by tracking the statistics
-- "session uga memory" and "session pga memory" in the
-- v$sesstat/v$statname fixed views. Monitoring these statistics will
-- also show how much memory this procedure has freed.
--
-- The behavior of this procedure depends upon the configuration of the
-- server operating on behalf of the client:
--
-- o dedicated server - returns unused PGA memory and session memory
-- to the OS (session memory is allocated from the PGA in this
-- configuration)
-- o MTS server - returns unused session memory to the
-- shared_pool (session memory is allocated from the shared_pool
-- in this configuration)
--
-- In order to free memory using this procedure, the memory must
-- not be in use.
--
-- Once an operation allocates memory, only the same type of operation can
-- reuse the allocated memory. For example, once memory is allocated
-- for sort, even if the sort is complete and the memory is no longer
-- in use, only another sort can reuse the sort-allocated memory. For
-- both sort and compilation, after the operation is complete, the memory
-- is no longer in use and the user can invoke this procedure to free the
-- unused memory.
--
-- An indexed table implicitly allocates memory to store values assigned
-- to the indexed table's elements. Thus, the more elements in an indexed
-- table, the more memory the RDBMS allocates to the indexed table. As
-- long as there are elements within the indexed table, the memory
-- associated with an indexed table is in use.
--
-- The scope of indexed tables determines how long their memory is in use.
-- Indexed tables declared globally are indexed tables declared in packages
-- or package bodies. They allocate memory from session memory. For an
-- indexed table declared globally, the memory will remain in use
-- for the lifetime of a user's login (lifetime of a user's session),
-- and is freed after the user disconnects from ORACLE.
--
-- Indexed tables declared locally are indexed tables declared within
-- functions, procedures, or anonymous blocks. These indexed tables
-- allocate memory from PGA memory. For an indexed table declared
-- locally, the memory will remain in use for as long as the user is still
-- executing the procedure, function, or anonymous block in which the
-- indexed table is declared. After the procedure, function, or anonymous
-- block is finished executing, the memory is then available for other
-- locally declared indexed tables to use (i.e., the memory is no longer
-- in use).
--
-- Assigning an uninitialized, "empty," indexed table to an existing index
-- table is a method to explicitly re-initialize the indexed table and the
-- memory associated with the indexed table. After this operation,
-- the memory associated with the indexed table will no longer be in use,
-- making it available to be freed by calling this procedure. This method
-- is particularly useful on indexed tables declared globally which can grow
-- during the lifetime of a user's session, as long as the user no
-- longer needs the contents of the indexed table.
--
-- The memory rules associated with an indexed table's scope still apply;
-- this method and this procedure, however, allow users to
-- intervene and to explictly free the memory associated with an
-- indexed table.
--
-- The PL/SQL fragment below illustrates the method and the use
-- of procedure free_unused_user_memory.
--
-- create package foobar
-- type number_idx_tbl is table of number indexed by binary_integer;
--
-- store1_table number_idx_tbl; -- PL/SQL indexed table
-- store2_table number_idx_tbl; -- PL/SQL indexed table
-- store3_table number_idx_tbl; -- PL/SQL indexed table
-- ...
-- end; -- end of foobar
--
-- declare
-- ...
-- empty_table number_idx_tbl; -- uninitialized ("empty") version
--
-- begin
-- for i in 1..1000000 loop
-- store1_table(i) := i; -- load data
-- end loop;
-- ...
-- store1_table := empty_table; -- "truncate" the indexed table
-- ...
-- -
-- dbms_session.free_unused_user_memory; -- give memory back to system
--
-- store1_table(1) := 100; -- index tables still declared;
-- store2_table(2) := 200; -- but truncated.
-- ...
-- end;
--
-- Performance Implication:
-- This routine should be used infrequently and judiciously.
--
-- Input arguments:
-- n/a
procedure set_context(namespace varchar2, attribute varchar2, value varchar2,
username varchar2 default null,
client_id varchar2 default null);
-- Input arguments:
-- namespace
-- Name of the namespace to use for the application context
-- attribute
-- Name of the attribute to be set
-- value
-- Value to be set
-- username
-- username attribute for application context . default value is null.
-- client_id
-- client identifier that identifies a user session for which we need
-- to set this context.
--
--
procedure set_identifier(client_id varchar2);
-- Input parameters:
-- client_id
-- client identifier being set for this session .
--
--
procedure clear_context(namespace varchar2, client_id varchar2 default null,
attribute varchar2 default null);
-- Input parameters:
-- namespace
-- namespace where the application context is to be cleared
-- client_id
-- all ns contexts associated with this client id are cleared.
-- attribute
-- attribute to clear .
procedure clear_all_context(namespace varchar2);
--
-- Input parameters:
-- namespace
-- namespace where the application context is to be cleared
--
procedure clear_identifier;
-- Input parameters:
-- none
--
TYPE AppCtxRecTyp IS RECORD ( namespace varchar2(30), attribute varchar2(30),
value varchar2(4000));
TYPE AppCtxTabTyp IS TABLE OF AppCtxRecTyp INDEX BY BINARY_INTEGER;
procedure list_context(list OUT AppCtxTabTyp, lsize OUT number);
-- Input arguments:
-- list
-- buffer to store a list of application context set in current
-- session
-- Output arguments:
-- list
-- contains a list of of (namespace,attribute,values) set in current
-- session
-- size
-- returns the number of entries in the buffer returned
procedure switch_current_consumer_group(new_consumer_group IN VARCHAR2,
old_consumer_group OUT VARCHAR2,
initial_group_on_error IN BOOLEAN);
-- Input arguments:
-- new_consumer_group
-- name of consumer group to switch to
-- old_consumer_group
-- name of the consumer group just switched out from
-- initial_group_on_error
-- If TRUE, sets the current consumer group of the invoker to his/her
-- initial consumer group in the event of an error.
--
procedure session_trace_enable(waits IN BOOLEAN DEFAULT TRUE,
binds IN BOOLEAN DEFAULT FALSE,
plan_stat IN VARCHAR2 DEFAULT NULL);
-- Enables SQL trace for the session. Supports waits and binds
-- specifications, which makes it more general than set_sql_trace. Using
-- this procedure is a preferred way in the future.
-- Input parameters:
-- waits
-- If TRUE, wait information will be present in the trace
-- binds
-- If TRUE, bind information will be present in the trace
-- plan_stat
-- Frequency at which we dump row source statistics.
-- Value should be 'never', 'first_execution'
-- (equivalent to NULL) or 'all_executions'.
procedure session_trace_disable;
-- Disables SQL trace for the session, which has been enabled by the
-- session_trace_enable procedure
-- Input parameters:
-- none
--
procedure set_edition_deferred(edition varchar2);
-- Requests a switch to the specified edition. The switch takes
-- effect at the end of the current client call.
--
-- Input parameters:
-- edition
-- The name of the edition to switch to. The contents of the
-- string are processed as a SQL identifier; double-quotes must
-- surround the remainder of the string if special characters or
-- lower case characters are present in the edition's actual
-- name, and if double-quotes are not used the contents will be
-- uppercased. The caller must have USE privilege on the named
-- edition.
type lname_array IS table of VARCHAR2(4000) index by BINARY_INTEGER;
type integer_array IS table of BINARY_INTEGER index by BINARY_INTEGER;
procedure get_package_memory_utilization(
owner_names OUT NOCOPY lname_array,
unit_names OUT NOCOPY lname_array,
unit_types OUT NOCOPY integer_array,
used_amounts OUT NOCOPY integer_array,
free_amounts OUT NOCOPY integer_array);
-- Supported info_kinds:
used_memory CONSTANT BINARY_INTEGER := 1;
free_memory CONSTANT BINARY_INTEGER := 2;
type big_integer_array IS table of INTEGER index by BINARY_INTEGER;
type big_integer_matrix IS table of big_integer_array
index by BINARY_INTEGER;
procedure get_package_memory_utilization(
desired_info IN integer_array,
owner_names OUT NOCOPY lname_array,
unit_names OUT NOCOPY lname_array,
unit_types OUT NOCOPY integer_array,
amounts OUT NOCOPY big_integer_matrix);
-- These procedures describe static package memory usage.
-- The output collections describe memory usage
-- in each instantiated package. Each package is
-- described by its owner name, package name, type,
-- and memory statistics.
-- The amount of unused memory is greater than zero
-- because of memory fragmentation and also because
-- once used free memory chunks initially go to a free
-- list owned by the package memory heap. They are
-- released back to the parent heap only when
-- free_unused_user_memory is invoked.
--
-- Two overloadings are provided.
-- The first measures memory usage up to 2**31-1 (the maximum for
-- BINARY_INTEGER). It only measures used and free memory.
-- The second measures up to 10**38 (the maximum for INTEGER (which is
-- NUMBER(38,0).) This overloading takes an IN 'desired_info' array
-- specifying which kinds of information are desired. Currently the options
-- are the same as for the first overloading; but in the future, additional
-- kinds of information may be supported. The OUT 'amounts' array is indexed
-- by info_kind values specified in 'desired_info' to yield arrays which are
-- indexed in turn by the same integer used to index the other OUT arrays to
-- yield the requested kinds of information.
procedure use_default_edition_deferred;
-- This procedure disassociates the session from an edition. The reset
-- takes effect at the end of the current client call. Following this
-- call and before the next top level call, no edition will be in use
-- by the session. The session will use the reigning database default
-- edition on its next operation.
-- Input parameters:
-- none
procedure use_default_edition_always(mode_on IN BOOLEAN DEFAULT TRUE);
-- This procedure turns on/off a mode that disassociates the session from an
-- edition at the end of each and every client call. Following each call and
-- before the next top level call, no edition will be in use by the
-- session. The session will use the reigning database default edition on its
-- next operation.
--
-- A choice of session edition that might otherwise occur due to use of ALTER
-- SESSION SET EDITION, set_edition_deferred, use_default_edition_deferred, or
-- the edition-choosing aspect of ALTER SESSION SET CONTAINER will be
-- overridden by this mode. Turn this mode off before invoking those
-- mechanisms if it is desired that they are to have impact.
--
-- Input parameters:
-- MODE_ON: TRUE to turn on this mode, FALSE to turn off this mode.
procedure set_current_schema_deferred(schema_name varchar2);
/*
Procedure: set_current_schema_deferred
Function to set the current schema of the session to a schema specified in
the call. The switch takes effect at the end of the current client call.
Parameters:
target_schema (IN) - the schema to which to set the current session. The
contents of the string are processed as a SQL identifier; double-quotes
must surround the remainder of the string if special characters or lower
case characters are present in the schema's actual name, and if
double-quotes are not used, the contents will be uppercased.
Note:
- The specified user must be a valid user in the database.
- If SET_CURRENT_SCHEMA_DEFERRED is invoked multiple times during the
same call, the schema specified in the last successful invocation is
the new current schema.
- If an invocation of SET_CURRENT_SCHEMA_DEFERRED results in an error,
the invocation is a no-op.
*/
procedure sleep(seconds in number);
-- Suspend the session for the specified period of time.
-- Input parameters:
-- seconds
-- In seconds, currently the maximum resolution is in hundreths of
-- a second (e.g., 1.00, 1.01, .99 are all legal and distinct values).
-- This will be preferable method than dbms_lock.sleep because it avoids
-- having to grant dbms_lock permissions and exposing more sensitive methods.
SQL_TEST CONSTANT NUMBER := 0;
PING_TEST CONSTANT NUMBER := 1;
ENDREQUEST_TEST CONSTANT NUMBER := 2;
-- Connection tests are used by application servers and applications to check
-- the health of a database connection before using it.
-- Most often, connections tests are used when borrowing and returning
-- connections from a connection pool. These are safe places to drain
-- connections for planned maintenance.
--
-- Three constants describe the safe place to drain a connection.
-- SQL_TEST - The connection test described is a SQL statement that is used
-- by the application to test the health of a connection.
-- PING_TEST - The connection test is a ping-based test including OCIPING for
-- OCI and isVALID for JDBC.
-- END_REQUEST - End request indicates the end of work and safe point to
-- drain the connection.
procedure add_sql_connection_test(connection_test in varchar2,
service_name in varchar2 DEFAULT NULL);
-- Procedure : add_sql_connection_test
-- This procedure adds a new connection test that will be used by the
-- database when draining sessions. Only SQL tests can be added.
--
-- Parameters:
-- connection_test - SQL rule to be added
-- service_name - Optional service name qualifier.
--
-- Notes:
-- The test applies to the level connected - CDB or PDB.
procedure delete_sql_connection_test(connection_test in varchar2,
service_name in varchar2 DEFAULT NULL);
-- Procedure : delete_sql_connection_test
-- This procedure deletes a connection test that is no longer needed for
-- planned draining. If you are not certain if a test should be deleted, you
-- can disable the test using DISABLE_CONNECTION_TEST.
--
-- Parameters:
-- connection_test - SQL rule to be deleted.
-- service_name - Optional service name qualifier.
--
-- Notes:
-- Only custom SQL tests can be deleted.
procedure disable_connection_test(connection_test_type IN number,
connection_test IN varchar2 DEFAULT NULL,
service_name IN varchar2 DEFAULT NULL);
-- Procedure : disable_connection_test
-- This procedure disables usage of a connection test during draining of
-- sessions. The TYPE defines whether this is a SQL test, END REQUEST test or
-- PING test
--
-- Parameters:
-- connection_test_type - Is a required field that indicates the type of
-- connection to be disabled. It can contain the
-- following values -
-- dbms_session.SQL_TEST, dbms_session.PING_TEST,
-- dbms_session.ENDREQUEST_TEST.
-- connection_test - SQL to be disabled when connection test being
-- disabled of the type SQL_TEST. Can be NULL for
-- other connection tests.
-- service_name - Optional service name qualifier.
--
-- Notes:
-- The disable applies to the level of that test (CDB or PDB or service) and
-- persists across restarts.
procedure enable_connection_test(connection_test_type IN number,
connection_test IN varchar2 DEFAULT NULL,
service_name IN varchar2 DEFAULT NULL);
-- Procedure : enable_connection_test
-- This procedure enables usage of a connection test during draining of
-- sessions.
--
-- Parameters:
-- connection_test_type - Is a required field that indicates the type of
-- connection to be disabled. It can contain the
-- following values -
-- dbms_session.SQL_TEST, dbms_session.PING_TEST,
-- dbms_session.ENDREQUEST_TEST.
-- connection_test - SQL to be disabled when connection test being
-- disabled of the type SQL_TEST. Can be NULL for
-- other connection tests.
-- service_name - Optional service name qualifier.
--
-- Notes:
-- The enable applies to the level of that test(CDB or PDB or service) and
-- persists across restarts.
end;
/
create or replace public synonym dbms_session for sys.dbms_session
/
grant execute on dbms_session to public
/
@?/rdbms/admin/sqlsessend.sql
OHA YOOOO