Fix #8 and #9 - Restructured Tool Support section with individual chapters on 4 db*CODECOP tools as well as plscope-util

Author: kibeha

docs/7-tool-support/.pages

@@ -1 +1 @@
-collapse_single_pages: true
+title: Tool Support

docs/7-tool-support/1-db-codecop-sqldev.md

@@ -0,0 +1,33 @@
+# db\* CODECOP for SQL Developer
+
+## Introduction
+
+[db\* CODECOP for SQL Developer](https://github.com/Trivadis/plsql-cop-sqldev) is a **free extension** to check an editor content for compliance violations of this coding guideline. The extension may be parameterized to your preferred set of rules and allows checking this set against a program unit.
+
+db\* CODECOP calculates metrics per PL/SQL unit, such as:
+
+- McCabe’s cyclomatic complexity
+- Halstead’s volume
+- The maintainability index
+- Lines
+- Commands (SQL\*Plus and SQL)
+- Statements (within a PL/SQL unit)
+- etc.
+
+And aggregates them on file level.
+
+The results are presented in an additional tabbed panel. One tab shows all guideline violations to quickly navigate to the corresponding code position. The other tab contains a full HTML report, which also may be opened in your external browser.
+
+## Examples
+
+Open an Oracle PL/SQL or SQL script in a SQL Developer editor and press Ctrl-Shift-C to check your code against the Trivadis PL/SQL & SQL guidelines.
+
+![Check](../images/tvdcc-sqldev-check.png)
+
+Navigate through the issues using the cursor keys to highlight the related code section in the linked editor.
+
+![Issues](../images/tvdcc-sqldev-issues.png)
+
+Dock the db\* CODECOP output window on your favorite position within SQL Developer and click on the report tab to reveal some additional metrics. Open the report in an external browser to print or save the report.
+
+![Report](../images/tvdcc-sqldev-report.png)

docs/7-tool-support/2-db-codecop-sonarqube.md

@@ -0,0 +1,87 @@
+# db\* CODECOP for SonarQube
+
+## Introduction
+
+[db\* CODECOP for SonarQube](https://github.com/Trivadis/plsql-cop-sonar) is a plugin for [SonarQube](http://www.sonarqube.org/). The plugin analyses SQL and PL/SQL code and calculates various metrics and checks the code for compliance of this coding guideline.
+
+A static code analysis is typically initiated as part of an continuous integration setup, e.g. at the end of a Jenkins or Hudson build job. SonarQube stores the result of the analysis in a relational database. Supported are PostgreSQL, Microsoft SQL Server and Oracle Database. For evaluation purposes, the embedded H2 database can also be used.
+
+Since every analysis is stored as a snapshot in the SonarQube repository the improvement or the decrease of the code quality may be monitored very well. Use SonarQube and the db\* CODECOP plugin if you care about your PL/SQL code quality.
+
+## Examples
+
+### Run Code Analysis via SonarScanner
+
+You start an analysis from the command line as follows (see [docs](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/) for more information):
+
+```
+sonar-scanner -Dsonar.projectKey="sample"
+```
+
+Here's an excerpt of the output:
+
+```
+INFO: Scanner configuration file: /usr/local/opt/sonar-scanner/conf/sonar-scanner.properties
+INFO: Project root configuration file: NONE
+INFO: SonarQube Scanner 4.1.0.1829
+...
+INFO: Project configuration:
+INFO: 115 files indexed
+INFO: Quality profile for plsql: db* CODECOP
+INFO: ------------- Run sensors on module sample
+INFO: JavaScript/TypeScript frontend is enabled
+INFO: Define db* CODECOP PlugIn (Secondary)
+INFO: Load metrics repository
+INFO: Load metrics repository (done) | time=36ms
+INFO: PlSQL COP Sensor initializing
+INFO: Instantiate class: com.trivadis.sonar.plugin.TrivadisGuidelines3ValidatorConfig
+INFO: Sensor CSS Rules [cssfamily]
+INFO: No CSS, PHP, HTML or VueJS files are found in the project. CSS analysis is skipped.
+INFO: Sensor CSS Rules [cssfamily] (done) | time=1ms
+INFO: Sensor PL/SQL Sensor [plsql]
+INFO: 115 source files to be analyzed
+INFO: Load project repositories
+INFO: Load project repositories (done) | time=10ms
+...
+INFO: Analysis report generated in 149ms, dir size=603 KB
+INFO: Analysis report compressed in 1101ms, zip size=264 KB
+INFO: Analysis report uploaded in 1858ms
+INFO: ANALYSIS SUCCESSFUL, you can browse http://localhost:9000/dashboard?id=sample
+INFO: Note that you will be able to access the updated dashboard once the server has processed the submitted analysis report
+INFO: More about the report processing at http://localhost:9000/api/ce/task?id=AXiSv3IJVMRTx5sCSVMo
+INFO: Analysis total time: 27.088 s
+INFO: ------------------------------------------------------------------------
+INFO: EXECUTION SUCCESS
+INFO: ------------------------------------------------------------------------
+INFO: Total time: 28.961s
+INFO: Final Memory: 40M/144M
+INFO: ------------------------------------------------------------------------
+```
+
+At the end of the run an URL to the scanner result is provided.
+
+### Run Code Analyis with CI Environments
+
+You can call the SonarScanner also from Gradle, .NET projects, Maven, Ant, Jenkins, etc. Whichever method you use, in the end the analysis report will be uploaded to SonarQube.
+
+See [SonarScanner](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/) for more information.
+
+### View Code Analysis Result in SonarQube
+
+Here are the results of the previous analysis.
+
+![SonarQube Dashboard](../images/sonar_1.png)
+
+Under `Issues` the following `Blocker` are shown:
+
+![SonarQube Issues](../images/sonar_2.png)
+
+By clicking on the reddish box you can drill down to the source code.
+
+![SonarQube Issues in Source](../images/sonar_3.png)
+
+When clicking on `Why is this an issue?` the complete rule is shown in similar way as in these guidelines.
+
+![SonarQube Guideline Details](../images/sonar_4.png)
+
+See [SonarQube documentation](https://docs.sonarqube.org/latest/) for more information.

docs/7-tool-support/3-db-codecop-cli.md

@@ -0,0 +1,27 @@
+# db\* CODECOP Command Line
+
+## Introduction
+
+[Trivadis db\* CODECOP](https://github.com/Trivadis/plsql-cop-cli) is a command line utility to check Oracle SQL*Plus files for compliance violations of this coding guideline.
+
+Furthermore McCabe’s cyclomatic complexity, Halstead’s volume, the maintainability index and some other software metrics are calculated for each PL/SQL unit and aggregated on file level.
+
+The code checking results are stored in XML, HTML and Excel files for further processing.
+
+To get the most out of this command line utility you should make it part of your Continuous Integration environment by using the [db\* CODECOP for SonarQube](https://github.com/Trivadis/plsql-cop-sonar) plugin. This way you may control the quality of your code base over time.
+
+Have also a look at [db\* CODECOP for SQL Developer](https://github.com/Trivadis/plsql-cop-sqldev) if you are interested to check the code quality of PL/SQL code within SQL Developer. It’s a free extension.
+
+db\* CODECOP supports custom validators. We provide some [example validators in this GitHub repository](https://github.com/Trivadis/plsql-cop-validators). You may use these validators as is or amend/extend them to suit your needs.
+
+## Examples
+
+Here are some screen shot taken from an of an HTML report based on the samples provided with db\* CODECOP.
+
+![Processing & Content](../images/plsqlcop_processing.png)
+![Issue Overview](../images/plsqlcop_issues_overview.png)
+![Complex PL/SQL Units](../images/plsqlcop_complex_plsql_units.png)
+![File Overview](../images/plsqlcop_file_overview.png)
+![File Issues](../images/plsqlcop_file_issues.png)
+
+These [HTML](https://trivadis.github.io/plsql-cop-cli/tvdcc_report.html) and [Excel](https://trivadis.github.io/plsql-cop-cli/tvdcc_report.xlsx) reports have been created by db\* CODECOP and are based on a simple set of good and bad example files distributed with db\* CODECOP.

docs/7-tool-support/4-db-codecop-validators.md

@@ -0,0 +1,20 @@
+# db\* CODECOP Validators
+
+db\* CODECOP supports custom validators. A validator must implement the `PLSQLCopValidator` Java interface and has to be a direct or indirect descendant of the `PLSQLValidator` class. Such a class can be used in the command line utility and the SQL Developer extension. 
+
+For SonarQube a `ValidationConfig` is required. A config defines the validator with its rules and quality profile for SonarQube. See [GLPValidatorConfig](https://github.com/Trivadis/plsql-cop-validators/tree/main/src/main/java/com/trivadis/sonar/plugin/GLPValidatorConfig.java). The referenced XML files are generated based on the validator and the optional [sample guidelines](https://github.com/Trivadis/plsql-cop-validators/tree/main/src/main/resources/GLP/sample).
+
+You may use these validators as is or amend/extend them to suit your needs.
+
+## Provided Validators
+
+The [db\* CODECOP Validators](https://github.com/Trivadis/plsql-cop-validators) project provides the following custom validators in the package `com.trivadis.tvdcc.validators`:
+
+Class | Description 
+----- | -----------
+TrivadisPlsqlNaming | Checks [Naming Conventions](https://trivadis.github.io/plsql-and-sql-coding-guidelines/2-naming-conventions/naming-conventions/#naming-conventions-for-plsql) of the Trivadis PL/SQL & SQL Coding Guidelines
+GLP | Checks naming of global and local variables and parameters 
+SQLInjection | Looks for SQL injection vulnerabilities, e.g. unasserted parameters in dynamic SQL
+Hint | Looks for unknown hints and invalid table references
+OverrideTrivadisGuidelines | Extends TrivadisGuidelines3 and overrides check for [G-1050](https://trivadis.github.io/plsql-and-sql-coding-guidelines/v4.0/4-language-usage/1-general/g-1050/).
+TrivadisGuidelines3Plus | Combines the validators TrivadisPlsqlNaming, SQLInjection and OverrideTrivadisGuidelines. 

docs/7-tool-support/5-plscope-utils.md

@@ -0,0 +1,14 @@
+# plscope-utils
+
+## Introduction
+[plscope-utils](https://github.com/PhilippSalvisberg/plscope-utils) is based on PL/Scope which is available in the Oracle Database since version 11.1. It consists of the following two components:
+
+- [Core Database Objects](https://github.com/PhilippSalvisberg/plscope-utils/blob/main/database/README.md)
+
+	Provides relational views and PL/SQL packages to simplify common source code analysis tasks. Requires a server side installation.
+
+- [SQL Developer Extension (plscope-utils for SQL Developer)](https://github.com/PhilippSalvisberg/plscope-utils/blob/main/sqldev/README.md)
+
+   Extends SQL Developer by a ```PL/Scope``` node in the database navigator tree, context menus, views shown for tables, views and PL/SQL nodes and some reports. Requires a client side installation only.
+
+Part of plscope-utils is a check of naming conventions according to this coding guideline - either as a database view or a Oracle SQL Developer report.

docs/7-tool-support/tool-support.md

@@ -115,7 +115,7 @@ n/a | 7330 | Always assign values to OUT parameters. | Major |  |  | ✘ |
 74 | 7440 | Never use OUT parameters to return values from a function. | Major |  |  |  |  |  | ✘ |  | 
 75 | 7450 | Never return a NULL value from a BOOLEAN function. | Major |  |  |  |  | ✘ |  |  | ✘
 n/a | 7460 | Try to define your packaged/standalone function deterministic if appropriate. | Major |  | ✘ |  |  |  |  |  | 
-76 | 7510 | Always prefix ORACLE supplied packages with owner schema name. | Major |  |  |  |  |  |  | ✘ | 
+76 | 7510 | Always prefix Oracle supplied packages with owner schema name. | Major |  |  |  |  |  |  | ✘ | 
 77 | 7710 | Avoid cascading triggers. | Major |  |  | ✘ |  |  |  |  | ✘
 n/a | 7720 | Never use multiple UPDATE OF in trigger event clause. | Blocker |  |  | ✘ |  | ✘ |  |  | ✘
 n/a | 7730 | Avoid multiple DML events per trigger. | Minor |  |  | ✘ |  |  |  |  | ✘