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