1 package dbms_application_info is
2
3 -- DE-HEAD <- tell SED where to cut
4
5 ------------
6 -- OVERVIEW
7 --
8 -- The dbms_application_info package provides a mechanism for registering
9 -- the name of the application module that is currently running with the
10 -- rdbms. Registering the name of the module allows DBAs to monitor how the
11 -- system is being used, and do performance analysis, and resource
12 -- accounting by module. The name that is registered through this
13 -- package will appear in the 'module' and 'action' column of
14 -- the v$session virtual table. It will also appear in the 'module' and
15 -- 'action' columns in v$sqlarea.
16 --
17 -- The MODULE name is normally set to a user recognizable name for the
18 -- program that is currently executing. For example, this could be the name
19 -- of the form that is executing, or it could be the name of the script that
20 -- is being executed by sql*plus. The idea is to be able to identify the
21 -- high level function that is being performed. For instance, you can tell
22 -- that a user is in the 'order entry' form instead of just telling that he
23 -- is running sql*forms. We encourage application tool vendors to
24 -- automatically set this value whenever an application is executed.
25 --
26 -- The ACTION name is normally set to a specific action that a user is
27 -- performing within a module. For instance a user could be 'reading
28 -- mail' or 'entering a new customer'. This is meant to more specifically
29 -- identify what a user is currently doing. The action should normally be
30 -- set by the designer of a specific application. It should not
31 -- automatically be set by the application tool.
32 --
33 -- If the local DBA would like to gather his own statistics based on
34 -- module, then the DBA can implement a wrapper around this package
35 -- by writing a version of this package in another schema that first
36 -- gathers statistics and then calls the sys version of the package. The
37 -- public synonym for dbms_application_info can then be changed to point
38 -- to the DBA's version of the package.
39 --
40
41 ----------------------------
42 -- PROCEDURES AND FUNCTIONS
43 --
44 procedure set_module(module_name varchar2, action_name varchar2);
45 -- Sets the name of the module that is currently running to a new
46 -- module. When the current module terminates, this should
47 -- be called with the name of the new module if there is one, or
48 -- null if there is not a new module. Passing null for either of these
49 -- values is equivalent to passing a zero length string.
50 -- Input arguments:
51 -- module_name
52 -- The name of the module that will now be running. The maximum
53 -- length of the module name is 64 bytes. Longer names will be
54 -- truncated.
55 -- action_name
56 -- The name of the action that will now be running. The maximum
57 -- length of the action_name is 64 bytes. Longer names will be
58 -- truncated. If the action name is not being specified, then null
59 -- should be passed for this value.
60 --
61 procedure set_action(action_name varchar2);
62 -- Sets the name of the current action within the current module.
63 -- When the current action terminates, this should be called with the
64 -- name of the new action if there is one, or null if there is not a
65 -- new action. Passing null for this value is equivalent to passing
66 -- a zero length string.
67 -- Input arguments:
68 -- action_name
69 -- The name of the action that will now be running. The maximum
70 -- length of the action_name is 64 bytes. Longer names will be
71 -- truncated.
72 --
73 procedure read_module(module_name out varchar2, action_name out varchar2);
74 -- Reads the values of the module and action fields of the current
75 -- session.
76 -- Output arguments:
77 -- module_name
78 -- The last value that the module name was set to using the set_module
79 -- procedure.
80 -- action_name
81 -- The last value that the action name was set to using the set_module
82 -- or set_action procedures.
83 --
84 procedure set_client_info(client_info varchar2);
85 -- Sets the client info field of the session. The client info field is
86 -- provided for the use of individual applications. The Oracle system
87 -- does not use this field for any purpose. After being set, the
88 -- client info field can be queried from v$session.
89 -- Input arguments:
90 -- client_info
91 -- Any character data that the client wishes to store up to a maximum of
92 -- 64 bytes. Longer values will be truncated. Passing a null is
93 -- equivalent to passing a zero length string.
94
95 procedure read_client_info(client_info out varchar2);
96 -- Reads the value of the client_info field of the current session.
97 -- Output arguments:
98 -- client_info
99 -- The last value that the client_info field was set to using the
100 -- set_client_info procedure.
101
102 procedure set_session_longops(rindex in out pls_integer,
103 slno in out pls_integer,
104 op_name in varchar2 default null,
105 target in pls_integer default 0,
106 context in pls_integer default 0,
107 sofar in number default 0,
108 totalwork in number default 0,
109 target_desc in varchar2
110 default 'unknown target',
111 units in varchar2 default null);
112
113 set_session_longops_nohint constant pls_integer := -1;
114
115 -- Sets a row in the V$SESSION_LONGOP table. This is a table which is
116 -- customarily used to indicate the on-going progress of a long running
117 -- operation. Some Oracle functions, such as Parallel Query and
118 -- Server Managed Recovery, use rows in this table to indicate the status
119 -- of, for example, a database backup. Applications may use this function
120 -- to advertise information about application-specific long running tasks.
121 -- Input Arguments:
122 -- rindex
123 -- This is a token which represents the v$session_longops row to update.
124 -- Set this to set_session_longops_nohint to start a new row. Use the
125 -- returned value from the prior call to reuse a row.
126 -- slno
127 -- This parameter is used to save information across calls to
128 -- set_session_longops. It is for internal use and should not be
129 -- modified by the caller.
130 -- op_name
131 -- This parameter specifies the name of the long running task. It
132 -- will appear as the OPNAME column of v$session_longops. The
133 -- maximum length of op_name is 64 bytes.
134 -- target
135 -- This parameter specifies the object that is being worked upon
136 -- during the long running operation. For example, it could be a
137 -- table id that is being sorted. It will appear as the TARGET
138 -- column of v$session_longops.
139 -- context
140 -- Any number the client wishes to store. It will appear in the
141 -- CONTEXT column of v$session_longops.
142 -- sofar
143 -- Any number the client wishes to store. It will appear in the
144 -- SOFAR column of v$session_longops. This is typically the amount
145 -- of work which has been done so far.
146 -- totalwork
147 -- Any number the client wishes to store. It will appear in the
148 -- TOTALWORK column of v$session_longops. This is typically the total
149 -- amount of work needed to be done in this long running operation.
150 -- target_desc
151 -- This parameter specifies the description of the object being
152 -- manipulated in this long operation. Basically, this provides a
153 -- caption for the 'target' parameter above. This value will appear
154 -- in the TARGET_DESC field of v$session_longops. The maximum length
155 -- of target_desc is 32 bytes.
156 -- units
157 -- This parameter specifies the units in which 'sofar' and 'totalwork'
158 -- are being represented. It will appear as the UNITS field of
159 -- v$session_longops. The maximum length of units is 32 bytes.
160
161 pragma TIMESTAMP('1998-03-12:12:00:00');
162
163 end;
164
165 -- CUT_HERE <- tell sed where to chop off the rest
[Home] [Help]