Merge pull request #14 from ogobrecht/development

Development

README.md

@@ -5,12 +5,12 @@
     /)__)   focused on easy installation and usage
     -"-"-   combined with nice features.
 
-*This is currently version 1.0.1. Feedback and help is welcome.*
+*This is currently version 1.1.0. Feedback and help is welcome.*
 
 A T T E N T I O N: If you have one of the beta versions installed you should
 always run the uninstallation script (`@uninstall/drop_console_objects.sql`)
 before you install a new version. If you created a context, you should also
-delete it: `@drop_context.sql` (you may need higher permissions for this...).
+delete it: `@uninstall/drop_context.sql` (you may need higher permissions for this...).
 
 ## Easy to Install
 

apexplugin.json

@@ -1,6 +1,6 @@
 {
   "name": "console",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Oracle Instrumentation Console",
   "keywords": [
     "oracle",
@@ -42,6 +42,6 @@
   },
   "jsFile": {
     "md5Hash": "0817bef6ea32215b8493a42c0fa67d7f",
-    "version": 130
+    "version": 131
   }
 }

docs/api-overview.md

@@ -66,10 +66,10 @@ The main instrumentation methods:
 - [console.assert](package-console.md#procedure-assert) &
   [assertf](package-console.md#procedure-assertf)
 - [console.format](package-console.md#function-format)
-- [console.add_param](package-console.md#procedure-add_param)
+- [console.add_param](package-console.md#procedure-add_param) (also see [generate_param_trace](package-console.md#procedure-generate_param_trace) for code generation)
 
 Additional instrumentation methods:
- 
+
 - [console.action](package-console.md#procedure-action) &
   [module](package-console.md#procedure-module): Aliases for
   dbms_application_info.set_action and set_module to be friendly to the DBA and

docs/changelog.md

@@ -12,6 +12,10 @@
 
 # Changelog
 
+## v1.1.0 (2021-11-28)
+
+- New helper `generate_param_trace` to generate code for tracing parameters - thanks to github.com/vincimaroda for the idea
+
 ## v1.0.1 (2021-10-12)
 
 - Fix #11: Package CONSOLE does not compile under 12.2 with error message like "no function t_attribute_value_row..."

docs/installation.md

@@ -15,7 +15,7 @@
 A T T E N T I O N: If you have one of the beta versions installed you should
 always run the uninstallation script (`@uninstall/drop_console_objects.sql`)
 before you install a new version. If you created a context, you should also
-delete it: `@drop_context.sql` (you may need higher permissions for this...).
+delete it: `@uninstall/drop_context.sql` (you may need higher permissions for this...).
 
 ## One Minute Installation
 

docs/package-console.md

@@ -75,6 +75,7 @@ Oracle Instrumentation Console
 - [Procedure exit](#procedure-exit)
 - [Procedure exit_all](#procedure-exit_all)
 - [Function version](#function-version)
+- [Procedure generate_param_trace](#procedure-generate_param_trace)
 - [Function split_to_table](#function-split_to_table)
 - [Function split](#function-split)
 - [Function join](#function-join)
@@ -128,7 +129,7 @@ SIGNATURE
 package console authid definer is
 
 c_name    constant varchar2 ( 30 byte ) := 'Oracle Instrumentation Console'       ;
-c_version constant varchar2 ( 10 byte ) := '1.0.1'                                ;
+c_version constant varchar2 ( 10 byte ) := '1.1.0'                                ;
 c_url     constant varchar2 ( 36 byte ) := 'https://github.com/ogobrecht/console' ;
 c_license constant varchar2 (  3 byte ) := 'MIT'                                  ;
 c_author  constant varchar2 ( 15 byte ) := 'Ottmar Gobrecht'                      ;
@@ -1086,7 +1087,7 @@ create or replace procedure demo_proc (
   p_11 xmltype                        )
 is
 begin
-  raise_application_error(-20999, 'Test Error.');
+  raise_application_error(-20999, 'Demo Error.');
 exception
   when others then
     console.add_param('p_01', p_01);
@@ -1583,6 +1584,7 @@ procedure exit_all;
 
 Returns the version information from the console package.
 
+Inspired by [Steven's Live SQL example](https://livesql.oracle.com/apex/livesql/file/content_CBXGUSXSVIPRVUPZGJ0HGFQI0.html)
 
 ```sql
 select console.version from dual;
@@ -1595,6 +1597,165 @@ function version return varchar2;
 ```
 
 
+## Procedure generate_param_trace
+
+Generates parameter tracing code for you.
+
+Writes to the server output - switch it on to see results. Input for parameter
+`p_program` will be uppercased and spaces will be replaced by underscores - this
+means `SOME_API.DO_STUFF` is equivalent to `some api.do stuff`.
+
+EXAMPLE 1
+
+```sql
+create or replace function demo_func (
+  p_01 in     varchar2 ,
+  p_02 in     number   ,
+  p_03 in     date     )
+return varchar2 is
+begin
+  null; --YOUR CODE HERE
+end demo_func;
+/
+set serveroutput on
+exec console.generate_param_trace('demo func');
+```
+
+This will output something like:
+
+```sql
+--------------------------------------------------------
+-- Signature not recoverable with user_arguments
+-- We start with declare for easier formatting
+-- Your Program : DEMO_FUNC
+-- Package Name : -
+-- Object Name  : DEMO_FUNC
+--------------------------------------------------------
+declare
+  procedure console_add_in_params is
+  begin
+    console.add_param('p_01', p_01);
+    console.add_param('p_02', p_02);
+    console.add_param('p_03', p_03);
+  end console_add_in_params;
+  procedure console_add_out_params is
+  begin
+    console.add_param('your_return_value', your_return_value);
+  end console_add_out_params;
+begin
+  console_add_in_params;
+  console.info('ENTER');
+  --------------------
+  -- YOUR CODE HERE
+  --------------------
+  console_add_out_params;
+  console.info('LEAVE');
+  ----------------------
+  -- YOUR RETURN HERE
+  ----------------------
+exception
+  when others then
+    console_add_out_params;
+    console.error;
+    raise;
+end;
+/
+```
+
+As you can see in the procedure `console_add_out_params` you have to align the
+name of your return variable (`console.add_param('your_return_value',
+your_return_value)`).
+
+EXAMPLE 2
+
+```sql
+create or replace procedure demo_proc (
+  p_01 in     varchar2                       ,
+  p_02 in     number                         ,
+  p_03 in     date                           ,
+  p_04 in     timestamp                      ,
+  p_05 in     timestamp with time zone       ,
+  p_06 in     timestamp with local time zone ,
+  p_07 in     interval year to month         ,
+  p_08 in     interval day to second         ,
+  p_09 in     boolean                        ,
+  p_10 in out clob                           ,
+  p_11 in out xmltype                        ,
+  p_12 in out console.t_client_prefs_row     ,
+  p_13 in out console.t_client_prefs_tab     )
+is
+begin
+  null; --YOUR CODE HERE
+end demo_proc;
+/
+set serveroutput on
+exec console.generate_param_trace('demo proc');
+```
+
+This will output something like:
+
+```sql
+--------------------------------------------------------
+-- Signature not recoverable with user_arguments
+-- We start with declare for easier formatting
+-- Your Program : DEMO_PROC
+-- Package Name : -
+-- Object Name  : DEMO_PROC
+--------------------------------------------------------
+declare
+  procedure console_add_in_params is
+  begin
+    console.add_param('p_01', p_01);
+    console.add_param('p_02', p_02);
+    console.add_param('p_03', p_03);
+    console.add_param('p_04', p_04);
+    console.add_param('p_05', p_05);
+    console.add_param('p_06', p_06);
+    console.add_param('p_07', p_07);
+    console.add_param('p_08', p_08);
+    console.add_param('p_09', p_09);
+    console.add_param('p_10', p_10);
+    console.add_param('p_11', p_11);
+    --unsupported data type PL/SQL RECORD: console.add_param('p_12', p_12);
+    --unsupported data type TABLE: console.add_param('p_13', p_13);
+  end console_add_in_params;
+  procedure console_add_out_params is
+  begin
+    console.add_param('p_10', p_10);
+    console.add_param('p_11', p_11);
+    --unsupported data type PL/SQL RECORD: console.add_param('p_12', p_12);
+    --unsupported data type TABLE: console.add_param('p_13', p_13);
+  end console_add_out_params;
+begin
+  console_add_in_params;
+  console.info('ENTER');
+  --------------------
+  -- YOUR CODE HERE
+  --------------------
+  console_add_out_params;
+  console.info('LEAVE');
+exception
+  when others then
+    console_add_out_params;
+    console.error;
+    raise;
+end;
+/
+```
+
+As you can see in the output, unsupported data types for `console.add_param`
+will be commented out.
+
+SIGNATURE
+
+```sql
+procedure generate_param_trace (
+  p_program in varchar2              , -- The package and/or program name ('some_api.do_stuff').
+  p_level   in pls_integer default 3   -- The level you want to use for the parameter tracing.
+);
+```
+
+
 ## Function split_to_table
 
 Splits a string into a (pipelined) SQL table of varchar2.

docs/uninstallation.md

@@ -23,5 +23,5 @@ As with the installation the uninstallation is splitted into multiple steps:
     - You know, if you created synonyms and how they were named...
 
 A T T E N T I O N: If you have installed one of the beta versions and created a
-context, you should also delete it: `@drop_context.sql` (you may need higher
+context, you should also delete it: `@uninstall/drop_context.sql` (you may need higher
 permissions for this...).

install/apex_plugin.sql

@@ -38,9 +38,9 @@ begin
     p_ajax_function             => 'console.apex_plugin_ajax'             ,
     p_substitute_attributes     => true                                   ,
     p_subscribe_plugin_settings => true                                   ,
-    p_version_identifier        => '1.0.1'                    ,
+    p_version_identifier        => '1.1.0'                    ,
     p_about_url                 => 'https://github.com/ogobrecht/console' ,
-    p_files_version             => 130                         );
+    p_files_version             => 131                         );
 end;
 /