DBDocumentor produces database documentation for the SQL objects in your database project. The list of SQL objects documented varies with the SQL dialect chosen, and DBDocumentor currently supports; Microsoft SQL Server 2005 and below, Firebird 1.5 and 2.0, and Sybase SQL Anywhere 10 and below (SQL Anywhere was previously marketed as Adaptive Server Anywhere, or ASA) . Generating reference documentation for a SQL database using DBDocumentor is as simple as selecting the SQL dialect, the object types to include and the source files to process. Within a few minutes DBDocumentor generates a fully cross referenced view of the SQL database, including where data is sourced from and what objects are modifying data in what other objects. The cross referencing extends to procedure and security usage, clearly showing which procedures are used where, and under what security context. These capabilities make DBDocumentor ideal for those wishing to learn the structure of a given database, or simply to document the database for future reference.
Extended capabilities of the rich feature set include declarative object grouping, support for DBMS metadata based descriptions like those provided in SQL Server Enterprise Manager or SQL Server Management Studio, SQL dialect specific syntax color coding, control over the documentation of temporary objects and dynamic SQL, ease of integration into automated build environments, and the generation of XML output. All documentation is generated by reading the source SQL batch files and requires no active database connection, or any database connectivity tools. The benefits of an offline SQL parser are many, and include the ability to document result set structure, return values and data access points.
DBDocumentor produced documentation is perfect as printed database application documentation for:
Client documentation for software development consulting projects
Online access for middle tier developers to develop against a documented database interface
Quality assurance efforts to ensure consistent coding guidelines are followed
Determining the degree of data exposure and risk by specific database functions and procedures
Determining the degree of dynamic SQL used in the database, and what data sources are impacted by the use of dynamic SQL
Determining what data is exposed via Microsoft SQL Server Reporting Services reports
DBDocumentor produced documentation can also be produced at the beginning of projects to help define the interface contract between the database layer and its consumers where data access occurs via stored procedures, user defined functions or data views. Object oriented design techniques have existed for some time, and they all have a guiding principle of defining the interfaces to objects, and adhering to those interfaces, often called contracts. Database procedures offer the capability to define SQL interfaces, but tools to actually document the interface are rare. DBDocumentor is one such tool.
DBDocumentor 4.50 contains new functionality and performance improvements. In response to customer requests, two specific items were added.
RDL documentation support has been added for SQL Server Reporting Services 2008 schemas.
The long awaited PDF output is now here. The PDF output shows a slightly different format from the normal HTML and CHM options, and this is mostly due to differences in how content is presented for these formats. As with the HTML/CHM options, all cross-referencing is present, and custom content is fully supported.
DBDocumentor 4.40 contains only new functionality. In response to customer requests, three specific items were added.
A major rework of the RDL documentation was performed. In previous versions, only the items directly relating to the SQL query used in a report element were documented. While this provided some value, there was no linkage between the various reports, nor was there any indication of where a given query was used within the report. These items have been resolved with the addition of report parameters, reports drilled into, reports drilled in from. Additionally, the report author is included.
The wildcard syntax for source file lists used in the external source file list was enhanced. It now supports partial match wildcards using the '?' character, and terminated partial matches using the '*' character. In both cases, the partial matching is on the file name, and follows standard Windows conventions.
Firebird 2.0 is now a supported dialect. All new functionality contained in Firebird 2.0 is supported, and automatically included in the updated output. All existing Firebird 1.5 projects are automatically upgraded to Firebird 2.0 projects, resulting in a seamless upgrade path for Firebird users. Please note that if you wish to take advantage of the new COMMENT syntax, you will need to enable that option in DBDocumentor.
DBDocumentor™ version 4.30 sees several major changes. The two most significant are changes in the supported operating systems, and major enhancements to a supported SQL parser.
Version 4.30 contains a significantly enhanced Sybase SQL
Anywhere (ASA) parser. Starting with version 10, Sybase has also changed its branding of
Adaptive Server Anywhere to SQL
Anywhere. DBDocumentor™ supports many of the new SQL Anywhere 10 constructs
including materialized views. The new keywords introduced with version 10
are also appropriately colorized.
In addition to the support for version 10, numerous enhancements were made to the ASA parser. Some of the constructs now processed are:
Global temporary tables
Local temporary tables
The SET HIDDEN option on procedures, functions and views to encrypt them
Triggers defined on user specified tables now inherit the user of their parent table
If multiple create statements for procedures, functions or views were present in the same batch, DBDocumentor™ was only processing the first object in the batch, but was treating the entire batch as a single statement. When processing an Anywhere batch, DBDocumentor™ 4.30 is more statement aware and will correctly process most batches containing multiple create statements. The source code listing will continue to contain the complete source for the batch, not only the statements used in the create. In the event that multiple statements are in a single batch, to document them the syntax will need to follow that of ##FND.
DBDocumentor™ 4.30 now has official support for Windows Vista™ in all editions, including 64 bit (x64). When DBDocumentor™ installs on any Windows Vista™ operating system, you will be prompted with a digital signature dialog to identify that the installer is from Pikauba Software and the installer is for DBDocumentor. When you accept this dialog, you will then be prompted with a normal (gray) user access control dialog. If you are a local machine administrator, you will be able to accept this dialog and DBDocumentor will install. DBDocumentor has been tested and verified as fully functional on all versions of Windows Vista™. If you experience any problems with DBDocumentor on Vista, please let us know.
Several bug fixes are included in this release. All are listed in the readme, but the follow are the most significant.
There is a behavior change which may impact some users. In prior versions, if you specified that tables were not be included in the output, under certain circumstances temporary tables would be included in the output.
In order to trigger this behavior, you had to configure DBDocumentor to include tables, then select temporary table inclusion, and then deselect table inclusion. Since the default configuration was to include temporary tables, it was likely that the changed behavior will impact many users.
The textual titles for ROLE membership were incorrect. The categorization was correct, so if you were working with the XML output, or had overridden the default values, your output would have been correct.
If a user defined function had as its first parameter a constant non-national character, then the function would not be included in the summary for the object calling it.
Encrypted stored procedures for the SQL Server dialects were not being correctly marked as encrypted. Depending upon the enabled options, this had the result of including the SQL source for encrypted options in the output -- very bad.
Encrypted user defined functions for the SQL Server dialects were not being correctly marked as encrypted. Depending upon the enabled options, this had the result of including the SQL source for encrypted options in the output -- very bad (again).
DBDocumentor version 4.21 is the first version of DBDocumentor to be digitally signed. We taken the extra step of digitally signing our binaries to provide you, our potential and valued customers, with greater confidence that the applications you are downloading were produced by Pikauba Software. If you find a version of DBDocumentor produced after October 1, 2006 without a digital signature, please contact us.
Other than this significant change, this release is a bug fix release. The full list of fixes are provided in the readme file, but here are some of the highlights.
DBDocumentor 4.21 has been verified on both the 32bit and 64bit versions of Windows Vista. DBDocumentor functions correctly on both of these operating systems, but during installation you may receive warnings about a problem executing the Setup.exe or Upgrade.exe files. You can safely ignore these warnings as DBDocumentor has been correctly installed. Resolution of these warnings will require changes to the installation package which are planned for the final release of Windows Vista.
Please note that since DBDocumentor is a 32bit application, it will be installed under "Program Files (x64)", not "Program Files" when installed on the 64bit version of Vista.
At this time DBDocumentor is not yet fully supported on Windows Vista, but should you experience any problems, please do report them. DBDocumentor will be fully supported once Windows Vista
is released to the public.
All HTML generated by DBDocumentor is now fully HTML 4.01 Transitional compliant. Please note that the full DTD of "loose.dtd" is not specified as there are some issues with the dynamic layout in Internet Explorer. If you are copying the layout from a DBDocumentor generated page for use in any
fixed content area, please be aware that full specification of the DTD may cause Internet Explorer or the CHM viewer to consume 100% of at least one CPU on the machine when the page is viewed. At present the only acceptable workaround is to *not* specify the full DTD.
If a language override file was created for an older version of DBDocumentor, and new language elements were added in a newer version of DBDocumentor, those new language elements would become blank strings when the override file was used with the newer version of DBDocumentor.
The fix was to always load the new template first, and then the override elements. At least this way no blank strings would appear.
If an output file name was defined which contained characters that are invalid for Windows filenames, DBDocumentor would throw an "Path not found" error during final compilation. DBDocumentor now validates the file name during the project definition phase.
If sp_executesql was used to execute dynamic SQL and the database owner was specified in the call to sp_executesql, the contents of the dynamic SQL were not being included. This bug was prevalent when exporting a SQL schema from Microsoft SQL Server 2005.
DBDocumentor version 4.20 contains a number of bug fixes, along with one very significant new feature.
DBDocumentor now supports Microsoft SQL Server Reporting Services Report Definition Language (SSRS RDL) files. When defining a project, you have the option of including RDL files. If you choose to supply an RDL file to DBDocumentor, DBDocumentor will verify that the default XML namespace corresponds to either Reporting Services for SQL Server 2000, or SQL Server 2005 Reporting Services. If the default namespace doesn't match, the file will not be processed.
A change in the way XML was handled beginning with version 4.00 resulted in UNICODE entities being incorrectly handled and certain XML parsers would raise an error if UNICODE characters were present in the XML. This problem was only present in the XML output.
If whitespace appeared in a RAISERROR TSQL statement containing a textual error message, the text of the error message would be omitted.
If you specified an alternate (non default) file extension for your SQL source files, and then browsed to the location of the SQL source files, any files matching your alternate file extension would not be listed.
In TSQL, if a user defined function was called where there was an open bracket preceding the function name, without any whitespace, the user defined function was not listed as a called function. Now fixed.
The default CHM icon was being used for the content page icon. The standard CHM icon for a content page, by convention, is an icon depicting a page of paper. This has been changed. If the previous default icon is desired, please set the II tag on your content to a value of 9.
DBDocumentor version 4.10 contains a significant number of bug fixes, and new functionality. The new functionality and major bug fixes are listed below:
Support for a new tag to exclude specific objects from the output.
If you are using source files which contain DDL for more than one object
which would be included by default but don't want to include specific instances of an object, you can now use the ##EXCL tag to accomplish this.
An example of this situation would be a single source file containing DDL for all the tables in the database, and you are wanting to provide documentation for third party developers to code against, but do not want to include tables which might change and which the developers are not expected to code against.
When specifying the file list in an external file, you now can include '*' as a wildcard. The acceptable options are '*.*, '*.<extension>' and '<file>.*'
The HTML output option is now accessible from the main user interface, and no longer requires CHM compilation to be selected.
An index page is now included with the HTML output option
The HTML generated for the HTML output option can now be scaled to any font size the supported browsers can render. Additionally, the table of contents images scale with the text.
If you specified 'recurse' for the file list, the user interface would not respond until the entire subfolder structure had been scanned. If an incorrect path was entered, this could take some time. The file population dialog is now interactive.
When using SQL Server 2005 extended properties, and specifying the variable name to sp_addextendedproperty, the contents of the extended property would not be included. This is due to a change in the documentation of the variable name between the final CTP of SQL Server 2005 and the released version of SQL Server 2005.
When using SQL Server extended properties, and specifying the variable name for all parameters, the contents of the extended property would not be included. This was a regression from version 3.41 behavior.
If the source SQL for a Firebird project specified the character set on procedure parameters, all parameters on the procedure following the character set specification would be ignored. Now fixed.
If both explicit JOIN and implicit JOINs were present in the same SELECT statement, with the implicit JOIN occurring after the explicit ones, the output would lack the implicit joins and would contain the word ON. Now fixed.
SQL Server table variables defined in under defined functions were not being hyperlinked.
In Microsoft TSQL, the pseudo table name given to multi-statement table
valued functions would be included in the output. Upon reflection, this
made little sense so the pseudo table name is no longer present in any
DBDocumentor version 4.00 is a significant upgrade from the last public release, version 3.41. The readme.txt file included with DBDocumentor 4.00 contains a list of all the changes made since version 3.41, including bug fixes. Among the major changes are:
Support for multiple SQL dialects. Currently DBDocumentor 4.00 supports Microsoft SQL Server 2005 and below including SQL Server 2005 Express, Firebird 1.5, and Sybase Adaptive Server Anywhere (ASA) 9 and below. Future dialects are planned, but will be implemented based upon demand.
Simplified user interface for project configuration. The tabbed configuration interface of prior versions has been replaced by a logical progression of configuration screens. As with all prior versions, once a project has been defined, subsequent runs of the project can be accomplished by pressing the 'Finish' button.
User defined descriptions can now contain XML, without the need to escape the XML, and that XML will be color syntax highlighted when displayed. Please see the manual section "Pikauba Namespace Extensions" for more information.
Significant performance gains have been made in the colorization process. If you have been using DBDocumentor 3.41 and experiencing long processing times while writing colorized output, you should find DBDocumentor 4.00 much faster.
Finer grained control is now provided on the processing of dynamic SQL.
Control of how temporary objects are processed is now provided. Additionally, if temporary objects are included in the project, they are linked and referenced only to the object which created them
Dialect specific objects are documented. For example, if the dialect supports Common Table Expressions, they will be included in the output.
Dialect specific object categorization is present. For example, in SQL Server a non-native data type is referred to as a user defined type, or UDT. In Firebird this concept is known as a Domain.
All textual aspects of the output CHM documentation can be overridden by the user. This means that if the target user of the CHM documentation reads a language other than English, you can supply a DBDocumentor generated document in their language, complete with all table of contents entries and layout items in their language. Please see the manual section "Alternate Language Support" for more information.
© 2001 - 2009 Pikauba Software. All rights reserved.
DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.
All other trademarks are properties of their respective owners.