DBMS_SYSTEM

A definitive guide

Garry Robinson

December 2001

first version for Oracle 7.3

Jens-Uwe Petersen
Jens-Uwe Petersen

March 2003
May 2004

revised for Oracle 8.0 - 9.2

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.

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
DIST_TXN_SYNC
GET_ENV
KCFRMS
KSDDDT
KSDFLS
KSDIND
KSDWRT
READ_EV
SET_BOOL_PARAM_IN_SESSION
SET_EV
SET_INT_PARAM_IN_SESSION

Garry Robinson
December 2001 OracleAdvice Ltd.

Description
Distributed transaction synchronisation
Get the value of environment variables
Reset counters in v$session_event and v$filestat
Prints the date stamp to the target file (alert log and/or trace file).
Flushes any pending output to the target file.
Does an 'indent' before the next write (ksdwrt) by printing that many
colons (:) before the next write.
Prints the message to the target file (alert log and/or trace file).
Get the level for events set in the current session.
Sets boolean-type init.ora parameters in any session
Set an event in any session
Sets integer-type init.ora parameters in any session

Jens-Uwe Petersen
May 2004 Trivadis GmbH

SET_SQL_TRACE_IN_SESSION
WAIT_FOR_EVENT

Turns tracing on or off in any session

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
Inst_num

Description
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
Var
Val

Description
Name of the environment variable / registry key.
Value of the environment variable. NULL if variable is not defined.

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
MAX_WAIT

Description
The maximum time (in hundredths of a second) waited for this event by this session

Table Reseted Columns in V$FILESTAT

Description
The maximum time (in milliseconds) spent doing a single write,
if the TIMED_STATISTICS parameter is TRUE; 0 if FALSE
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;

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

KSDDDT Procedure
This procedure prints the timestamp to the trace file. It cant 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
Lvl

Description
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

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
dest
tst

Description
Destination is indicated by the following values:
1 - Write to trace file.
2 - Write to alertlog.
3 - Write to both.
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>
SQL>
SQL>
SQL>
SQL>
SQL>

exec
exec
exec
exec
exec
exec

dbms_system.ksdwrt (3,
dbms_system.ksdwrt (3,
dbms_system.ksdddt;
dbms_system.ksdwrt (3,
dbms_system.ksdwrt (3,
dbms_system.ksdwrt (3,

);
--- Start ---);

Test Alert Msg);

Output in tracefile looks like:

Note the following:

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
iev
oev

Description
The event number 10000 to 10999
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

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
si
se
ev
le
nm

Description
Session identifier
Session serial number
The event number 10000 to 10999
The level to set. See file $ORACLE_HOME/rdbms/mesg/oraus.msg for details of events and
possible level settings.
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, );

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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
sid
serial#
sql_trace

Description
Session identifier
Session serial number
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);

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

SET_INT_PARAM_IN_SESSION Procedure
This procedure allows you to change init.ora parameters in the context of another users 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
sid
serial#
parnam
intval

Description
Session identifier
Session serial number
Parameter name
New value

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

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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 users 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
sid
serial#
parnam
bval

Description
Session identifier
Session serial number
Parameter name
New value

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

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH

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 cant 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
event
extended_id
timeout

Description
Wait event name.
P1 value.
This value will be placed in the P1 column of V$SESSION_WAIT
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

Garry Robinson
December 2001 OracleAdvice Ltd.

Jens-Uwe Petersen
May 2004 Trivadis GmbH