1 package dbms_debug_jdwp authid current_user is
2
3
4 -- DBMS_DEBUG_JDWP.CONNECT_TCP:
5
6 -- Connect the specified session to the debugger waiting at host:port.
7 --
8 -- To connect the current session to a debugger, you can pass NULL to
9 -- both the session_id and session_serial parameters.
10 --
11 -- To connect a different session, you need to find out its id and
12 -- serial. These are available in the v$session and v_$session views,
13 -- although in general only users with dba-like privileges can select
14 -- from those. Oracle Enterprise Manager's Instance Manager is one
15 -- example of a user interface that will display these values to
16 -- users with sufficient privileges. You can also find the values of
17 -- these for your own session using the current_session_id and
18 -- current_session_serial functions declared below.
19 --
20 -- An ORA-30677 indicates that the requested session is already
21 -- being debugged. It is suggested in this case that the user be
22 -- asked to confirm that (s)he desires to steal the session from
23 -- the existing connection, and then either an explicit disconnect
24 -- call or the use of the connect_force_connect option bit
25 -- can be used to allow the connection to succeed on a second attempt.
26 -- Note that using the connect_force_connect bit will avoid
27 -- the session being allowed to run freely if it is currently suspended
28 -- through the debugger - in other words, this bit lets you steal a
29 -- session from one debugger to another without actually disturbing the
30 -- state of the session at all.
31 --
32 -- The debug_role and debug_role_pwd arguments allow the user to name
33 -- any role as the "debug role", which will be available to privilege
34 -- checking when checking for permissions to connect the session and
35 -- when checking permissions available on objects within the debugged
36 -- session. Both the role and its password are passed here as strings
37 -- and not as identifiers, so double quotes should not be used but
38 -- case matters -- if the original role name wasn't double-quoted,
39 -- it should be specified here in upper case.
40 --
41 -- Likely errors to encounter here are ORA-00022, ORA-01031, ORA-30677,
42 -- ORA-30681, ORA-30682, and ORA-30683.
43 --
44 -- NOTE: Only a subset of our desired functionality is implemented in this
45 -- release:
46 --
47 -- - A session cannot yet connect another session to a debugger; it
48 -- can only connect itself. ORA-00022 will be raised on attempts
49 -- to cause other sessions to connect to a debugger.
50 --
51 -- - The per-object DEBUG privilege is not yet meaningful. Attempts
52 -- to connect to a debugger will only succeed at all if the session's
53 -- current effective user and roles unioned with the debug_role carry
54 -- both the DEBUG CONNECT SESSION and DEBUG ANY PROCEDURE privileges.
55 -- ORA-01031 will be raised otherwise.
56 --
57 -- - The session's effective user at the time of the call must be the
58 -- same as the login user of the session. This call will not succeed
59 -- if invoked from a definer's rights function running as a different
60 -- user; in such a case an ORA-01031 will be raised.
61 --
62 procedure connect_tcp(host varchar2,
63 port varchar2,
64 session_id pls_integer := NULL,
65 session_serial pls_integer := NULL,
66 debug_role varchar2 := NULL,
67 debug_role_pwd varchar2 := NULL,
68 option_flags pls_integer := 0,
69 extensions_cmd_set pls_integer := 128);
70
71 -- Values for option_flags argument:
72 -- These may be added together to select multiple option choices.
73
74 -- Don't actually suspend the program until the next client/server
75 -- request begins. This can be used to hide the startup sequence
76 -- itself from end users, who likely really only want to see their
77 -- own code.
78 connect_defer_suspension constant pls_integer := 1;
79
80 -- Force the connection even if the session appears to already be
81 -- connected to a debugger. This should best only be specified
82 -- after some human-interaction confirmation step has occurred; i.e.,
83 -- if an attempt without this option raised ORA-30677, then if the user
84 -- confirms, retry with this bit set.
85 connect_force_connect constant pls_integer := 2;
86
87
88
89 -- DBMS_DEBUG_JDWP.DISCONNECT:
90
91 -- Disconnect the specified session from any debugger that it is connected
92 -- with. The session will be allowed to run freely after disconnecting the
93 -- debugger. The same rights are required for this call as for
94 -- connect.
95 --
96 -- An ORA-00022 exception may be raised here.
97 --
98 -- NOTE: Only a subset of our desired functionality is implemented in this
99 -- release:
100 --
101 -- - A session cannot yet disconnect another session from a debugger; it
102 -- can only connect or disconnect itself. ORA-00022 will be raised on
103 -- attempts to cause other sessions to disconnect from a debugger.
104 --
105 procedure disconnect(session_id pls_integer := NULL,
106 session_serial pls_integer := NULL);
107
108
109
110 -- DBMS_DEBUG_JDWP.CURRENT_SESSION_ID:
111
112 -- Get the current session's session id.
113 --
114 -- No special rights are required and no errors are possible.
115 --
116 function current_session_id return pls_integer;
117
118
119
120 -- DBMS_DEBUG_JDWP.CURRENT_SESSION_SERIAL:
121
122 -- Get the current session's session serial number.
123 --
124 -- No special rights are required and no errors are possible.
125 --
126 function current_session_serial return pls_integer;
127
128
129
130 -- DBMS_DEBUG_JDWP.PROCESS_CONNECT_STRING:
131
132 -- To make it easy to connect a session to a debugger without having to
133 -- directly modify an application's code, we provide mechanisms allowing a
134 -- session to connect to a debugger through the use of either the
135 -- ORA_DEBUG_JDWP operating system environment variable when running
136 -- an OCI program, or a web browser "cookie" called OWA_DEBUG_<dad>
137 -- set when running an application through the PL/SQL Web Gateway.
138 --
139 -- Such connections to a debugger route through this function to have
140 -- the environment variable or cookie value parsed and the next layer
141 -- of processing dispatched.
142 --
143 -- Alternative PL/SQL web cartridge/gateway products are free to use
144 -- this API to establish debugging connections.
145 --
146 -- All errors discussed under DBMS_DEBUG_JDWP.CONNECT_TCP may be raised
147 -- by this call. ORA-30689 may also be raised. Additionally, this call
148 -- can route through "custom" routines implemented by the application to
149 -- do additional filtering on which debugger connections to allow; errors
150 -- may also be raised from such "custom" code.
151 --
152 procedure process_connect_string(connect_string varchar2,
153 connect_string_type pls_integer);
154
155 -- Values for connect_string_type argument:
156
157 -- After parsing, invoke DBMS_DEBUG_JDWP_CUSTOM.CONNECT_DEBUGGER
158 connect_string_environment_var constant pls_integer := 1;
159
160 -- After parsing, invoke OWA_DEBUG_JDWP_CUSTOM.CONNECT_DEBUGGER
161 connect_string_cookie constant pls_integer := 2;
162
163
164
165 -- DBMS_DEBUG_JDWP.GET_NLS_PARAMETER, SET_NLS_PARAMETER:
166
167 -- Gets or sets the value of the specified NLS parameter affecting the
168 -- format in which NUMBER, DATE, TIME (WITH TIME ZONE) and TIMESTAMP (WITH
169 -- TIME ZONE) runtime values of PL/SQL programs are converted to strings
170 -- as they are presented through JDWP. These values are private to the
171 -- current session, but further are private to the debugger mechanisms,
172 -- separate from the values used to convert values within the debugged
173 -- program itself.
174 --
175 -- When any variable value is read or assigned through JDWP, or when one
176 -- of these get_nls_parameter or set_nls_parameter APIs are first invoked
177 -- in a session, the debugger mechanisms make a private copy of the
178 -- then-current NLS_LANGUAGE, NLS_TERRITORY, NLS_CALENDAR,
179 -- NLS_DATE_LANGUAGE, NLS_NUMERIC_CHARACTERS, NLS_TIMESTAMP_FORMAT,
180 -- NLS_TIMESTAMP_TZ_FORMAT, NLS_TIME_FOMAT and NLS_TIME_TZ_FORMAT values.
181 -- These private copies may be read using this get_nls_parameter call and
182 -- changed using the following set_nls_parameter call.
183 --
184 -- Once the debugger's private copy of the NLS parameters is established,
185 -- changes made to the NLS parameters in the current session using the
186 -- "ALTER SESSION" statement will have no effect on the formatting of
187 -- values as seen through JDWP. To modify the NLS parameters used for
188 -- JDWP, one must use this set_nls_parameter procedure.
189 --
190 -- Vice versa, changes made to the debugger's private copy of the NLS
191 -- parameters using this set_nls_parameter procedure will have no effect
192 -- on the debugged program itself.
193 --
194 -- Date values are always formatted for JDWP use using the
195 -- NLS_TIMESTAMP_FORMAT. The default format for DATE (NLS_DATE_FORMAT)
196 -- used in a session most often does not show the time information that
197 -- is in fact present in the value, and for debugging purposes it seems
198 -- beneficial to always display that information.
199 --
200 function get_nls_parameter(name varchar2) return varchar2;
201
202 procedure set_nls_parameter(name varchar2, value varchar2);
203
204 end;
[Home] [Help]