Fix #40 - Added rules G-9010, G-9020 and G-9030 about conversion functions

Author: kibeha

docs/4-language-usage/9-function-usage/.pages

@@ -0,0 +1 @@
+title: Function Usage

docs/4-language-usage/9-function-usage/g-9010.md

@@ -0,0 +1,38 @@
+# G-9010: Always use a format model in string to date/time conversion functions.
+
+!!! warning "Major"
+    Changeability, Maintainability, Reliability, Security, Testability
+
+## Reason
+
+Converting from strings to `date` or `timestamp` datatypes (using `to_date`, `to_timestamp`, `to_timestamp_tz` or `cast` to any of those datatypes) in practice always expects a fixed format (unlike converting *to* strings that can be fixed as well as allow the session to decide). Therefore it is a bad idea to allow this conversion to rely on the session NLS settings (`nls_date_format`, `nls_timestamp_format` and `nls_timestamp_tz_format`) as this makes the code vulnerable to changes in session and/or server configuration. It is even possible to utilize session `nls_date_format` for SQL injection if you use dynamic SQL.
+
+Using an explicit format model for string to `date` or `timestamp` conversion avoids this inappropriate dependability on configurable NLS parameters.
+
+## Example (bad)
+
+``` sql
+create package body employee_api is
+   procedure set_dob (in_employee_id in employees.employee_id%type, in_dob_str in varchar2)
+   begin
+      update employee
+      set date_of_birth = to_date(in_dob_str)
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```
+
+## Example (good)
+
+``` sql
+create package body employee_api is
+   procedure set_dob (in_employee_id in employees.employee_id%type, in_dob_str in varchar2)
+   begin
+      update employee
+      set date_of_birth = to_date(in_dob_str, 'YYYY-MM-DD')
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```

docs/4-language-usage/9-function-usage/g-9020.md

@@ -0,0 +1,38 @@
+# G-9020: Try to use a format model and NLS_NUMERIC_CHARACTERS in string to number conversion functions.
+
+!!! warning "Major"
+    Changeability, Maintainability, Reliability, Security, Testability
+
+## Reason
+
+Converting from strings to numeric datatypes (using `to_number`, `to_binary_double`, `to_binary_float` or `cast` to any of those datatypes) rely on session NLS settings for `nls_numeric_characters`. Typically the input string is expected to have a given decimal- and group-separator, so it is best practice to specify `nls_numeric_characters` in the function call. However, this requires also setting a format model, which is a good idea but can require a very large format model with many 9's if you do not know the maximum length of the string.
+
+To avoid an inappropriate dependability on configurable NLS parameters, try to use both format model and `nls_numeric_characters` in the conversion function call. The exceptions can be if the input is known to always be integer with no decimal- or group-separator, or if you do not know the maximum number of digits **and** have control over the session `nls_numeric_characters` parameter.
+
+## Example (bad)
+
+``` sql
+create package body employee_api is
+   procedure set_salary (in_employee_id in employees.employee_id%type, in_salary in varchar2)
+   begin
+      update employee
+      set salary = to_number(in_salary)
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```
+
+## Example (good)
+
+``` sql
+create package body employee_api is
+   procedure set_salary (in_employee_id in employees.employee_id%type, in_salary in varchar2)
+   begin
+      update employee
+      set salary = to_number(in_salary, '99999999999999999999.99999', q'[nls_numeric_characters='.,']')
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```

docs/4-language-usage/9-function-usage/g-9030.md

@@ -0,0 +1,36 @@
+# G-9030: Try to define a default value on conversion errors.
+
+!!! tip "Minor"
+    Maintainability, Reliability, Testability
+
+## Reason
+
+When converting from strings to other datatypes using a conversion function that supports the `default ... on conversion error` clause, it is a good idea to use this clause to avoid getting an error raised on bad input. The exception can be when you explicitly *want* an error to be raised to catch and process it in a later exception handler.
+
+## Example (bad)
+
+``` sql
+create package body employee_api is
+   procedure set_dob (in_employee_id in employees.employee_id%type, in_dob_str in varchar2)
+   begin
+      update employee
+      set date_of_birth = to_date(in_dob_str, 'YYYY-MM-DD')
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```
+
+## Example (good)
+
+``` sql
+create package body employee_api is
+   procedure set_dob (in_employee_id in employees.employee_id%type, in_dob_str in varchar2)
+   begin
+      update employee
+      set date_of_birth = to_date(in_dob_str default null on conversion error, 'YYYY-MM-DD')
+      where employee_id = in_employee_id;
+   end set_dob;
+end employee_api;
+/
+```

docs/9-appendix/appendix.md

@@ -123,4 +123,6 @@ n/a | 8120 | Never check existence of a row to decide whether to create it or no
 n/a | 8310 | Always validate input parameter size by assigning the parameter to a size limited variable in the declaration section of program unit. | Minor |  |  | ✘ |  | ✘ | ✘ |  | ✘
 n/a | 8410 | Always use application locks to ensure a program unit is only running once at a given time. | Minor |  | ✘ |  |  | ✘ |  |  | 
 n/a | 8510 | Always use dbms_application_info to track program process transiently. | Minor |  | ✘ |  |  | ✘ |  |  | 
-n/a | 9010 | Try to label your sub blocks. | Minor |  |  | ✘ |  |  |  |  | 
+n/a | 9010 | Always use a format model in string to date/time conversion functions. | Major | ✘ |  | ✘ |  | ✘ |  | ✘ | ✘
+n/a | 9020 | Try to use a format model and NLS_NUMERIC_CHARACTERS in string to number conversion functions. | Major | ✘ |  | ✘ |  | ✘ |  | ✘ | ✘
+n/a | 9030 | Try to define a default value on conversion errors. | Minor |  |  | ✘ |  | ✘ |  |  | ✘

docs/stylesheets/extra.css

@@ -224,7 +224,8 @@
     [id="access-objects-of-foreign-application-schemas"], 
     [id="validating-input-parameter-size"],
     [id="ensure-single-execution-at-a-time-of-a-program-unit"], 
-    [id="use-dbms_application_info-package-to-follow-progress-of-a-process"] {
+    [id="use-dbms_application_info-package-to-follow-progress-of-a-process"], 
+    [id="function-usage"] {
         page-break-before: always;
     }
 

tools/run-in-container/genpdf.sh

@@ -164,6 +164,8 @@ write_text "### Ensure single execution at a time of a program unit"
 write_guidelines "4-language-usage/8-patterns/4-ensure-single-execution-at-a-time-of-a-program-unit" "####"
 write_text "### Use dbms_application_info package to follow progress of a process"
 write_guidelines "4-language-usage/8-patterns/5-use-dbms-application-info-package-to-follow-progress-of-a-process" "####"
+write_text "## Function Usage"
+write_guidelines "4-language-usage/9-function-usage" "###"
 write_file "5-complexity-analysis/complexity-analysis.md"
 write_file "6-code-reviews/code-reviews.md"
 write_file "7-tool-support/tool-support.md"