oracle DBMS_SYSTEM

DBMS_SYSTEM
A definitive guide

参考：http://docstore.mik.ua/orelly/oracle/bipack/ch11_02.htm

Garry Robinson December 2001  first version for Oracle 7.3

Jens-Uwe Petersen March 2003  revised for Oracle 8.0 - 9.2 
Jens-Uwe Petersen May 2004  revised for Oracle 10.1 

ABSTRACT

Presenting the “missing” section from the PL/SQL supplied packages manual. This is not an official Oracle document. I formatted it to look the same as the Oracle online documentation just for fun.
 
Oracle Documentation

PL/SQL Packages and Types Reference
10g Release 1 (10.1)
Part Number B10802-01

DBMS_SYSTEM
This package enables you to gather information about events set in the current session and manipulate others users sessions to set events and change the values of certain init.ora parameters. It provides some of the capability of DBMS_SESSION but with the ability to affect any session.
Oracle version 8.0 introduced a procedure to reset the IO counters in dynamic performance views (KCFRMS) and a suite of procedures that allow privileged users to write messages to the session trace file and instance alert log.
For Oracle version 10.1 a procedure to read in environment variables (GET_ENV) has been added.

Note:
I should add that this package has been left undocumented for good reason and since Oracle8, it has been wrapped and moved into prvtutil.plb “for obscurity”.

Requirements
This package is owned by SYS and is not generally available. I recommend that you only use this when logged on as SYS or connected as SYSDBA.

Summary of Subprograms

Table DBMS_SYSTEM Subprograms
Subprogram
Description
DIST_TXN_SYNC

Distributed transaction synchronisation
GET_ENV

Get the value of environment variables
KCFRMS

Reset counters in v$session_event and v$filestat
KSDDDT

Prints the date stamp to the target file (alert log and/or trace file).
KSDFLS

Flushes any pending output to the target file.
KSDIND
Does an 'indent' before the next write (ksdwrt) by printing that many colons (:) before the next write.
KSDWRT

Prints the message to the target file (alert log and/or trace file).
READ_EV

Get the level for events set in the current session.
SET_BOOL_PARAM_IN_SESSION

Sets boolean-type init.ora parameters in any session
SET_EV

Set an event in any session
SET_INT_PARAM_IN_SESSION

Sets integer-type init.ora parameters in any session
SET_SQL_TRACE_IN_SESSION

Turns tracing on or off in any session
WAIT_FOR_EVENT

Puts the current session into a wait state for any named wait event

Privileges
Before using this package, you must run the DBMSUTIL.SQL and PRVTUTIL.PLB scripts to create the DBMS_SYSTEM package.

DIST_TXN_SYNC Procedure

There is no public information available for this procedure, but it somehow sounds like distributed transaction synchronisation.  According to Tom Kyte it is used in XA interfaces and is nothing you would ever need to call directly.

Syntax
DBMS_SYSTEM.DIST_TXN_SYNC (inst_num  IN  NUMBER);

Parameters
Table DIST_TXN_SYNC Procedure Parameters
Parameter
Description
Inst_num 
Database instance number

GET_ENV Procedure

This procedure has been introduced with 10g. It returns the value of environment variables.
The behaviour is different for Windows and Unix.

In Unix every environment variable set in the current Oracle process can be retrieved. These environment variables are inherited from the listener if connected through SQL*Net or from the current shell if connected locally.

In Windows only registry values under the current Oracle home (per default HKLM\SOFTWARE\ORACLE\ KEY_OraDb10g_home1) can be retrieved. No system or user variables can be read, and the use of the ENVS parameter in the listener.ora is not supported on Windows.

Syntax
DBMS_SYSTEM.GET_ENV (
   var  IN  VARCHAR2,
   val  OUT VARCHAR2);

Parameters
Table GET_ENV Procedure Parameters
Parameter
Description
Var Name of the environment variable / registry key.
Val Value of the environment variable. NULL if variable is not defined.
Example
Retrieve environment variable from Unix:

SQL> var v_value char(70);
SQL> exec dbms_system.get_env('ORACLE_SID', :v_value);
SQL> print v_value;

V_VALUE
--------
db10

Retrieve value from Windows registry:

SQL> exec dbms_system.get_env(' OLEDB\TraceFileName', :v_value);
SQL> print v_value;

V_VALUE
----------------
c:\OraOLEDB.trc

KCFRMS Procedure

This procedure resets the timers displayed by MAX_WAIT in V$SESSION_EVENT and MAXIORTM, MAXIOWTM in V$FILESTAT (X$KCFIO) views.

Table Reseted Columns in V$SESSION_EVENT
Parameter
Description
MAX_WAIT 
The maximum time (in hundredths of a second) waited for this event by this session

