1 PACKAGE DBMS_DEBUG IS
2
3 ------------------------------
4 -- PUBLIC CONSTANTS and TYPES
5
6 ----------------------------- PROGRAM_INFO ---------------------
7 -- Specifies a program location - a line number in a program unit.
8 -- Used for stack backtraces and for setting and examining breakpoints.
9 --
10 -- The read-only fields are currently ignored by Probe for breakpoint
11 -- operations. They are set by Probe only for stack backtraces.
12 -- EntrypointName - null unless this is a nested procedure/function
13 -- LibunitType - to disambiguate among objects that share the same
14 -- namespace (eg. procedure and package spec). See
15 -- the LibunitType_* constants below.
16 --
17 TYPE program_info IS RECORD
18 (
19 -- The following fields are used when setting a breakpoint
20 Namespace BINARY_INTEGER, -- See 'NAMESPACES' section below.
21 Name dbms_id, -- name of the program unit
22 Owner dbms_id, -- owner of the program unit
23 Dblink dbms_id, -- database link, if remote
24 Line# BINARY_INTEGER,
25
26 -- Read-only fields (set by Probe when doing a stack backtrace)
27 LibunitType BINARY_INTEGER, -- ie. kglobtyp
28 EntrypointName VARCHAR2(512)
29 );
30
31 ------------------------------- RUNTIME_INFO -----------------------
32 -- Runtime_info gives context information about the running program.
33 --
34 -- Probe v2.4:
35 -- Added oer. It gets set if info_getOerInfo is set. The oer
36 -- is a positive number. It can be translated into SQLCODE by
37 -- translating 1403 to 100, 6510 to 1, and negating any other value.
38 --
39 TYPE runtime_info IS RECORD
40 (
41 Line# BINARY_INTEGER, -- (duplicate of program.line#)
42 Terminated BINARY_INTEGER, -- has the program terminated?
43 Breakpoint BINARY_INTEGER, -- breakpoint number
44 StackDepth BINARY_INTEGER, -- number of frames on the stack
45 InterpreterDepth BINARY_INTEGER, -- <reserved field>
46 Reason BINARY_INTEGER, -- reason for suspension
47 Program program_info, -- source location
48
49 -- Following fields were added in Probe v2.4
50 oer PLS_INTEGER -- OER (exception), if any
51 );
52
53 ---------------------------- BREAKPOINT_INFO ----------------------------
54 -- Information about a breakpoint: its current status and the program unit
55 -- in which it was placed.
56 --
57 -- (The reason for duplicating fields from the 'program_info' record is
58 -- that PL/SQL doesn't yet support tables of composite records, and
59 -- show_breakpoints is going to build a table of these records.)
60 --
61 TYPE breakpoint_info IS RECORD
62 (
63 -- These fields are duplicates of 'program_info':
64 Name dbms_id,
65 Owner dbms_id,
66 DbLink dbms_id,
67 Line# BINARY_INTEGER,
68 LibunitType BINARY_INTEGER,
69
70 Status BINARY_INTEGER -- see breakpoint_status_* below
71 );
72
73 -- Breakpoint statuses.
74 -- breakpoint_status_unused - the breakpoint is not in use.
75 --
76 -- Otherwise the status is a mask of the following values:
77 -- breakpoint_status_active - this is a line breakpoint
78 -- breakpoint_status_active2 - this is an entry breakpoint (deprecated
79 -- functionality)
80 -- breakpoints_status_disabled - this breakpoint is currently disabled
81 -- breakpoint_status_remote - this is a 'shadow' breakpoint (a local
82 -- representation of a remote breakpoint).
83 --
84 -- (Internal note: these map to the PBBPT constants)
85 --
86 breakpoint_status_unused CONSTANT BINARY_INTEGER := 0;
87 breakpoint_status_active CONSTANT BINARY_INTEGER := 1;
88 breakpoint_status_active2 CONSTANT BINARY_INTEGER := 2;
89 breakpoint_status_disabled CONSTANT BINARY_INTEGER := 4;
90 breakpoint_status_remote CONSTANT BINARY_INTEGER := 8;
91
92
93 ------------------------------ INDEX_TABLE ------------------------------
94 -- Used by get_indexes to return the available indexes for a given
95 -- indexed table. See get_indexes for more details.
96 --
97 TYPE index_table IS table of BINARY_INTEGER index by BINARY_INTEGER;
98
99 ---------------------------- BACKTRACE_TABLE ----------------------------
100 -- Used by print_backtrace.
101 TYPE backtrace_table IS TABLE OF program_info INDEX BY BINARY_INTEGER;
102
103 --------------------------- BREAKPOINT_TABLE ---------------------------
104 -- Used by show_breakpoints.
105 TYPE breakpoint_table IS TABLE OF breakpoint_info INDEX BY BINARY_INTEGER;
106
107 ------------------------------- VC2_TABLE -------------------------------
108 -- Used by show_source.
109 TYPE vc2_table IS table of varchar2(90) index by BINARY_INTEGER;
110
111 ------------------------------- oer_table -------------------------------
112 -- Used by show_breakpoints
113 -- VERSION
114 -- Probe v2.4
115 TYPE oer_table IS TABLE OF PLS_INTEGER INDEX BY BINARY_INTEGER;
116
117 ------------------------------- NAMESPACES -----------------------------
118 -- Program units on the server reside in different namespaces. When
119 -- setting a breakpoint it is necessary to specify the desired namespace
120 -- (to distinguish between a package spec and a package body, for example).
121 --
122 -- 1. Namespace_cursor contains cursors (anonymous blocks)
123 -- 2. Namespace_pgkspec_or_toplevel contains:
124 -- + package specifications
125 -- + procedures and functions (that are not nested inside other
126 -- packages/procedures/functions)
127 -- + object types
128 -- 3. Namespace_pkg_body contains package bodies and type bodies.
129 -- 4. Namespace_trigger contains triggers.
130 -- 5. Namespace_none is used to describe a frame by number,
131 -- currently supported by set_breakpoint only.
132 --
133 -- (Internal note: these map to the KGLN constants)
134 --
135 namespace_cursor CONSTANT BINARY_INTEGER := 0;
136 namespace_pkgspec_or_toplevel CONSTANT BINARY_INTEGER := 1;
137 namespace_pkg_body CONSTANT BINARY_INTEGER := 2;
138 namespace_trigger CONSTANT BINARY_INTEGER := 3;
139 namespace_none CONSTANT BINARY_INTEGER := 255;
140
141 ----------------------------- LIBUNIT TYPES -----------------------------
142 -- These provide an itemization of the actual type of a stack frame,
143 -- rather than just the namespace in which it resides. This information
144 -- is helpful sometimes when presenting a stack backtrace to the user,
145 -- and is written into the LibunitType field of program_info.
146 --
147 -- In retrospect, it probably would have been cleaner not to expose
148 -- namespaces at all and to use libunit types instead. This might be
149 -- done in a future release (via overloading).
150 --
151 -- (Internal note: these map to the KGLT constants).
152 --
153 LibunitType_cursor CONSTANT BINARY_INTEGER := 0;
154 LibunitType_procedure CONSTANT BINARY_INTEGER := 7;
155 LibunitType_function CONSTANT BINARY_INTEGER := 8;
156 LibunitType_package CONSTANT BINARY_INTEGER := 9;
157 LibunitType_package_body CONSTANT BINARY_INTEGER := 11;
158 LibunitType_trigger CONSTANT BINARY_INTEGER := 12;
159 LibunitType_Unknown CONSTANT BINARY_INTEGER := -1;
160
161
162 --------------------------- BREAK FLAGS --------------------------------
163 -- Values to use for the 'breakflags' parameter to continue(), in order
164 -- to tell Probe what events are of interest to the client.
165 -- These flags may be combined.
166 --
167 -- (Internal note: these map to the PEDE constants)
168 --
169 -- Line stepping:
170 -- break_next_line - break at next source line (step over calls)
171 -- break_any_call - break at next source line (step into calls)
172 -- break_any_return - break after returning from current entrypoint
173 -- (skip over any entrypoints that are called from the current)
174 -- break_return - break the next time an entrypoint gets ready to
175 -- return (note that this includes entrypoints called from the
176 -- current one. If interpreter is executing Proc1, which calls
177 -- Proc2, then break_return will stop at the end of Proc2.)
178 --
179 -- (Yes, break_any_return and break_return are backwards. Too late to
180 -- fix it now that we have existing clients...)
181 --
182 -- Exceptions:
183 -- break_exception - break when an exception is raised
184 -- break_handler - break when an exception handler is executed
185 --
186 -- Execution termination:
187 -- abort_execution - terminate execution and force an 'exit' event
188 -- as soon as DBMS_DEBUG.continue is called
189 --
190 break_exception CONSTANT PLS_INTEGER := 2;
191 break_any_call CONSTANT PLS_INTEGER := 12; -- 4 | 8
192 break_return CONSTANT PLS_INTEGER := 16;
193 break_next_line CONSTANT PLS_INTEGER := 32;
194 break_any_return CONSTANT PLS_INTEGER := 512;
195 break_handler CONSTANT PLS_INTEGER := 2048;
196 abort_execution CONSTANT PLS_INTEGER := 8192;
197
198 -- Not supported yet:
199 -- break_control_c - break when a control-C is issued by the client
200 -- break_RPC - break when executing an RPC
201 break_control_c CONSTANT BINARY_INTEGER := 256;
202 break_RPC CONSTANT BINARY_INTEGER := 4096;
203
204 -- Reserved internal values:
205 -- 4 and 8 for CALL/XCAL
206 -- 64 and 128 for ICD enter/return
207
208 ------------------------- INFORMATION FLAGS ---------------------------
209 -- These are flags that can be passed as the 'info_requested' parameter
210 -- to synchronize, continue, and get_runtime_info.
211 --
212 -- (Internal note: these map to the PBBA constants)
213 --
214 info_getStackDepth CONSTANT PLS_INTEGER := 2; -- get stack depth
215 info_getBreakpoint CONSTANT PLS_INTEGER := 4; -- get breakpoint number
216 info_getLineinfo CONSTANT PLS_INTEGER := 8; -- get program info
217 info_getOerInfo CONSTANT PLS_INTEGER := 32; -- (Probe v2.4)
218
219
220 ------------------------- REASONS -------------------------------------
221 -- Reasons for suspension. After continue is executed, the program will
222 -- either run to completion or break on some line.
223 --
224 -- (Internal note: these map to the PBEVN constants)
225 --
226 reason_none CONSTANT BINARY_INTEGER := 0;
227 reason_interpreter_starting CONSTANT BINARY_INTEGER := 2;
228 reason_breakpoint CONSTANT BINARY_INTEGER := 3; -- at a breakpoint
229 reason_enter CONSTANT BINARY_INTEGER := 6; -- procedure entry
230 reason_return CONSTANT BINARY_INTEGER := 7; -- procedure return
231 reason_finish CONSTANT BINARY_INTEGER := 8; -- procedure is finished
232 reason_line CONSTANT BINARY_INTEGER := 9; -- reached a new line
233 reason_interrupt CONSTANT BINARY_INTEGER := 10; -- an interrupt occurred
234 reason_exception CONSTANT BINARY_INTEGER := 11; -- an exception was raised
235 reason_exit CONSTANT BINARY_INTEGER := 15; -- interpreter is exiting
236 reason_handler CONSTANT BINARY_INTEGER := 16; -- start exception-handler
237 reason_timeout CONSTANT BINARY_INTEGER := 17; -- a timeout occurred
238 reason_instantiate CONSTANT BINARY_INTEGER := 20; -- instantiation block
239 reason_abort CONSTANT BINARY_INTEGER := 21; -- interpeter is aborting
240 reason_knl_exit CONSTANT BINARY_INTEGER := 25; -- interpreter is exiting
241
242 -- Not yet supported:
243 reason_sql CONSTANT BINARY_INTEGER := 4; -- executing SQL
244 reason_watch CONSTANT BINARY_INTEGER := 14; -- watched value changed
245 reason_rpc CONSTANT BINARY_INTEGER := 18; -- an RPC started
246 reason_unhandled CONSTANT BINARY_INTEGER := 19; -- unhandled exception
247
248 -- Reserved internal values:
249 -- 1 for internal bootstrapping init
250 -- 5 unused
251 reason_ICD_call CONSTANT BINARY_INTEGER := 12;
252 reason_ICD_return CONSTANT BINARY_INTEGER := 13;
253
254 -- Added in Probe v2.4
255 reason_oer_breakpoint CONSTANT BINARY_INTEGER := 26;
256
257 ------------------------------ ERROR CODES ------------------------------
258 -- These values are returned by the various functions that are called in
259 -- the debug session (synchronize, continue, set_breakpoint, etc).
260 --
261 -- (If PL/SQL exceptions worked across client/server and server/server
262 -- boundaries then these would all be exceptions rather than error
263 -- codes.)
264 --
265 -- (Internal note: these map to the PBERR constants)
266 --
267 success CONSTANT binary_integer := 0;
268 -- Statuses returned by GET_VALUE and SET_VALUE:
269 error_bogus_frame CONSTANT binary_integer := 1; -- no such frame
270 error_no_debug_info CONSTANT binary_integer := 2; -- debuginfo missing
271 error_no_such_object CONSTANT binary_integer := 3; -- no such var/parm
272 error_unknown_type CONSTANT binary_integer := 4; -- debuginfo garbled
273 error_indexed_table CONSTANT binary_integer := 18; -- Can't get/set an
274 -- entire collection
275 -- at once
276 error_illegal_index CONSTANT binary_integer := 19; -- illegal collection
277 -- index (V8)
278 error_nullcollection CONSTANT binary_integer := 40; -- collection is
279 -- atomically null
280 -- (V8)
281 error_nullvalue CONSTANT binary_integer := 32; -- value is null
282
283 -- Statuses returned by set_value:
284 error_illegal_value CONSTANT binary_integer := 5; -- constraint vio
285 error_illegal_null CONSTANT binary_integer := 6; -- constraint vio
286 error_value_malformed CONSTANT binary_integer := 7; -- bad value
287 error_other CONSTANT binary_integer := 8; -- unknown error
288 error_name_incomplete CONSTANT binary_integer := 11; -- not a scalar lvalue
289
290 -- Statuses returned by the breakpoint functions:
291 error_illegal_line CONSTANT binary_integer := 12; -- no such line
292 error_no_such_breakpt CONSTANT binary_integer := 13; -- no such breakpoint
293 error_idle_breakpt CONSTANT binary_integer := 14; -- unused breakpoint
294 error_stale_breakpt CONSTANT binary_integer := 15; -- pu changed under
295 -- bpt
296 error_bad_handle CONSTANT binary_integer := 16; -- can't set bpt there
297
298 -- General error codes (returned by many of the dbms_debug routines)
299 error_unimplemented CONSTANT binary_integer := 17; -- NYI functionality
300 error_deferred CONSTANT binary_integer := 27; -- request was deferred
301 -- (currently unused)
302 error_exception CONSTANT binary_integer := 28; -- exception inside Probe
303 error_communication CONSTANT binary_integer := 29; -- generic pipe error
304 error_timeout CONSTANT binary_integer := 31; -- timeout
305
306
307 -- Error codes that only apply to client-side PL/SQL
308 error_pbrun_mismatch CONSTANT binary_integer := 9;
309 error_no_rph CONSTANT binary_integer := 10;
310 error_probe_invalid CONSTANT binary_integer := 20;
311 error_upierr CONSTANT binary_integer := 21;
312 error_noasync CONSTANT binary_integer := 22;
313 error_nologon CONSTANT binary_integer := 23;
314 error_reinit CONSTANT binary_integer := 24;
315 error_unrecognized CONSTANT binary_integer := 25;
316 error_synch CONSTANT binary_integer := 26;
317 error_incompatible CONSTANT binary_integer := 30;
318
319
320 ----------------------------- CURSOR FLAGS -----------------------------
321 -- The 'value' of a cursor returned by GET_VALUE is a string of the
322 -- following form:
323 -- 'flags:<f>, rowcount:<r>' [Probe v2.2 and earlier]
327 -- - The rowcount <r> is the cursor's rowcount.
324 -- 'flags:<f>, rowcount:<r>, knlflags:<k>' [Probe v2.2+ and later]
325 -- which the caller is expected to parse.
326 --
328 --
329 -- - The flags <f> are a bitmask of the following values:
330 -- cflags_open - %OPEN
331 -- cflags_found - %FOUND
332 -- cflags_notfound - %NOTFOUND
333 -- cflags_recursive - recursive cursor
334 -- cflags_uninitialized - uninitialized refcursor
335 -- cflags_refcur_bind - refcursor bind variable
336 -- cflags_first_iter - first iteration of cursor
337 -- cflags_dynamic_sql - this is a dynamic SQL cursor
338 -- cflags_dynamic_open - dynamic OPEN statement
339 -- This is not an exhaustive listing of the possible flags, but the
340 -- other values are used temporarily by the interpreter and can not
341 -- be relied on. Probe does not strip these undocumented values out
342 -- since they are useful internally for debugging the interpreter.
343 -- See more notes in the comments for GET_VALUE.
344 --
345 -- - The flags <k> are a bitmask of UPI flags (the UOPF_* values in
346 -- upidef.h), and are a kind of scratchpad indicating what operations
347 -- the kernel must do on the cursor. For example if they include
348 -- UOPF_EXE then this is a note indicating that the cursor must be
349 -- executed prior to use. These flags are only valid once a cursor
350 -- has been opened - up to that point they will be zero.
351 -- Since they already exist in a public header (rdbms/include/upidef.h),
352 -- they are not duplicated in DBMS_DEBUG.
353 -- They include the following:
354 -- UOPF_PRS parse
355 -- UOPF_EXE execute
356 -- UOPF_FCH fetch
357 -- UOPF_DSL describe select list
358 -- UOPF_DBL describe bind list
359 -- UOPF_BND bind
360 -- UOPF_DFN define
361 -- UOPF_CAN cancel after fetch
362 -- UOPF_FEX exact fetch
363 -- UOPF_OPN open
364 -- UOPF_CLO close
365
366 cflags_open CONSTANT BINARY_INTEGER := 1;
367 cflags_found CONSTANT BINARY_INTEGER := 2;
368 cflags_notfound CONSTANT BINARY_INTEGER := 4;
369 cflags_uninitialized CONSTANT BINARY_INTEGER := 32;
370 cflags_recursive CONSTANT BINARY_INTEGER := 128;
371 cflags_refcur_bind CONSTANT BINARY_INTEGER := 1024;
372 cflags_dynamic_sql CONSTANT BINARY_INTEGER := 2048;
373 cflags_first_iter CONSTANT BINARY_INTEGER := 4096;
374 cflags_dynamic_open CONSTANT BINARY_INTEGER := 16384;
375
376
377 --------------------------- TIMEOUT OPTIONS ---------------------------
378 -- Timeout options for the target session are registered with the
379 -- target session by calling set_timeout_behaviour.
380 --
381 -- retry_on_timeout - Retry. Timeout has no effect. This is like
382 -- setting the timeout to an infinitely large value.
383 --
384 -- continue_on_timeout - Continue execution, using same event flags.
385 --
386 -- nodebug_on_timeout - Turn debug-mode OFF (ie. call debug_off) and
387 -- then continue execution. No more events will be generated
388 -- by this target session unless it is reinitialized by calling
389 -- debug_on.
390 --
391 -- abort_on_timeout - Continue execution, using the abort_execution
392 -- flag, which should cause the program to abort immediately. The
393 -- session remains in debug-mode.
394 --
395 retry_on_timeout CONSTANT BINARY_INTEGER := 0;
396 continue_on_timeout CONSTANT BINARY_INTEGER := 1;
397 nodebug_on_timeout CONSTANT BINARY_INTEGER := 2;
398 abort_on_timeout CONSTANT BINARY_INTEGER := 3;
399
400
401 ------------------------------
402 -- EXCEPTIONS
403 illegal_init EXCEPTION; -- DEBUG_ON called prior to INITIALIZE
404
405 -- Following 5 are raised by procedure self_check.
406 pipe_creation_failure EXCEPTION; -- can't create a secure pipe
407 pipe_send_failure EXCEPTION; -- can't send to the pipe
408 pipe_receive_failure EXCEPTION; -- can't receive from the pipe
409 pipe_datatype_mismatch EXCEPTION; -- datatype mismatch in pipe
410 pipe_data_error EXCEPTION; -- message garbled across pipe
411
412 -- Functionality that is no longer supported. (Some calls in the
413 -- underlying packages are replaced with calls in dbms_debug.)
414 desupported EXCEPTION;
415
416 unimplemented EXCEPTION; -- Not yet implemented.
417 target_error EXCEPTION; -- problem in target session
418
419 no_target_program EXCEPTION; -- target is not running
420
421 ------------------------------
422 -- PUBLIC VARIABLES
423
424 -- The timeout value (used by both sessions).
425 -- The smallest possible timeout is 1 second - if default_timeout is
426 -- set to 0 then a large value (3600) will be used.
427 --
428 default_timeout BINARY_INTEGER := 3600; -- 60 minutes
429
430 -- Whether to dump diagnostic output to the tracefile (for debugging
431 -- Probe). Do not reset this value unless instructed by Oracle personnel.
432 diagnostic_level BINARY_INTEGER := 0;
433 full_diagnostics CONSTANT BINARY_INTEGER := 1;
434
435
436 ------------------------ COMMON Section -----------------------------
440 -------------------------- PROBE_VERSION -------------------------
437 -- These functions/procedures may be called in either the target or
438 -- debug session.
439
441 -- Return the version number of DBMS_DEBUG on the server.
442 --
443 -- PARAMETERS
444 -- major - major version number.
445 -- minor - minor version number. Incremented as functionality is added
446 -- to DBMS_DEBUG.
447 --
448 -- Version history:
449 -- 1.0 was the alpha version of Probe.
450 -- 2.0 was the first version of DBMS_DEBUG.
451 -- 2.1 includes get_indexes and the indexed-table versions of
452 -- print_backtrace, show_breakpoints, and show_source.
453 -- 2.2 contains the 'immediate' version of debug_on, and the
454 -- get/set_value package variable fix for AppServer
455 -- 2.3 execute, plus cflags_* constants
456 -- 2.4 print_instantiations
457 -- target_program_running
458 -- get_encoded_pkgvars_for_client
459 -- set_timeout_behaviour, get_timeout_behaviour
460 -- ping
461 -- set_oer_breakpoint, delete_oer_breakpoint, show_breakpoints
462 -- added oer to runtime_info and added flag info_getOerInfo
463 -- added reason_oer_breakpoint event
464 -- added show_frame_source
465 -- added frame# support in set_breakpoint
466 -- added get_line_map
467 -- 2.5 [8829891] new overloadings for get_encoded_pkgvars_for_client and
468 -- get_encoded_stack_for_client
469 --
470 PROCEDURE probe_version(major out BINARY_INTEGER,
471 minor out BINARY_INTEGER);
472
473 ------------------------------ SELF_CHECK ------------------------------
474 -- Perform an internal consistency check.
475 -- If self_check does not return successfully then an incorrect version
476 -- of DBMS_DEBUG was probably installed on this server. The solution
477 -- is to install the correct version.
478 -- (pbload.sql loads DBMS_DEBUG and the other relevant packages).
479 --
480 -- Self_check also runs a communications test (to ensure that the Probe
481 -- processes will be able to communicate).
482 --
483 -- PARAMETERS
484 -- timeout - Timeout to use for the communication test. (Default
485 -- 60 seconds).
486 --
487 -- Exceptions
488 -- OER-6516 - Probe version is inconsistent
489 -- pipe_creation_failure - couldn't create a pipe
490 -- pipe_send_failure - couldn't write data to the pipe
491 -- pipe_receive_failure - couldn't read data from the pipe
492 -- pipe_datatype_mismatch - datatype in the pipe was wrong
493 -- pipe_data_error - data got garbled in the pipe
494 --
495 -- All of these exceptions are FATAL. They indicate a serious problem
496 -- with Probe that will prevent it from working correctly.
497 --
498 PROCEDURE self_check(timeout IN binary_integer := 60);
499
500 ------------------------------ SET_TIMEOUT ------------------------------
501 -- Set the timeout value.
502 --
503 -- PARAMETERS
504 -- timeout - the timeout value to set. If 0, then uses default_timeout
505 --
506 -- RETURNS
507 -- the new timeout value.
508 --
509 FUNCTION set_timeout(timeout BINARY_INTEGER) RETURN BINARY_INTEGER;
510
511 ------------------------- SET_DIAGNOSTIC_LEVEL -------------------------
512 -- Set diagnostic output to a given level. Similar to the 'diagnostics'
513 -- parameter to initialize() and attach_session.
514 -- Diagnostic output goes to the rdbms tracefile. Ordinarily the
515 -- diagnostic level should remain at 0.
516 --
517 -- PARAMETERS
518 -- dlevel - the diagnostic level to switch to
519 --
520 PROCEDURE set_diagnostic_level(dlevel IN BINARY_INTEGER);
521
522 ------------------------ TARGET SESSION Section ------------------------
523 --
524 -- These functions and procedures are to be executed in the target session
525 -- (the session that is to be debugged).
526 --
527
528 ----------------------- INITIALIZE ---------------------------
529 -- Initializes the target session by registering a debugID.
530 --
531 -- PARAMETERS
532 -- debug_session_id - A session-id name to identify the target session.
533 -- If null, a unique ID will be generated.
534 -- diagnostics - whether to dump diagnostic output to the tracefile
535 -- 0 = no output, 1 = minimal output
536 -- debug_role - An additional role to use for debugger privilege
537 -- checks. Will not affect SQL or PL/SQL execution.
538 -- debug_role_pwd - Password for the debug_role, if needed.
539 --
540 -- RETURNS
541 -- the newly-registered debug-session-id (debugID)
542 --
543 --
544 --
545 -- We do not support use of DBMS_DEBUG and the JDWP-based debugging
546 -- interface simultaneously. This call will fail with an ORA-30677
547 -- if the session is currently being debugged with the JDWP-based
548 -- debugging interface, and if this call does succeed, any further use
549 -- of the JDWP-based interface to debug this session will instead be
550 -- disallowed.
551 --
552 -- As of 10i, a new privilege model for debugging will control use of
553 -- DBMS_DEBUG:
554 --
558 -- role is specified but the password doesn't match, the calling user
555 -- This call will only succeed if either the caller or the specified
556 -- debug role carries the DEBUG CONNECT SESSION privilege. Otherwise an
557 -- ORA-1031 will be raised. Other exceptions are also possible if a debug
559 -- hasn't been granted the role, or the role is application-enabled and
560 -- this call is not coming from within the role-enabling package.
561 --
562 -- CREATE ANY PROCEDURE privilege no longer affects the visibility of
563 -- routines through the debugger. An new per-object (package, schema-level
564 -- procedure or function, etc.) DEBUG privilege has been introduced, with
565 -- a corresponding DEBUG ANY PROCEDURE variant. These are required instead
566 -- in order to see routines owned by users other than the session's login
567 -- user.
568 --
569 -- Authentication of the debug role and the check for DEBUG CONNECT SESSION
570 -- privilege will be done in the context of the caller to this routine -
571 -- if the caller is a definer's rights routine or has been called from one,
572 -- only privileges granted to the defining user, the debug role, or PUBLIC
573 -- will be used to check for DEBUG CONNECT SESSION. If this call is from
574 -- within a definer's rights routine, the debug role, if specified, must
575 -- be one that has been granted to that definer, but it need not also have
576 -- been granted to the session login user, nor must it be actually enabled
577 -- in the calling session at the time this call is made.
578 --
579 -- The checks made by the debugger after this call is made, looking for
580 -- the DEBUG privilege on individual procedures, will be done in the
581 -- context of the session's login user, the roles that were enabled at
582 -- session level at the moment this call was made (even if those roles
583 -- weren't available within a definer's rights environment that called
584 -- here), and the debug role.
585 --
586 FUNCTION initialize(debug_session_id IN VARCHAR2 := NULL,
587 diagnostics IN BINARY_INTEGER := 0,
588 debug_role IN VARCHAR2 := NULL,
589 debug_role_pwd IN VARCHAR2 := NULL)
590 RETURN VARCHAR2;
591
592 ----------------------- DEBUG_ON -----------------------------
593 -- Mark the target session so that all PL/SQL is executed in
594 -- debug mode. This must be done before any debugging can take
595 -- place.
596 --
597 -- PARAMETERS
598 -- no_client_side_plsql_engine - whether this debugging session
599 -- is standalone or results from a client-side PL/SQL session.
600 -- (Client-side PL/SQL uses different entrypoints into the
601 -- server, and therefore has restricted use of dbms_debug.)
602 -- immediate - whether to switch into debug mode immediately, or
603 -- to wait until the call has completed. If TRUE, then a
604 -- debug session will be required in order to complete the call.
605 -- This parameter was added in Probe V2.2.
606 --
607 -- NOTES
608 -- If in doubt, use the default parameter values.
609 --
610 PROCEDURE debug_on(no_client_side_plsql_engine BOOLEAN := TRUE,
611 immediate BOOLEAN := FALSE);
612
613 ----------------------- DEBUG_OFF ----------------------------
614 -- Notify the target session that debugging is no longer to take
615 -- place in that session.
616 -- It is not necessary to call this function before logging the
617 -- session off.
618 --
619 -- NOTES
620 -- The server does not handle this entrypoint specially. Therefore
621 -- it will attempt to debug this entrypoint.
622 --
623 PROCEDURE debug_off;
624
625
626 --------------------- SET_TIMEOUT_BEHAVIOUR ------------------
627 -- Tell Probe what to do with the target session when a timeout
628 -- occurs.
629 --
630 -- VERSION
631 -- Probe v2.4
632 --
633 -- PARAMETERS
634 -- behaviour - one of the following (see descriptions above):
635 -- retry_on_timeout
636 -- continue_on_timeout
637 -- nodebug_on_timeout
638 -- abort_on_timeout
639 --
640 -- EXCEPTIONS
641 -- unimplemented - the requested behaviour is not recognized
642 --
643 -- NOTES
644 -- The default behaviour (if this procedure is not called)
645 -- is continue_on_timeout, since it allows a debugger client
646 -- to re-establish control (at the next event) but does not
647 -- cause the target session to hang indefinitely.
648 --
649 PROCEDURE set_timeout_behaviour(behaviour IN PLS_INTEGER);
650
651
652 --------------------- GET_TIMEOUT_BEHAVIOUR ------------------
653 -- Return the current timeout behaviour.
654 --
655 -- VERSION
656 -- Probe v2.4
657 --
658 FUNCTION get_timeout_behaviour RETURN BINARY_INTEGER;
659
660
661 ------------------------- DEBUG SESSION Section -------------------------
662 --
663 -- These functions and procedures are to be executed in the debug session
664 -- only.
665 --
666
667 ----------------------- ATTACH_SESSION -----------------------
668 -- Notify the debug session about the target program.
669 --
670 -- PARAMETERS
671 -- debug_session_id - the debugID from a call to initialize()
675 PROCEDURE attach_session(debug_session_id IN VARCHAR2,
672 -- diagnostics - generate diagnostic output (in the rdbms
673 -- tracefile)? 0 = no output, 1 = minimal output
674 --
676 diagnostics IN BINARY_INTEGER := 0);
677
678
679 ------------------------------ SYNCHRONIZE ------------------------------
680 -- This function:
681 -- 1. Waits until the target program signals an event.
682 -- 2. Calls get_runtime_info
683 --
684 -- PARAMETERS
685 -- run_info - structure in which to write information about the program
686 -- By default this will include information about what program
687 -- is executing and at which line execution has paused.
688 -- info_requested - optional bit-field in which to request information
689 -- other than the default (which is info_getStackDepth +
690 -- info_getLineInfo). 0 means that no information is requested.
691 --
692 -- RETURNS
693 -- success
694 -- error_timeout - timed out before the program started execution
695 -- error_communication - other communication error
696 --
697 FUNCTION synchronize(run_info OUT runtime_info,
698 info_requested IN BINARY_INTEGER := NULL)
699 RETURN BINARY_INTEGER;
700
701 -------------------------- SHOW_FRAME_SOURCE ----------------------------
702 -- Get frame source. The only time where this really has to be used
703 -- is when backtrace shows anonymous unit is executing at a given
704 -- frame position and source is required for viewing and possibly
705 -- setting a breakpoint.
706 --
707 -- If frame number is top of the stack and it's an anonymous block
708 -- then show_source can also be used.
709 --
710 -- If it's a stored PLSQL package/function/procedure then use SQL
711 -- as described in the comment to show_source below.
712 --
713 -- PARAMETERS
714 -- first_line - line number of first line to fetch. (PL/SQL programs
715 -- always start at line 1, and have no holes.)
716 -- last_line - line number of last line to fetch. No lines will be
717 -- fetched past the end of the program.
718 -- source - the resulting table, indexed by line-number (starting
719 -- with first_line). On error, the table will be empty.
720 -- frame_num - 1-based frame number
721 --
722 PROCEDURE show_frame_source(first_line IN BINARY_INTEGER,
723 last_line IN BINARY_INTEGER,
724 source IN OUT NOCOPY vc2_table,
725 frame_num IN BINARY_INTEGER);
726
727 ------------------------------ SHOW_SOURCE ------------------------------
728 -- The best way to get the source code (for a program that is being
729 -- executed) is to use SQL - ie. select from all_source, using
730 -- the owner, name and line# in the program_info record:
731 --
732 -- SELECT text INTO <buffer> FROM all_source
733 -- WHERE owner = info.Program.Owner
734 -- AND name = info.Program.Name
735 -- AND line = info.Line#;
736 --
737 -- This wont work for non-persistent programs however (anonymous blocks
738 -- and trigger invocation blocks, for example) - in that case you can
739 -- call show_source. There are two flavours - one returns an indexed
740 -- table of source lines and the other returns a packed (and formatted)
741 -- buffer.
742 --
743 -- PARAMETERS
744 -- first_line - line number of first line to fetch. (PL/SQL programs
745 -- always start at line 1, and have no holes.)
746 -- last_line - line number of last line to fetch. No lines will be
747 -- fetched past the end of the program.
748 -- source - the resulting table, indexed by line-number (starting
749 -- with first_line). On error, the table will be empty.
750 --
751 PROCEDURE show_source(first_line IN BINARY_INTEGER,
752 last_line IN BINARY_INTEGER,
753 source IN OUT NOCOPY vc2_table);
754
755 -- VERSION
756 -- Probe v2.1
757 --
758 -- This second overloading of show_source returns the source in a
759 -- formatted buffer, complete with line-numbers. It is faster than
760 -- the indexed table version, but it doesn't guarantee to fetch all
761 -- the source.
762 -- If the source doesn't fit in bufferlength (buflen) then additional
763 -- pieces can be retrieved using the 'get_more_source' procedure
764 -- ('pieces' will return the additional number of pieces that need to
765 -- be retrieved).
766 --
767 -- PARAMETERS
768 -- first_line - smallest line-number to print
769 -- last_line - largest line-number to print
770 -- window - 'window' of lines - the number of lines around the
771 -- current source line.
772 -- print_arrow - non-zero means to print an arrow before the current line
773 -- buffer - buffer in which to place the source listing
774 -- buflen - length of buffer
775 -- pieces - set to non-zero if not all the source could be placed
776 -- into the given buffer
777 --
778 PROCEDURE show_source(first_line IN BINARY_INTEGER,
779 last_line IN BINARY_INTEGER,
783 buflen IN BINARY_INTEGER,
780 window IN BINARY_INTEGER,
781 print_arrow IN BINARY_INTEGER,
782 buffer IN OUT VARCHAR2,
784 pieces OUT BINARY_INTEGER);
785
786 ----------------------- GET_MORE_SOURCE -------------------
787 -- When source doesn't fit in buffer provided in the "show_source"
788 -- procedure, this procedure provides additional source.
789 PROCEDURE get_more_source(buffer IN OUT VARCHAR2,
790 buflen IN BINARY_INTEGER,
791 piece# IN BINARY_INTEGER);
792
793
794 ---------------------- PRINT_BACKTRACE -------------------
795 -- Print a backtrace listing of the current execution stack.
796 -- Should only be called if a program is currently executing.
797 --
798 -- PARAMETERS
799 -- listing - A formatted character buffer with embedded newlines
800 --
801 PROCEDURE print_backtrace(listing IN OUT VARCHAR2);
802
803 -- VERSION
804 -- Probe v2.1
805 --
806 -- PARAMETERS
807 -- backtrace - 1-based indexed table of backtrace entries. The
808 -- currently-executing procedure is the last entry in the
809 -- table (ie. the frame numbering is the same as that used by
810 -- get_value). Entry 1 is the oldest procedure on the stack.
811 --
812 PROCEDURE print_backtrace(backtrace OUT backtrace_table);
813
814 ----------------------- CONTINUE --------------------------
815 -- Continue execution of the target program.
816 --
817 -- This function:
818 -- 1. Passes the given breakflags (a mask of the events that are
819 -- of interest) to Probe in the target process.
820 -- 2. Tells Probe to continue execution of the target process.
821 -- 3. Waits until the target process either runs to completion or
822 -- signals an event.
823 -- 4. If info_requested is not 0 and program has not terminated,
824 -- calls get_runtime_info.
825 --
826 -- PARAMETERS
827 -- run_info - information about the new state of the program
828 -- breakflags - mask of events that are of interest
829 -- info_requested - what information should be returned in 'run_info'
830 -- when the program stops. See 'information flags'
831 -- 0 means no information. Null means default info.
832 -- RETURNS
833 -- success
834 -- error_timeout - timeout while waiting for target session
835 -- error_communication - other communication error
836 --
837 -- HANDLING TIMEOUTS
838 -- If this function returns with a timeout then the target session
839 -- either terminated abnormally or is still running. If it is still
840 -- running, and the client wishes to continue waiting for it, then
841 -- 'synchronize' should be called.
842 --
843 -- One way to determine whether a session is alive is to use
844 -- dbms_session.is_session_alive, which takes as a parameter the
845 -- uniqueID for the session (which may be obtained via
846 -- dbms_session.unique_session_id). Note that the uniqueID and
847 -- the debugID are not necessarily the same, for security reasons,
848 -- so Probe does not automatically check for target session death
849 -- when a timeout occurs.
850 --
851 FUNCTION continue(run_info IN OUT runtime_info,
852 breakflags IN BINARY_INTEGER,
853 info_requested IN BINARY_INTEGER := null)
854 RETURN BINARY_INTEGER;
855
856 -------------------------- SET_BREAKPOINT ----------------------
857 -- Set a breakpoint in a program unit, which persists for the current
858 -- session. Execution will pause if the target program reaches the
859 -- breakpoint.
860 --
861 -- PARAMETERS
862 -- program Information about the program unit in which the
863 -- breakpoint is to be set.
864 -- (In version 2.1 and later, the namespace, name, owner,
865 -- and dblink may be set to NULL, in which case the
866 -- breakpoint will be placed in the currently-executing
867 -- program unit.)
868 -- (In version 2.4 and later namespace can be set to
869 -- namespace_none and name to a frame number to set
870 -- a breakpoint in one of the currently executing frames)
871 -- line# The line at which the breakpoint is to be set.
872 -- breakpoint# On successful completion, will contain the unique
873 -- breakpoint number by which to refer to the breakpoint.
874 -- fuzzy Only applicable if there is no executable code at
875 -- the specified line:
876 -- 0 means return error_illegal_line.
877 -- 1 means search forward for an adjacent line at which
878 -- to place the breakpoint.
879 -- -1 means search backwards for an adjacent line at
880 -- which to place the breakpoint.
881 -- iterations The number of times to wait before signalling this
882 -- breakpoint.
883 --
884 -- RETURNS
885 -- success
886 -- error_illegal_line - can't set a breakpoint at that line
887 -- error_bad_handle - no such program unit exists
891 --
888 --
889 -- RESTRICTIONS/BUGS
890 -- 'fuzzy' and 'iterations' not yet implemented.
892 FUNCTION set_breakpoint(program IN program_info,
893 line# IN BINARY_INTEGER,
894 breakpoint# OUT BINARY_INTEGER,
895 fuzzy IN BINARY_INTEGER := 0,
896 iterations IN BINARY_INTEGER := 0)
897 RETURN BINARY_INTEGER;
898
899 -------------------------- DELETE_BREAKPOINT ----------------------
900 -- Deletes a breakpoint.
901 --
902 -- PARAMETERS
903 -- breakpoint - a breakpoint number returned by SET_BREAKPOINT
904 --
905 -- RETURNS
906 -- success
907 -- error_no_such_breakpt - no such breakpoint exists
908 -- error_idle_breakpt - breakpoint was already deleted
909 -- error_stale_breakpt - the program unit was redefined since the
910 -- breakpoint was set
911 --
912 FUNCTION delete_breakpoint(breakpoint IN BINARY_INTEGER)
913 RETURN BINARY_INTEGER;
914
915
916 ------------------------- SET_OER_BREAKPOINT ----------------------
917 -- Set a breakpoint on an OER. The breakpoint persists for the
918 -- session (or until deleted), as with code breakpoints.
919 --
920 -- VERSION
921 -- Probe v2.4
922 --
923 -- PARAMETERS
924 -- oer - the OER (a 4-byte positive number)
925 --
926 -- RETURNS
927 -- success
928 --
929 -- NOTES
930 -- Less functionality is supported on OER breakpoints than on
931 -- code breakpoints. In particular, note that:
932 -- 1. No 'breakpoint number' is returned - the number of the OER
933 -- is used instead. Thus it is impossible to set duplicate
934 -- breakpoints on a given OER (it is a no-op).
935 -- 2. It is not possible to disable an OER breakpoint (although
936 -- clients are free to simulate this by deleting it).
937 -- 3. OER breakpoints are deleted via delete_oer_breakpoint.
938 --
939 FUNCTION set_oer_breakpoint(oer IN PLS_INTEGER) RETURN PLS_INTEGER;
940
941
942 ---------------------- DELETE_OER_BREAKPOINT ----------------------
943 -- Delete an OER breakpoint.
944 --
945 -- VERSION
946 -- Probe v2.4
947 --
948 -- PARAMETERS
949 -- oer - the OER (positive 4-byte number) to delete
950 --
951 -- RETURNS
952 -- success
953 -- error_no_such_breakpt - no such OER breakpoint exists
954 --
955 FUNCTION delete_oer_breakpoint(oer IN PLS_INTEGER) RETURN PLS_INTEGER;
956
957
958 -------------------------- DISABLE_BREAKPOINT ----------------------
959 -- With this procedure the breakpoint will still be there, but not be
960 -- active. After disabling the breakpoint needs to be enabled to make it
961 -- active
962 --
963 -- PARAMETERS
964 -- breakpoint - a breakpoint number returned by SET_BREAKPOINT
965 --
966 -- RETURNS
967 -- success
968 -- error_no_such_breakpt - no such breakpoint exists
969 -- error_idle_breakpt - breakpoint was already deleted
970 -- error_stale_breakpt - the program unit was redefined since the
971 -- breakpoint was set
972 --
973 FUNCTION disable_breakpoint(breakpoint IN BINARY_INTEGER)
974 RETURN BINARY_INTEGER;
975
976 -------------------------- ENABLE_BREAKPOINT ----------------------
977 -- Reverse of disabling. This procedure "activates" an exsiting breakpoint
978 --
979 -- PARAMETERS
980 -- breakpoint - a breakpoint number returned by SET_BREAKPOINT
981 --
982 -- RETURNS
983 -- success
984 -- error_no_such_breakpt - no such breakpoint exists
985 -- error_idle_breakpt - breakpoint was already deleted
986 -- error_stale_breakpt - the program unit was redefined since the
987 -- breakpoint was set
988 --
989 FUNCTION enable_breakpoint(breakpoint IN BINARY_INTEGER)
990 RETURN BINARY_INTEGER;
991
992 -------------------------- SHOW_BREAKPOINTS ----------------------
993 -- Return a listing of the current breakpoints.
994 --
995 -- PARAMETERS
996 -- listing - a formatted buffer (including newlines) of the breakpoints
997 PROCEDURE show_breakpoints(listing IN OUT VARCHAR2);
998
999 -- VERSION
1000 -- Probe v2.1
1001 --
1002 -- PARAMETERS
1003 -- listing - indexed table of breakpoint entries. The
1004 -- breakpoint number is indicated by the index into the table.
1005 -- Breakpoint numbers start at 1 and are reused when deleted.
1006 --
1007 PROCEDURE show_breakpoints(listing OUT breakpoint_table);
1008
1009
1010 -- VERSION
1011 -- Probe v2.4
1012 --
1013 -- PARAMETERS
1014 -- code_breakpoints - indexed table of breakpoint entries, indexed
1015 -- by breakpoint number (starting at 1).
1016 -- oer_breakpoints - indexed table of OER breakpoints, indexed by
1017 -- OER.
1018 --
1019 PROCEDURE show_breakpoints(code_breakpoints OUT breakpoint_table,
1020 oer_breakpoints OUT oer_table);
1021
1022
1026 -- PARAMETERS
1023 ------------------------------- GET_VALUE -------------------------------
1024 -- Get a value from the currently-executing program.
1025 --
1027 -- variable_name the name of the variable or parameter
1028 -- frame# the frame in which it lives (0 means the current
1029 -- procedure)
1030 -- scalar_value its value
1031 -- format an optional date format to use, if meaningful.
1032 --
1033 -- RETURNS
1034 -- success
1035 -- error_bogus_frame - frame# does not exist
1036 -- error_no_debug_info - entrypoint has no debug information
1037 -- error_no_such_object - variable_name does not exist in frame#
1038 -- error_unknown_type - the type information in the debug information
1039 -- is illegible
1040 -- error_nullvalue - value is null
1041 --
1042 -- NOTES
1043 -- If the variable is a cursor, then a special string value is returned,
1044 -- which the caller is expected to parse. See the comments at the
1045 -- 'Cursor flags' section above.
1046 --
1047 -- get_value and set_value now support bind names. Bind names must be
1048 -- put in quotes and capitalized. Note that trigger binds have
1049 -- qualified names, i.e. ":NEW" is not a valid bind, while ":NEW.CLMN"
1050 -- is valid. Generally, only referenced binds are available using
1051 -- probe. IN and IN-OUT binds can be get_value-ed, OUT and IN-OUT
1052 -- binds can be set using set_value. The only exception is trigger
1053 -- binds: :NEW.COLUMN and :OLD.COLUMN are created for all columns
1054 -- for get_value (set_value still can be used only on binds modified
1055 -- by the trigger code.
1056 --
1057 -- BUGS
1058 -- - There are situations when the cursor flags may appear to be
1059 -- incorrect: one common case is recursive cursors (ie. a procedure
1060 -- containing a cursor, where the procedure calls itself recursively).
1061 -- On return from the recursive call the cursor flags are *not*
1062 -- restored, even though the interpreter behaves correctly.
1063 -- The difficulty is that both PL/SQL and the kernel maintain their
1064 -- own cursor-caches, and it is difficult for Probe to follow the
1065 -- mapping in these situations.
1066 -- This will be fixed in a later release.
1067 --
1068 FUNCTION get_value(variable_name IN VARCHAR2,
1069 frame# IN BINARY_INTEGER,
1070 scalar_value OUT VARCHAR2,
1071 format IN VARCHAR2 := NULL)
1072 RETURN BINARY_INTEGER;
1073
1074 --
1075 -- This form of get_value is for fetching package variables.
1076 -- Instead of a frame#, it takes a handle, which describes the package
1077 -- containing the variable.
1078 --
1079 -- VERSION
1080 -- Probe v2.2
1081 --
1082 -- PARAMETERS
1083 -- (See description above for the other parameters.)
1084 -- handle - package description. The 'Name,' 'Owner,' and Namespace
1085 -- fields must be initialized appopriately.
1086 --
1087 -- RETURNS
1088 -- error_no_such_object if:
1089 -- 1. the package does not exist
1090 -- 2. the package is not instantiated
1091 -- 3. the user does not have privileges to debug the package
1092 -- 4. the object does not exist in the package
1093 --
1094 -- EXAMPLE
1095 -- Given a package PACK in schema SCOTT, containing variable VAR,
1096 -- do the following to get its value:
1097 --
1098 -- DECLARE
1099 -- handle dbms_debug.program_info;
1100 -- resultbuf VARCHAR2(500);
1101 -- BEGIN
1102 -- handle.Owner := 'SCOTT';
1103 -- handle.Name := 'PACK';
1104 -- handle.namespace := dbms_debug.namespace_pkgspec_or_toplevel;
1105 -- retval := dbms_debug.get_value('VAR', handle, resultbuf, NULL);
1106 -- END;
1107 --
1108 FUNCTION get_value(variable_name IN VARCHAR2,
1109 handle IN program_info,
1110 scalar_value OUT VARCHAR2,
1111 format IN VARCHAR2 := NULL)
1112 RETURN BINARY_INTEGER;
1113
1114 -------------------------- SET_VALUE ----------------------------
1115 -- Set a value in the currently-executing program.
1116 --
1117 -- PARAMETERS
1118 -- frame# - the frame in which the value is to be set (0 means the
1119 -- currently executing frame.
1120 -- assignment_statement - an assignment statement (which must be legal
1121 -- PL/SQL) to execute in order to set the value.
1122 -- For example, 'x := 3;'
1123 -- Note that only scalar values are supported in
1124 -- this release - the right hand side of the
1125 -- assignment statement must be a scalar.
1126 --
1127 -- NOTES see notes on bind variables in get_value
1128 --
1129 -- RETURNS
1130 -- success
1131 -- error_illegal_value - constraint violation
1132 -- error_illegal_null - constraint violation (object is 'not null')
1133 -- error_value_malformed - value is not a scalar
1134 -- error_name_incomplete - the assignment statement does not resolve to
1135 -- a scalar. For example 'x := 3;', if x is
1136 -- a record.
1137 -- error_other
1141 RETURN BINARY_INTEGER;
1138 --
1139 FUNCTION set_value(frame# IN binary_integer,
1140 assignment_statement IN varchar2)
1142
1143 -- This form sets the value of a package variable.
1144 --
1145 -- VERSION
1146 -- Probe v2.2
1147 --
1148 -- RETURNS
1149 -- error_no_such_object if:
1150 -- 1. the package does not exist
1151 -- 2. the package is not instantiated
1152 -- 3. the user does not have privileges to debug the package
1153 -- 4. the object does not exist in the package
1154 --
1155 -- In some cases the PL/SQL compiler uses temporaries to access package
1156 -- variables, and Probe does not guarantee to update such temporaries.
1157 -- So the possibility exists (although it is unlikely) for the user to
1158 -- update a package variable and the new value not 'take effect' for a
1159 -- line or two.
1160 --
1161 -- EXAMPLE
1162 -- To set the value of SCOTT.PACK.var to 6:
1163 --
1164 -- DECLARE
1165 -- handle dbms_debug.program_info;
1166 -- BEGIN
1167 -- handle.Owner := 'SCOTT';
1168 -- handle.Name := 'PACK';
1169 -- handle.namespace := dbms_debug.namespace_pkgspec_or_toplevel;
1170 -- retval := dbms_debug.set_value(handle, 'var := 6;');
1171 -- END;
1172 --
1173 FUNCTION set_value(handle IN program_info,
1174 assignment_statement IN varchar2)
1175 RETURN BINARY_INTEGER;
1176
1177 -------------------------------- ABORT --------------------------------
1178 -- Abort the currently-executing program.
1179 --
1180 -- NOT YET SUPPORTED. To abort a program call 'continue' with
1181 -- execution flags 'abort_execution'.
1182 --
1183 FUNCTION abort return BINARY_INTEGER;
1184
1185 -------------------------- DETACH_SESSION ----------------------
1186 -- Detach from the currently attached session - ie. stop debugging
1187 -- the target program. This procedure may be called at any time,
1188 -- but it does not notify the target session that the debug session
1189 -- is detaching itself, and it does not abort execution of the target
1190 -- session. Therefore care should be taken to ensure that the target
1191 -- session does not hang itself.
1192 --
1193 PROCEDURE detach_session;
1194
1195 --------------------------- GET_RUNTIME_INFO ---------------------------
1196 -- This function returns information about the current program. It is
1197 -- only needed if the 'info_requested' parameter to synchronize or
1198 -- continue was set to 0.
1199 --
1200 -- Currently only used by client-side PL/SQL.
1201 --
1202 -- PARAMETERS
1203 -- info_requested - bitmask of the information to fetch. 0 means
1204 -- nothing, null means 'default information.'
1205 -- run_info - location in which to stash the requested information.
1206 --
1207 -- RETURNS
1208 -- success
1209 -- error_timeout - pipe timed out
1210 -- error_communication - other communication error
1211 --
1212 FUNCTION get_runtime_info(info_requested IN BINARY_INTEGER,
1213 run_info OUT runtime_info)
1214 return BINARY_INTEGER;
1215
1216 ------------------------------ GET_INDEXES ------------------------------
1217 -- Given a name (of a variable or parameter), return the set of its
1218 -- indexes if it is an indexed table. Error if it is not an indexed
1219 -- table.
1220 --
1221 -- VERSION
1222 -- Probe v2.1
1223 --
1224 -- PARAMETERS
1225 -- varname - name of the variable to get index information about
1226 -- frame# - number of frame in which the variable/parameter resides.
1227 -- Pass in NULL if you want a package variable.
1228 -- handle - package description (if object is a package variable)
1229 -- entries - 1-based table of the indexes. If non-null, then
1230 -- entries(1) contains the first index of the table,
1231 -- entries(2) contains the second index, etc.
1232 --
1233 -- RETURNS
1234 -- error_no_such_object if varname is not an indexed table.
1235 --
1236 FUNCTION get_indexes(
1237 varname IN VARCHAR2,
1238 frame# IN BINARY_INTEGER,
1239 handle IN program_info,
1240 entries OUT index_table
1241 ) RETURN BINARY_INTEGER;
1242
1243 --------------------- GET_ENCODED_STACK_FOR_CLIENT ---------------------
1244 --
1245 -- ***********************************************************************
1246 -- ** This function is only usable if the caller is client-side PL/SQL. **
1247 -- ** If you do not have client-side PL/SQL then you cannot use it. **
1248 -- ***********************************************************************
1249 --
1250 -- Return an encoded form of one or more stack frames. Only useful if
1251 -- the caller is client-side PL/SQL, since the decoder is built into the
1252 -- PL/SQL engine.
1253 --
1254 -- [8829891] tidl_buf may contain multibyte character data in the server-
1255 -- side character set. This data should not be translated when crossing
1256 -- from server to client. Thus, this data should be in RAW form. The
1257 -- VARCHAR2 version of this function has been preserved for compatibility
1258 -- reasons. The final two parameters are reordered because we can't
1259 -- overload on VARCHAR2 vs. RAW. This overloading is new with Probe 2.5.
1263 -- frame_count - number of frames to fetch
1260 --
1261 -- PARAMETERS
1262 -- start_frame
1264 -- flags - currently unused
1265 -- max_string_length - truncate strings at this value (NYI)
1266 -- max_index_values - only fetch this many index table elements (NYI)
1267 -- pbrun_version - client version
1268 -- tidl_buf - buffer in which to place encoded TIDL
1269 -- tidl_version - version-number of the generated TIDL
1270 --
1271 PROCEDURE get_encoded_stack_for_client(
1272 start_frame IN BINARY_INTEGER,
1273 frame_count IN BINARY_INTEGER,
1274 flags IN BINARY_INTEGER,
1275 max_string_length IN BINARY_INTEGER,
1276 max_index_values IN BINARY_INTEGER,
1277 pbrun_version IN BINARY_INTEGER,
1278 tidl_version OUT BINARY_INTEGER,
1279 tidl_buf IN OUT RAW
1280 );
1281 PROCEDURE get_encoded_stack_for_client(
1282 start_frame IN BINARY_INTEGER,
1283 frame_count IN BINARY_INTEGER,
1284 flags IN BINARY_INTEGER,
1285 max_string_length IN BINARY_INTEGER,
1286 max_index_values IN BINARY_INTEGER,
1287 pbrun_version IN BINARY_INTEGER,
1288 tidl_buf IN OUT VARCHAR2,
1289 tidl_version OUT BINARY_INTEGER
1290 );
1291
1292 -- VERSION
1293 -- Probe v2.4 (VARCHAR2 overloading)/ Probe v2.5 (RAW overloading)
1294 --
1295 -- Get_encoded_pkgvars_for_client is similar to the previous
1296 -- procedure, but with the following additional parameters:
1297 -- handle - description of package
1298 -- status - error-code, in case package doesn't exist, doesn't
1299 -- contain debug info, or hasn't been instantiated
1300 --
1301 PROCEDURE get_encoded_pkgvars_for_client(
1302 handle IN program_info,
1303 flags IN BINARY_INTEGER,
1304 pbrun_version IN BINARY_INTEGER,
1305 status IN OUT BINARY_INTEGER,
1306 tidl_version OUT BINARY_INTEGER,
1307 tidl_buf IN OUT RAW
1308 );
1309 PROCEDURE get_encoded_pkgvars_for_client(
1310 handle IN program_info,
1311 flags IN BINARY_INTEGER,
1312 pbrun_version IN BINARY_INTEGER,
1313 status IN OUT BINARY_INTEGER,
1314 tidl_buf IN OUT VARCHAR2,
1315 tidl_version OUT BINARY_INTEGER
1316 );
1317
1318
1319 ---------------------------- EXECUTE ------------------------------
1320 -- Execute some SQL or PL/SQL code in target session. Program is
1321 -- assumed to be suspended in the target session awaiting commands.
1322 --
1323 -- VERSION
1324 -- Probe v2.3
1325 --
1326 -- PARAMETERS
1327 -- what - the SQL or PL/SQL source to execute
1328 -- frame# - the context in which to execute it.
1329 -- Only -1 (global context) is supported at this time.
1330 -- bind_results - whether the source wants to bind results (0=no, 1=yes).
1331 -- Binding is to 'results' (see next parameter), and is done
1332 -- only once.
1333 -- results - a collection where output may be placed (see bind_results).
1334 -- errm - error message, if an error occurred. Otherwise null.
1335 --
1336 -- EXCEPTIONS
1337 -- unimplemented - frame# other than -1
1338 -- target_error - a communication problem of some kind
1339 --
1340 -- RESTRICTIONS
1341 -- 1. User's code ('what') must allocate space in 'results' (ie. call
1342 -- results.EXTEND) either implicitly or explicitly prior to use.
1343 -- 2. Rows in 'results' are expected to be adjacent - 'what' should not
1344 -- delete interior rows.
1345 -- 3. User's code runs with the privileges of the current user (in the
1346 -- program that is suspended), and name-resolution is done in the
1347 -- context of that user.
1348 -- 4. If 'bind_results' is 1, then 'results' will always be a non-null
1349 -- collection on successful termination. This is true even if 'what'
1350 -- nulls it out.
1351 --
1352 -- SAMPLE USE:
1353 -- 1. SQL:
1354 -- DECLARE
1355 -- coll sys.dbms_debug_vc2coll; -- results (unused)
1356 -- errm VARCHAR2(100);
1357 -- BEGIN
1358 -- dbms_debug.execute('insert into emp(ename,empno,deptno) ' ||
1359 -- 'values(''LJE'', 1, 1)',
1360 -- -1, 0, coll, errm);
1361 -- IF (errm IS NOT NULL) THEN
1362 -- :oops := errm;
1363 -- END IF;
1364 -- END;
1365 --
1366 -- Note that there is NO SEMI-COLON at the end of the insert
1367 -- statement. Otherwise the kernel will return ORA-00911 (invalid
1368 -- character).
1369 --
1370 -- 2. PL/SQL (with autonomous transaction):
1371 -- DECLARE
1372 -- coll sys.dbms_debug_vc2coll; -- results (unused)
1373 -- errm VARCHAR2(100);
1374 -- BEGIN
1375 -- dbms_debug.execute(
1376 -- 'DECLARE PRAGMA autonomous_transaction; ' ||
1377 -- 'BEGIN ' ||
1378 -- ' insert into emp(ename, empno, deptno) ' ||
1379 -- ' values(''LJE'', 1, 1); ' ||
1383 -- END;
1380 -- ' COMMIT; ' ||
1381 -- 'END;',
1382 -- -1, 0, coll, errm);
1384 --
1385 -- 3. PL/SQL (with results)
1386 -- DECLARE
1387 -- my_vc2coll sys.dbms_debug_vc2coll;
1388 -- errm VARCHAR2(100);
1389 -- each PLS_INTEGER;
1390 -- BEGIN
1391 -- dbms_debug.execute(
1392 -- 'DECLARE ' ||
1393 -- ' vc SYS.dbms_debug_vc2coll := ' ||
1394 -- ' SYS.dbms_debug_vc2coll();' ||
1395 -- ' len PLS_INTEGER; ' ||
1396 -- ' i PLS_INTEGER := 1; ' ||
1397 -- 'BEGIN ' ||
1398 -- ' SELECT COUNT(*) INTO len FROM emp; ' ||
1399 -- ' vc.EXTEND(len * 6); ' ||
1400 -- ' FOR c IN (SELECT * FROM emp) LOOP ' ||
1401 -- ' vc(i) := ''Ename: '' || c.ename; i := i+1; ' ||
1402 -- ' vc(i) := ''Empno: '' || c.empno; i := i+1; ' ||
1403 -- ' vc(i) := ''Job: '' || c.job; i := i+1; ' ||
1404 -- ' vc(i) := ''Mgr: '' || c.mgr; i := i+1; ' ||
1405 -- ' vc(i) := ''Sal: '' || c.sal; i := i+1; ' ||
1406 -- ' vc(i) := null; i := i+1; ' ||
1407 -- ' END LOOP; ' ||
1408 -- ' :1 := vc;' ||
1409 -- 'END;',
1410 -- -1, 1, my_vc2coll, errm);
1411 -- IF (errm IS NOT NULL) THEN
1412 -- :oops := errm;
1413 -- END IF;
1414 -- each := my_vc2coll.FIRST;
1415 -- WHILE (each IS NOT NULL) LOOP
1416 -- dosomething(my_vc2coll(each));
1417 -- each := myvc2_coll.NEXT(each);
1418 -- END LOOP;
1419 -- END;
1420 --
1421 PROCEDURE execute(what IN VARCHAR2,
1422 frame# IN BINARY_INTEGER,
1423 bind_results IN BINARY_INTEGER,
1424 results IN OUT NOCOPY dbms_debug_vc2coll,
1425 errm IN OUT NOCOPY VARCHAR2);
1426
1427
1428 ------------------------ TARGET_PROGRAM_RUNNING ------------------------
1429 -- Return TRUE if the target session is currently executing a stored
1430 -- procedure, or FALSE if it is not.
1431 --
1432 -- VERSION
1433 -- Probe v2.4
1434 --
1435 FUNCTION target_program_running RETURN BOOLEAN;
1436
1437
1438 ------------------------- PRINT_INSTANTIATIONS -------------------------
1439 -- Return a listing of the packages that have been instantiated in the
1440 -- current session.
1441 --
1442 -- VERSION
1443 -- Probe v2.4
1444 --
1445 -- PARAMETERS
1446 -- pkgs - the instantiated packages (OUT)
1447 -- flags - bitmask of options:
1448 -- 1 - show specs
1449 -- 2 - show bodies
1450 -- 4 - show local instantiations
1451 -- 8 - show remote instantiations (NYI)
1452 -- 16 - do a fast job (dont test to see if debug info exists or
1453 -- whether the libunit is shrink-wrapped)
1454 --
1455 -- EXCEPTIONS
1456 -- no_target_program - target session is not currently executing
1457 --
1458 -- NOTES
1459 -- On return, pkgs contains a program_info for each instantiation.
1460 -- The valid fields are Namespace, Name, Owner, and LibunitType.
1461 -- In addition, Line# contains a bitmask of:
1462 -- 1 - the libunit contains debug info
1463 -- 2 - the libunit is shrink-wrapped
1464 --
1465 PROCEDURE print_instantiations(pkgs IN OUT NOCOPY backtrace_table,
1466 flags IN BINARY_INTEGER);
1467
1468
1469 ------------------------------- PING ---------------------------------
1470 -- Ping the target session, to prevent it from timing out. This
1471 -- procedure is intended for use when execution is suspended in the
1472 -- target session (for example at a breakpoint).
1473 --
1474 -- If the timeout_behaviour is set to retry_on_timeout then this
1475 -- procedure is not strictly necessary.
1476 --
1477 -- VERSION
1478 -- Probe v2.4
1479 --
1480 -- EXCEPTIONS
1481 -- no_target_program will be raised if there is no target program
1482 -- or if the target session is not currently waiting for input
1483 -- from the debug session.
1484 --
1485 PROCEDURE ping;
1486
1487 ----------------------------- GET_LINE_MAP ------------------------------
1488 -- Get information about line numbers in program unit
1489 --
1490 -- Finds program unit and returns highest source line number, number
1491 -- of entry points, and a line map that allows to determine which
1492 -- lines are executable (or, to be precise, whether user can install
1493 -- a break-point or step on that line)
1494 --
1495 -- Line map is represented as a bitmap. If line number N is executable,
1496 -- bit number N MOD 8 will be set to 1 at linemap position N / 8.
1497 -- The length of returned linemap is either maxline divided by 8
1498 -- (plus one if maxline MOD 8 is not zero) or 32767 in the unlikely
1499 -- case of maxline being larger than 32767 * 8.
1500 --
1501 -- RETURNS:
1502 -- error_no_debug_info - line map is not available
1503 -- error_bad_handle - if program unit info could not be found
1504 -- success - successfull completion
1505 --
1506 -- VERSION
1510 --
1507 -- Probe v2.4
1508 --
1509 -- EXCEPTIONS
1511 FUNCTION get_line_map(program IN program_info,
1512 maxline OUT BINARY_INTEGER,
1513 number_of_entry_points OUT BINARY_INTEGER,
1514 linemap OUT raw) RETURN binary_integer;
1515
1516
1517 END DBMS_DEBUG;
[Home] [Help]