How DBDocumentor processes dynamic SQL

Beginning with DBDocumentor 3.10, the parsing of dynamic SQL occurs under a structured series of conditions.  Versions prior to 3.0 attempted to determine the intent behind the dynamic SQL in a fairly crude fashion.  This approach led to a large number of potential parsing error conditions which have been eliminated with structured Dynamic SQL Parsing Rules.  While these rules do create a situation where the output is fairly deterministic, due to the very nature of dynamic SQL, this still does not eliminate every potential parsing errors.  This section describes the rules followed for processing dynamic SQL and as such should provide an explanation of the outcome, if it is not immediately obvious.  DBDocumentor 4.00 expands upon this to provide the user with control over the types of dynamic SQL documented.  

Dynamic SQL Conditions Parsed

DBDocumentor will consider SQL which falls into one of these three categories as dynamic SQL, and will attempt to process it as such.

If any of these three conditions are met, the SQL is considered dynamic and will be expanded.

SQL Dialect Specific Dynamic SQL

How dynamic SQL is specified varies from DBMS to DBMS.  The following DBMS statements constitute dynamic SQL for DBDocumentor.

Microsoft SQL Server

Firebird 1.5

Sybase SQL Anywhere (ASA)

Dynamic SQL Expansion

DBDocumentor attempts to first expand any string variables contained within the dynamic SQL.  This expansion occurs to build up a pseudo command which can be parsed using the default SQL parser.  If the pseudo command corresponds to SQL which creates other objects, DBDocumentor will create sub-batches to handle the resultant SQL and its operations.

Dynamic SQL Error Conditions

During the processing of dynamic SQL, DBDocumentor applies some rudimentary validation rules on the pseudo command generated by the Dynamic SQL Parsing Rules.  These validation rules are intended to provide an indication of the types of problems which could be present in dynamic SQL, and if a rule appears to be broken, a log file entry will be written.  As a general rule, if you see an entry in the log file indicating a SQL warning, this indicates some dynamic SQL is present which may error out when executed.  If after investigation it is determined that the validation rule is in fact in error, please do not hesitate to inform Pikauba Software.

Dynamic SQL Output Inconsistencies

Since DBDocumentor does not evaluate the dynamic SQL, there is no method for it to provide 100% coverage of the possible paths of execution for the dynamic SQL.  What this means is that the output from the dynamic SQL parser may not be completely consistent with the output of the same SQL when run on SQL Server.  The following are examples of the expected inconsistencies:

'SELECT * FROM ' + RTRIM(@DBName)

Will return a data source of RTRIM

If any of these conditions are present, use of the override tag is recommended.

© 2001 - 2009 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.