Table Reseted Columns in V$FILESTAT
Parameter
Description
MAXIOWTM The maximum time (in milliseconds) spent doing a single write,
if the TIMED_STATISTICS parameter is TRUE; 0 if FALSE
MAXIORTM The maximum time (in milliseconds) spent doing a single read,
if the TIMED_STATISTICS parameter is TRUE; 0 if FALSE

Syntax
DBMS_SYSTEM.KCFRMS ;

Example
To check  for the current timer values:

SQL> select MAX_WAIT from V$SESSION_EVENT;
SQL> select MAXIORTM, MAXIOWTM from V$FILESTAT;
?
KSDDDT Procedure

This procedure prints the timestamp to the trace file. It can’t be used for the alert log.

Syntax
DBMS_SYSTEM.KSDDDT ;

Example
SQL> exec dbms_system.ksdddt ;

Output in tracefile looks like:

*** 2003-03-10 21:23:17.000

 
KSDFLS Procedure

This procedure flushes any pending output to the target file (alert log and/or trace file).

Syntax
DBMS_SYSTEM.KSDFLS ;

KSDIND Procedure

This procedure does an 'indent' before the next write (ksdwrt) by printing that many colons (:) before the next write.

Syntax
DBMS_SYSTEM.KSDIND (lvl  IN  BINARY_INTEGER);

Parameters
Table KSDIND Procedure Parameters
Parameter
Description
Lvl 
The indend level from 0 to 30

Example
Write in the same line 5 ‘:’ and the text ’Test Alert Msg’  to the tracefile and the alertlog:

SQL> exec dbms_system.ksdind (5);
SQL> exec dbms_system.ksdwrt (3, ‘Test Alert Msg’);

Output in tracefile/alertlog looks like:

:::::Test Alert Msg?
KSDWRT Procedure

This procedure prints the message to the target file (alert log and/or trace file).

Syntax
DBMS_SYSTEM.KSDWRT (
   dest  IN  BINARY_INTEGER,
   tst   IN  VARCHAR2);

Parameters
Table KSDWRT Procedure Parameters
Parameter
Description
dest Destination is indicated by the following values:
1 - Write to trace file.
2 - Write to alertlog.
3 - Write to both.
tst 
Message (not tested for max length, but output with 2000 chars was successful)

Example
Write the text ’Test Alert Msg’  to the tracefile and the alertlog:

SQL> exec dbms_system.ksdwrt (3, ‘ ’);
SQL> exec dbms_system.ksdwrt (3, ‘--- Start ---’);
SQL> exec dbms_system.ksdddt;
SQL> exec dbms_system.ksdwrt (3, ‘    Test Alert Msg’);
SQL> exec dbms_system.ksdwrt (3, ‘--- End ---’);
SQL> exec dbms_system.ksdwrt (3, ‘ ’);

Output in tracefile looks like:

*** 2003-03-10 21:23:17.000

--- Start ---
*** 2003-03-10 21:23:17.000
    Test Alert Msg
--- Ende ---

 
Output in alertlog looks like:

Mon Mar 10 21:23:17 2003
 
--- Start ---
    Test Alert Msg
--- Ende ---
 

Note the following:
? Oracle automatically prints a timestamp before the very first output of a ksd-function in a session.
? The date format differs between the alertlog and the tracefile.?
READ_EV Procedure

This procedure returns the level for any event set in the session. Error codes 10000 to 10999 are reserved for debug event codes that are not really errors. See file $ORACLE_HOME/rdbms/mesg/oraus.msg for details of events and possible level settings.

Syntax
DBMS_SYSTEM.READ_EV (
   iev  IN  BINARY_INTEGER,
   oev  OUT BINARY_INTEGER);

Parameters
Table READ_EV Procedure Parameters
Parameter
Description
iev 
The event number  10000 to 10999
oev 
Event level. Level will be 0 if the event is not set.

Example
To check whether the session is in SQL_TRACE mode:

SQL> ALTER SYSTEM SET SQL_TRACE=TRUE;   (implicitly sets event 10046 at level 1)

SQL> exec dbms_system.read_ev(10046,:lev);
SQL> print lev

       LEV
----------
         1

?
SET_EV Procedure

This procedure allows you to set an event in any session for debugging purposes.  Common events to enable debugging are:
10032 sorts
10033 large sorts
10046 sql_trace / SQL statements (at level 1, equivalent to SQL_TRACE=TRUE)
10053 cost-based optimizer tracing
10104 hash join debugging
 
Syntax
DBMS_SYSTEM.SET_EV (
   si  IN  BINARY_INTEGER,
   se  IN  BINARY_INTEGER,
   ev  IN  BINARY_INTEGER,
   le  IN  BINARY_INTEGER,
   nm  IN  BINARY_INTEGER);

Parameters
Table SET_EV Procedure Parameters
Parameter
Description
si 
Session identifier
se 
Session serial number
ev 
The event number  10000 to 10999
le 
The level to set. See file $ORACLE_HOME/rdbms/mesg/oraus.msg for details of events and possible level settings.
nm 
Name, usually just set it to a NULL string ‘’

Example
Set event 10046 (SQL_TRACE) at level 12 to collect information about all wait events and bind variables. The trace information will get written to user_dump_dest.

SQL> exec dbms_system.set_ev(8, 1158, 10046, 12, ‘’);

?
SET_SQL_TRACE_IN_SESSION Procedure

This procedure is similar to DBMS_SESSION.SET_SQL_TRACE which turns tracing on or off. It is equivalent to the following SQL statement except that it can be used to set SQL_TRACE in another session:

ALTER SESSION SET SQL_TRACE ...

Behind the scenes, it actually just calls DBMS_SYSTEM.SET_EV to set event 10046 at level 1.

Syntax
DBMS_SYSTEM.SET_SQL_TRACE_IN_SESSION (
   sid       IN  NUMBER,
   serial#   IN  NUMBER,
   sql_trace IN  BOOLEAN);

Parameters
Table SET_SQL_TRACE_IN_SESSION Procedure Parameters
Parameter
Description
sid 
Session identifier
serial# 
Session serial number
sql_trace 
TRUE turns tracing on, FALSE turns tracing off.

Example
Turn SQL tracing on in session 448. The trace information will get written to user_dump_dest.

SQL> exec dbms_system.set_sql_trace_in_session(448,2288,TRUE);

Turn SQL tracing off in session 448

SQL> exec dbms_system.set_sql_trace_in_session(448,2288,FALSE);

?
SET_INT_PARAM_IN_SESSION Procedure

This procedure allows you to change init.ora parameters in the context of another user’s session. It is equivalent to the following SQL statement:

ALTER SESSION SET parameter_name = value;

Syntax
DBMS_SYSTEM.SET_INT_PARAM_IN_SESSION (
   sid       IN  NUMBER,
   serial#   IN  NUMBER,
   parnam    IN  VARCHAR2,
   intval    IN  BINARY_INTEGER);

Parameters
Table SET_INT_PARAM_IN_SESSION Procedure Parameters
Parameter
Description
sid 
Session identifier
serial# 
Session serial number
parnam 
Parameter name
intval 
New value

Example
SQL> exec dbms_system.SET_INT_PARAM_IN_SESSION
          (16, 161, 'sort_area_size', 1048576);

?
SET_BOOL_PARAM_IN_SESSION Procedure

Similar to SET_INT_PARAM_IN_SESSION, this procedure allows you to change init.ora parameters in the context of another user’s session. It is equivalent to the following SQL statement:

ALTER SESSION SET parameter_name = value;

Syntax
DBMS_SYSTEM.SET_BOOL_PARAM_IN_SESSION (
   sid       IN  NUMBER,
   serial#   IN  NUMBER,
   parnam    IN  VARCHAR2,
   bval      IN  BOOLEAN);

Parameters
Table SET_BOOL_PARAM_IN_SESSION Procedure Parameters
Parameter
Description
sid 
Session identifier
serial# 
Session serial number
parnam 
Parameter name
bval 
New value

Example
SQL> exec dbms_system.SET_BOOL_PARAM_IN_SESSION(16, 161, 'sql_trace', TRUE);

?
WAIT_FOR_EVENT Procedure

This procedure causes the current session to go into a wait for the event specified. The event must be a recognised wait event from V$EVENT_NAME. The session will wait for the timeout period specified and populate the P1 column in V$SESSION_WAIT with the value of EXTENDED_ID .

I can’t think of any useful purpose for this procedure other than possibly training or as a substitute for DBMS_LOCK.SLEEP.

Syntax
DBMS_SYSTEM.WAIT_FOR_EVENT (
   event         IN  VARCHAR2,
   extended_id   IN  BINARY_INTEGER,
   timeout       IN  BINARY_INTEGER);

Parameters
Table WAIT_FOR_EVENT Procedure Parameters
Parameter
Description
event 
Wait event name.
extended_id 
P1 value.
This value will be placed in the P1 column of V$SESSION_WAIT
timeout 
Time to wait in seconds

Example
Wait for “debugger command” event for 10 seconds:

SQL> exec dbms_system.wait_for_event('debugger command',55,10);

Check V$SESSION_WAIT from another session:

SQL> select sid, event, p1, seconds_in_wait, state
  2  from v$session_wait
  3  where sid=8;
                                         SECONDS
                                              IN
  SID EVENT                        P1       WAIT STATE
----- -------------------- ---------- ---------- --------
    8 debugger command             55          3 WAITING