DBDocumentor

Overview DBDocumentor™

DBDocumentor™ SQL Database Documentation Tool

Welcome to the DBDocumentor™ SQL Server database documentation tool from Pikauba Software. This tool allows the SQL developer to produce professional documentation that can be viewed using the Microsoft® HTML Help System. By using the HTML Help format, DBDocumentor™ can generate documentation in an industry standard form that should be familiar to any developer working with Microsoft® tools.

The rich feature set allows the developer a simplified method for creating the documentation. The tag replacement capability permits "document as you go" methodologies. A brief discussion of the SQL objects DBDocumentor™ is currently designed to work with include: data views, stored procedures, tables, triggers, user defined data types, user defined functions and indices.

The benefits of DBDocumentor™ are numerous and range from; decoupling the SQL and object development, to facilitating coding standards adherence, to providing production quality documentation for SQL database administrators.

For users upgrading from SQLHelp, please see the feature comparison chart.

DBDocumentor™ is compatible with batch build scripts. Please see the command line options page.

DBDocumentor™ has been tested with the Microsoft Windows Server™ 2003 and found to be compatible. The only operational issues a user should encounter relate to Internet Explorer Enhanced Security settings during application setup and product purchase, and to output file ownership. Output file ownership issues are addressed here, and Internet Explorer Enhanced Security issues can be resolved by adding *.pikauba.com and *.regsoft.net to the trusted sites list.

SQL Dialects

DBDocumentor supports multiple SQL dialects. The default SQL dialect is Microsoft SQL Server 2000. DBDocumentor produces its output by processing the raw SQL commands used to define the database, so if your SQL dialect is not listed on this page, you may experience processing problems. If your SQL dialect is not currently supported, you may wish to contact us to learn if there are any plans for inclusion.

Required Components

DBDocumentor has several required third party components. If you are missing any of these components, the Test Components dialog box will appear. The most common component you're likely to be missing will be the HTML Help workshop. For details on the Test Components dialog and how to obtain missing components, please view this page.

Licensing

DBDocumentor™ is not free software. Until you elect to purchase it and enter the registration key, once per day you will be required to agree to the licensing agreement. For more details on registering DBDocumentor™, please view this page.

Important Note: Since this documentation is available for separate download from the DBDocumentor™ product, it contains its own licensing agreement. If you are running this documentation from within DBDocumentor™ itself, you can safely ignore this section, otherwise, please view the licensing agreement here.

SQL Documentation

DBDocumentor™ performs its documentation by processing the SQL script files used to create the database. This means that you will need to obtain one or more SQL scripts corresponding to the database, or to the portion of the database you wish to document. DBDocumentor™ does not support direct connection to a SQL Server instance for a number of reasons, most notably that such a connection potentially could potentially result in a document containing considerably less detail than what can be obtained by processing the raw SQL.

© 2001- 2006 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.
All other trademarks are the property of their respective owners.


SQL Dialects

Documentation Procedures DBDocumentor™

Multiple SQL Dialect Support

DBDocumentor 4.0 and higher supports the parsing of multiple SQL dialects using the same core parsing engine. Since the core engine does not require any active database connection, there are no compatibility problems with SQL libraries, or security concerns about providing a login to a database simply for the purposes of documenting the database. The documentation for each dialect has been customized for the dialect being documented. This results in an output which is expressed in terms specific to the dialect.

Microsoft SQL Server 2000 and Prior

If you are familiar with versions of DBDocumentor prior to version 4.00, you have already seen the output style used for SQL Server 2000 and before. While there have been some overall enhancements to the parser, the core capabilities of the SQL 2000 parser are essentially unchanged. If you pass SQL Server 2000 batches to the SQL Server 2005 parser, no processing errors will occur, but you may notice some colorization of keywords which were not colorized in SQL Server 2000.

Firebird 1.5

Firebird is an open source database derived from Borland Interbase. Firebird is maintained by the Firebird Foundation, which can be found on the Internet at: http://firebird.sourceforge.net/index.php. DBDocumentor processes Firebird SQL files in the same manner as it does for Microsoft SQL Server 2000. In order to invoke the Firebird parser, you must select 'Firebird 1.5' as the SQL dialect. If you pass a Firebird 1.5 SQL batch to the default SQL Server 2000 parser, DBDocumentor will take significant time to complete the parsing and the output will be largely inaccurate.

Note: At present there is no processing of the RDB$DESCRIPTION description tag. As a result the option to include metadata descriptions is disabled. Future versions of DBDocumentor may support these optional descriptions.

Sybase ASA 9 and Below

Sybase Adaptive Server Anywhere is a product of iAnywhere (http://www.ianywhere.com/), a Sybase company. ASA databases can be coded in a subset of Transact SQL used for Adaptive Server Enterprise (and Microsoft SQL Server), Watcom SQL or a combination of the two. DBDocumentor processes ASA SQL files in the same manner as it does for Microsoft SQL Server 2000. In order to invoke the ASA 9 parser, you must select 'Sybase ASA 9 and below' as the SQL dialect. If you pass an ASA SQL batch to the default SQL Server parser, no Watcom SQL commands will be correctly processed, and subtle errors will be present in the output document.

Microsoft SQL Server 2005

Microsoft SQL Server 2005 builds upon the capabilities of SQL Server 2000. Some of the features are extended from SQL 2000 and others are completely new. DBDocumentor is able to correctly process SQL Server 2005 batches. If your SQL batch makes use of SQL Server 2005 specific functionality, an accurate document will only be generated by selecting 'SQL Server 2005' as the SQL dialect. If you pass a SQL Server 2005 batch to the default SQL 2000 parser, the features and functionality of SQL Server 2005 SQL will not be processed.

© 2001- 2006 Pikauba Software. All rights reserved.


DBDocumentor - Benefits

Overview DBDocumentor™

Benefits

The DBDocumentor system offers numerous benefits to developers, database administrators, professional services firms, and those generally interested in documenting the schema and activity on their SQL Server databases. A brief discussion of the SQL objects DBDocumentor is currently designed to work with include: data views, stored procedures, tables, triggers, user defined data types, user defined functions, indices and security roles.

DBDocumentor is designed to document the SQL database objects contained in batch scripts. To minimize the impact on a database, DBDocumentor is intended to run offline from the actual database by parsing the batch scripts used to define the objects in the system.

Offline Parser Benefits

By processing the raw SQL used to define the database, DBDocumentor has several distinct benefits from other documentation solutions.

  • Encrypted stored procedures, triggers, and user defined functions can be documented without exposing business logic (assuming the source is not included in the output document)
  • Should Microsoft decide to change any system stored procedures, or metadata tables, DBDocumentor will continue to function, assuming no changes to the Transact SQL language occur.
  • DBDocumentor does not need any special security or login considerations on the actual database, as it never connects to the database
  • DBDocumentor does not require any connectivity with an actual database, nor does it require any SQL Server components (including SQLDMO) be installed on the machine performing the documentation
  • The DBDocumentor parser is able to describe the result set layout used in stored procedures, data views and functions
  • If a stored procedure returns information via a RETURN statement, the DBDocumentor parser will include that in the output
  • The DBDocumentor parser is able to determine object interactions not stored in the SQL Server metadata tables (e.g. table usage in dynamic stored procedures)
  • The DBDocumentor parser can frequently document the structure of dynamic SQL. Dynamic SQL is never stored in SQL Server metadata tables effectively hiding it from online documentation approaches.
  • Any usage of dynamic SQL is clearly indicated in the object's documentation
  • Ad-hoc queries can be documented

Benefits of SQL Documentation

The use of the DBDocumentor documentation tool, and its output, offer several benefits including:

  • The ability to document database structures in raw form. Raw form documentation refers to the parsing of SQL scripts where no comment tags currently exist. When you first run DBDocumentor against script, raw form documentation is produced.
  • Isolation of non-SQL developers from any requirement to read the SQL of a procedure or function to determine what the required inputs and expected outputs might be.
  • The ability to provide rich descriptions of the purpose behind procedures, their parameters, and output.
  • The ability to provide rich descriptions of the purpose behind data views
  • The ability to provide database administrators with a listing of procedures, that return data, modify data, use cursors or are transactional. With this information, administrators can better evaluate database performance.
  • The ability to determine if SQL coding conventions are being followed. E.g. if a project must use transactions, but a data modification procedure exists that isn't transactional.
  • The ability to determine if multiple result sets are being used in a query.
  • The ability to provide examples of the intended use behind a procedure, function or data view.
  • Providing a method to isolate the query development from the critical path for projects. In object oriented design an interface contract is defined between clients and servers. By allowing the database interface to be defined, actual database query development can occur in parallel with other aspects of a project.
  • The ability to define project specific groupings of objects. This allows the consumer of the documentation the ability to see database objects in the context of their peers.
  • Optionally indicate what security context is associated with an object
  • Clear indication of relationships between objects. For example, the report for a data table includes a listing of what objects are referencing it, and which are modifying it
  • The ability to determine where dynamic SQL is being used
  • The ability to determine if all objects which are supposed to be encrypted are in fact encrypted.


DBDocumentor - Features

Overview DBDocumentor™

Features

The DBDocumentor system contains a large number of features to assist development staff in producing production quality SQL documentation.

Documentation items include the ability to:

  • Output documentation in XML format
  • Output documentation in HTML Help format (Classic and Modern MSDN style)
  • Document stored procedures, user defined functions, user defined data types, triggers, data views, tables, indices, security roles, and generic SQL batches.
  • Document databases without having any connection to the database.
  • Read all parameters of a stored procedure, including the name, data type, direction of data transfer (input vs. output), and default values.
  • Read the result sets of stored procedures, data views and table based user defined functions
  • Read all the parameters of table columns including; name, data type, NULLness, identity values and constraints
  • Read indices and associate them with their parent table or data view
  • Hyperlink between tables having foreign key references
  • Hyperlink between stored procedures to see which procedure is calling which procedure, and which procedure is being called.
  • Optionally include the source of the procedure in the compiled help. This allows users to view the SQL without having access to either the database or the source SQL.
  • Produce color syntax highlighted output, ideal for printed reports.
  • Define usage examples and color syntax highlight any sample SQL
  • Document the relationships between data sources (tables, views and table based functions) and queries (stored procedures, triggers, views, functions, and generic batches)
  • Document user defined function usage in queries and ad-hoc batches
  • Determine if a stored procedure uses return values, and what those values might be.
  • Determine if stored procedures or data views returns data via one or more result sets, and the structure of the result set
  • Define project specific copyright notices.
  • Define project specific project file descriptions.
  • Define the purpose of each user defined function, user defined data type, stored procedure, data view, trigger, table and index and security role in the database.
  • Optionally, define usage examples (and color syntax highlight any sample SQL) for the use of a given stored procedure or user defined functions.
  • Define functional groupings for the SQL that is in the project to provide a detailed table of contents structure.
  • Define the intent of executed procedures within stored procedures, data views and triggers.
  • Optionally, use SQL Server 2000 extended properties for documentation. Includes Pikauba specific extensions designed to make the database self documenting.
  • Indicate if an object is encrypted
  • Indicate if an object uses dynamic SQL
  • Full support for object ownership calling conventions in the output documentation


SQL Server 2000 Extended Properties

Microsoft SQL Server 2000 introduced a method for providing descriptions for certain objects, or object attributes in the database. These descriptions are stored in the database as extended properties. Natively, SQL Server supports adding usage descriptions to objects from the Enterprise Manager tool. These descriptions are stored in the database using the MS_Description property name. In version 2.x of DBDocumentor, the MS_Description property was the only property supported, and its use is described here.

You can obtain more information on the use of extended properties in general by looking in the SQL Server Books Online (BOL) under the topic "Property Management" and "Using Extended Properties on Database Objects". It is important to note that while the BOL does describe the usage of extended properties, it does not describe the MS_Description property specifically.

How DBDocumentor uses Extended Properties

If you select the "Use enterprise manager descriptions" SQL option, DBDocumentor will make use of the MS_Description extended property, if it finds one. This can provide for a common location to store your object descriptions, assuming you are using SQL Server 2000. If you are using a combination of both DBDocumentor/SQLHelp tags and extended properties, please note that if both are defined for a given object or object attribute, the descriptions from each will be used, with the DBDocumentor/SQLHelp tags appearing first.

Additionally, you can store other meta level data in SQL Server 2000 extended properties by using special Pikauba tags. These tags require no modification to the SQL Server installation to function, and their presence does not negatively impact the operation of SQL Server.

Pikauba_AT

The Pikauba_AT property corresponds to the object level ##AT tag. Using the Pikauba_AT tag allows you to include the table of contents structure directly in the database. The value of the property is exactly the same as it would be for the ##AT tag. Multiple entries can be specified by separating each entry with a semi-colon (;) character.

Pikauba_II

The Pikauba_II property corresponds to the ##II tag. Using the Pikauba_II tag allows you to define an alternate icon for use in the output documentation, and store this definition in the meta data of the database. The value of the property is exactly the same as it would be for the ##II tag.

Pikauba_EP

The Pikauba_EP property corresponds to the ##EP tag. Using the Pikauba_EP tag allows you to store the reason for a given procedures use in the meta data of the data base. The value of the property is exactly the same as it would be for the ##EP tag.

Pikauba_EX

The Pikauba_EX property corresponds to the ##EX tag. Using the Pikauba_EX tag allows you to store the example text associated with the object in the meta data of the data base. The value of the property is exactly the same as it would be for the ##EX tag. Note that SQL Server 2000 extended properties can support a maximum of 8000 characters (4000 UNICODE characters) for the description. This limits the example text to this length. Note that all Pikauba namespace extensions apply for Pikauba_EX.

Pikauba_EXCL

The Pikauba_EXCL property corresponds to the ##EXCL tag. Using the Pikauba_EXCL tag allows you to define an object which while processed by DBDocumentor will not be included in any output file.

Pikauba_EXREF

The Pikauba_EXREF allows you to reference an example entered via the Pikauba_EX property from many other SQL objects. The text used for the description of the property lists the objects whose example text you wish to use for the example text of this specific object. In addition, multiple entries can be specified by separating each entry with a semi-colon (;) character. Doing so effectively creates a concatenation of the example text from multiple objects for use as the example text for a single object.

Pikauba_RD

The Pikauba_RD property corresponds to the ##RD tag. Using the Pikauba_RD tag allows you to store the return values used in a procedure in the meta data of the data base. The value of the property is exactly the same as it would be for the ##RD tag.

Pikauba_RS

The Pikauba_RS property corresponds to the ##RS tag. Using the Pikauba_RS tag allows you to store the descriptions associated with the returned result set information of a view, procedure, or function in the meta data of the data base. The value of the property is exactly the same as it would be for the ##RS tag.

Note: The name of this property however is not Pikauba_RS. Since the ##RS tag requires knowledge of the result set being documented, so too does the Pikauba_RS property. Pikauba_RS property names follow the syntax of Pikauba_RS^xx, where xx refers to the index of the result set as it would be for a corresponding ##RS tag.

Pikauba_RSD

The Pikauba_RSD property corresponds to the ##RSD tag. Using the Pikauba_RSD tag allows you to store the description of the returned result set in the meta data of the data base. The value of the property is exactly the same as it would be for the ##RSD tag.

Note: As with the Pikauba_RS property, the name of this property is not Pikauba_RSD. Since the ##RSD tag requires knowledge of the result set being documented, so too does the Pikauba_RSD property. Pikauba_RSD property names follow the syntax of Pikauba_RSD^xx, where xx refers to the index of the result set as it would be for a corresponding ##RSD tag.

Pikauba_SA

The Pikauba_SA property corresponds to the ##SA tag. Using the Pikauba_SA tag allows you to store the object relationships in the meta data of the data base. The value of the property is exactly the same as it would be for the ##SA tag. Multiple entries can be specified by separating each entry with a semi-colon (;) character.

MS_Description

For completeness, the MS_Description property is described here. The MS_Description property has been defined by Microsoft and corresponds to the description of the object. Specific details of the role the MS_Description property plays in DBDocumentor can be found here.

How to Enter Extended Properties Using Enterprise Manager

SQL Server 2000 only allows you to enter the MS_Description property from Enterprise Manager, and then does not indicate that it is the MS_Description property being accessed. If you wish to use the Pikauba extended properties, you will need to either use Query Analyzer to enter them, or build SQL calling the sp_addextendedproperty procedure to add them.

How to Enter Extended Properties Using Query Analyzer

Using the query analyzer tool for Microsoft SQL Server 2000, you can enter extended property descriptions for most of the items in your database. When entering the extended property, you will need to use one of the properties defined above.

Building the SQL Batch Required for DBDocumentor

Since DBDocumentor does not operate against online databases, you will need to script out the database schema to obtain the value of the extended properties. Details of scripting out a database are covered in the Books Online (BOL) under the topic "scripting databases" or "Documenting and Scripting Databases". The important piece for this discussion is that you must ensure the extended properties are selected for inclusion in the final script.


DBDocumentor Dynamic SQL Parsing Rules

Overview DBDocumentor™

Dynamic SQL Parsing Rules

Beginning with DBDocumentor 3.0, 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 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.

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.

  • SQL executed using EXEC sp_executesql (Microsoft SQL Server)
  • SQL executed using EXECUTE IMMEDIATE ( Sybase ASA )
  • SQL executed using EXECUTE STATEMENT or EXECUTE PROCEDURE (Firebird 1.5)
  • SQL executed inline
  • SQL executed inline from a string variable

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

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:

  • If the SQL to be executed is built up using several conditional statements (e.g. IF ... ELSE ), then only one of the paths will be parsed
  • If the SQL to be executed is built up using CASE statements which impact the structure of the object (e.g. a CASE statement to select columns for a result set), then a warning will be issued to the log file, and the output may be inconsistent
  • If the SQL to be executed is partially built from variables which are input to the procedure or function, the output may contain these variable names (e.g. creating a dynamically named table where the table name is passed into the procedure)
  • If the tables to be joined on are determined conditionally, the data sources listed for the procedure or function may be incomplete.
  • If a function is executed on a variable which is used for a data source, the name of the function will be returned. For example:

'SELECT * FROM ' + RTRIM(@DBName)

Will return a data source of RTRIM

  • If dynamic SQL is used to build additional dynamic SQL, then the output may not fully represent the actual SQL

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


DBDocumentor Command line options

User Interface DBDocumentor™

Command Line Options

To support the batch documentation of SQL databases, as would be present in build scripts, DBDocumentor has a command line version. This command line version, or console version, has the filename of DBDocConsole.exe. DBDocConsole will only operate if DBDocumentor has been registered. If you attempt to execute DBDocConsole.exe while running in shareware mode, DBDocConsole will exit immediately with an error informing you of the registration requirement.

Please note that running DBDocConsole.exe and running DBDocumentor.exe will produce exactly the same output file.

Usage

DBDocConsole takes several command line parameters.

DBDocConsole.exe -f[:]ProjectFile [-d[:]0/1] [-o[:]OutputPath] [-L[:]LogPath] [-e[:]ErrorLevel] [-p]

Where ProjectFile is the fully specified path, including filename, to the DBDocumentor or SQLHelp project file. If the path resides on a network share, please ensure that the user running the command line compilation has access rights to network share.

0/1 is a flag (default of 0) indicating if the HTML Help output should be launched when the compilation completes. This value always overrides the value specified in Step 2 - Options.

OutputPath is a fully specified path, including filename, to the output file to produce, if different than that contained in the project file. If the file resides on a network share, please ensure that the user running the command line compilation has write access to the network share. The path can specified relative to the working folder.

LogPath is a fully specified path to an optional processing log file. If the file resides on a network share, please ensure that the user running the command line compilation has write access to the network share. The path can specified relative to the working folder. If the file can not be created, processing of the project will still occur.

ErrorLevel is an optional value corresponding to the level of detail to be contained in the output log file. Regardless of the error level, certain errors which would impact the quality of the output will always be displayed. It must be expressed as a decimal value.

Specifying the P option will cause the output log file to be piped to the console (stdout).

Specifying no options will cause DBDocConsole to display a usage screen to the console window.

ErrorLevel Values

The ErrorLevel value is any combination of the following values. It must be expressed as a decimal value.

1 | Show the current file being processed
2 | Show the current section within the file. A section is bounded by batch delimiters.
4 | Show the object name currently being processed.
8 | If a DROP occurs prior to a CREATE being found, log this.
16 | Show any parameters passed to an object
32 | Show rowset (result set) column names
64 | Show constraint details
128 | Show table column names
256 | Show values associated with predicates
512 | Show alias details
1024 | Show HTML Help compiler details
2048 | Show dynamic SQL details
4096 | Show security role details

Return values

DBDocConsole will report any errors to the console window in which it is running. It will also return an error number (errorlevel) to the console. Valid errorlevel values are:

  • 0 Indicates a successful run, but also indicates that the usage screen was returned
  • 1 An internal error was encountered. This value was not written to any log file, but was printed to the console window
  • 2 A standard processing error occurred. The error message may have been written to a log file, but was also printed to the console window.
  • 3 The DBDocumentor processing engine was not correctly registered. An error message was returned to the console window.

All error messages returned to the console window are sent to stdout not stderr.


Usage Guidelines

DBDocumentor, like any other developer tool, is capable of considerably more than first glance would indicate. Here we present several hints to derive the most from DBDocumentor.

Define the SQL Interfaces Early

Using the ##OV tag the intent behind the stored procedure can be defined before a single line of SQL is ever written.

  • ##OV allows you to define the parameters passed and document them with ##PD early.
  • ##OV allows you to define the column names of the result set (s) and document them with ##RS
  • ##OV allows you to define transactional procedures with the ##TR tag
  • ##OV allows you to define data modification procedures, before the SQL is written, with the ##MD tag
  • ##OV allows you to define procedures which use cursors, before the SQL is written, using the ##CU tag

Optionally, project global overrides van be defined in the user interface.

Remove ##OV as Objects are Completed

As valuable as the ##OV is during interface design, it can be a hindrance to ensuring the objects are correctly documented. Since ##OV actually prevents the SQL parser from parsing the batch, if there is a departure from the design, DBDocumentor will not be able to locate it.

Optionally, the ##NOV tag can be used to remove the overrides on a per procedure basis.

Run DBDocumentor Frequently

Running DBDocumentor periodically as projects progress can highlight potential bugs before they manifest themselves. DBDocumentor does this by noting those parameters that are not yet documented. If a parameter or column alias is not yet documented, this could indicate a departure from the original design, and likely indicates a situation where code has been developed that is potentially no longer in spec.

Provide Rich Descriptions

Since you never know who might need to use the interfaces being developed, or how far in the future this need might arise, the richer the documentation you provide, the greater the likelihood that ongoing maintenance will be successful.

Document each result set returned

If returning more than one result set, documenting each one independently allows the users of the documentation to better understand each result sets purpose.


HTML Output Option

Overview

DBDocumentor 4.1 and higher provides the option to output a pure HTML frameset representing the database. The pages contained in the frameset are identical to those which would be contained in the CHM output. For authors, this means that there is no special work required to have any custom fixed HTML content included in the HTML frameset.

Frameset Contents

The output frameset consists of several additional pages. The frame page itself is named SQLDoc.html. Any attempt to load a DBDocumentor generated file outside of this page will cause a client side redirection to occur and the frameset will be loaded automatically. The frameset consists of a left hand navigational area, and a right hand content area. All DBDocumentor generated pages will load into the content area. If you have developed fixed content and wish to learn what changes you will be required to implement in order for your custom content to be treated in a similar fashion, please contact Pikauba Support at mailto://support@pikauba.com with an example of your custom content page. Typically within two business days, you will receive a response describing the minimum changes required to support the frameset.

Navigation is accomplished by using tow distinct pages, HTMLToC.html and DBDocHTMLIndex.html. HTMLToC.html presents an identical navigation tree to that of the CHM file which is normally created. In part, this means that any custom groups (##ATG or XML table of contents entries) are automatically included. It is important to note that alternate icons defined by the ##II tag are not supported in the HTML output. DBDocHTMLIndex.html presents an identical index listing as would be presented in the normal CHM. The text for the navigational button text can be overridden using the alternate language output options.

Browser Support

When you select the HTML output option, you will notice that you must select the modern MSDN layout option. This is due to the classic output option using an ActiveX control which is not easily managed by non Microsoft browsers. The HTML files generated have been tested on Microsoft Windows 2000 Professional and higher with browser versions of Internet Explorer 5.5 and 6.0 (version 6.0 works best), Firefox 1.0 and higher, and Opera 8.5 and higher. It should be no surprise that the CHM compatible HTML displays best in Internet Explorer 6.0. Each content page has a series of links "Bookmark", "Print", and "Locate in Contents" which are displayed in the header of the page.

Bookmark Link

The "Bookmark" link is only available if you are running Internet Explorer or Firefox with a web server. Bookmarks in Firefox are implemented as side bar elements, which are only available if the content is obtained using the HTTP protocol (i.e. the file:// moniker doesn't support adding sidebar elements by default). The text for the "Bookmark" link can be overridden using the alternate language output options.

Print Link

The "Print" link prints the content page Internet Explorer and Firefox. In Opera, the result of the clicking on the "Print" link depends upon your printing mode. By default, Opera will print the entire contents of the browser window, including the frame. If you wish to print only the content, Press <Shift>+P three times, then <Ctrl>+P to print the current page and F5 to toggle out of print mode. Once you have done this key stroke dance once, future prints of content during the same browser session will only be of the content window. Please also note that Opera has been observed to occasionally crash in Opera.dll when printing large documents. The crash is present in at least versions 8.5, 8.52, and 8.54 on Windows 2000. Details of the crash have been provided to the Opera developers, so you can probably expect a timely fix. The text for the "Print" link can be overridden using the alternate language output options.

Locate in Contents Link

The "Locate in Contents" link will cause the table of contents to find the first occurrence of the current content page in the table of contents. If the content page is not found in the table of contents, the table of contents will not change. Different browsers highlight the located content differently. Internet Explorer will reformat the table of contents to have the located content be the first item in the navigation window, assuming the complete contents of the navigation window are longer than than the size of the window. Internet Explorer does not highlight the actual entry. Firefox will place a highlight border around the located content entry. Opera will change the background color of the located content entry. The text for the "Locate in Contents" link can be overridden using the alternate language output options.

Miscellaneous Issues

Please note that there are some additional more subtle issues with certain browsers. In Internet Explorer, if the viewer elects to override the stylesheet with a user defined one, they may not be able to scroll the content area correctly. In Firefox, the content area can only be scrolled with the scroll bars. Mouse wheel scrolling does not function. In Opera, if a table of contents folder is opened or closed and the scroll bars would be expected to appear, they may only partially appear, but will be functional.

© 2006 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


XML Output in SQLDocumentation Format

XML Files DBDocumentor™

XML Output in SQLDocumentation™ Format

Overview

DBDocumentor provides an optional XML output option which generates a XML representation of the output contained in the CHM file. The XML file follows the SQLDocumentation schema located in the XSD folder off the product installation path. Within the limitations the restrictions on use detailed below, you are free to develop transformations based on the SQLDocumentation schema. SQLDocumentation files completely describe the contents of your project, including the settings used to compile it, and the result of those settings.

Note: SQLDocumentation files will not be generated in shareware mode (i.e. in trial versions). To see an example SQLDocumentation file, please view the sample file.

Schema Overview

The primary reference point for the schema should be the XSD file. This overview will only present the top level elements of the file. If you have any questions concerning the XSD, please contact support@pikauba.com detailing your question.

Types

The Types element encapsulates the various data types used in DBDocumentor. Generally, whenever a type attribute is present on an element, the range and meaning of the type can be traced back to one of the types contained in the Types element.

Settings

All the project settings are encapsulated in the Settings element.

Index

The Index element provides a listing of all the objects making up the project in an alphabetically sorted list following the conventions of a document index.

toc

The toc element contains the table of contents, organized by chapter with the content sorted alphabetically. Only the groups defined in the project XML file for which content is present will be output in the toc.

Objects

The Objects element contains all the SQL objects making up the project, organized by object type.

Restrictions on Schema Use

The SQLDocumentation schema is a copyrighted work and as such there are several restrictions on the use of the SQLDocumentation XML schema. Please note that the intent of these restrictions is only to protect the copyright of the schema. If you wish to develop against the schema, please do so, just obtain the proper license. SQLDocumentation files are not intended to be final output files.

The restrictions are summarized here:

  • If you want to build any transformations for internal usage based on the SQLDocumentation schema, you are welcome to do so, provided you have an accompanying license to use DBDocumentor as a registered user.
  • If you do build any transformations based on the SQLDocumentation schema, and decide to make the transformations public, that is to say "not for internal usage", please contact our sales department at sales@pikauba.com for a schema development license. Since only registered users are licensed to build any transformations, this is largely a procedural formality to ensure that any future changes made to the schema are done so in a fashion as not to break your transformations. This also ensures that should an incompatible schema update be required, you can be alerted to it with sufficient time to modify your transformations.
  • If you are wishing to develop transformations or products which generate documents following the SQLDocumentation schema, please contact our sales department at sales@pikauba.com detailing the nature of your product. Schema development licenses may be available either on an end user basis (e.g. the end user is a registered user of DBDocumentor), or on a product basis (issued to a product developer and not dependent upon the end user being a registered user of DBDocumentor).
  • If you are wishing to offer services which will include as deliverables documents following the SQLDocumentation schema (e.g. SQLDocumentation via a web service), whether produced by DBDocumentor or not, you will need a schema development license. The SQLDocumentation output is not intended to be a final document, where such a document may be used by someone who is not a registered user. Please contact our sales department at sales@pikauba.com, detailing the type of service being offered, for the schema development license. As with products generating SQLDocumentation documents, development licenses are available based on if the end user is a registered user of DBDocumentor or not.

© 2005 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


Language Overrides

Documentation Procedures DBDocumentor™

Alternate Output Language Support

Beginning with version 4.0 of DBDocumentor, users have the ability to override the textual elements DBDocumentor uses in the output documentation. These overrides could be as simple as local preferences (i.e. by default DBDocumentor refers to a group of INDEX statements as "Indicies", however, the word "Indexes" is equally valid. More complex overrides are possible, including localizing the output document to your preferred language.

Note: While it is possible to provide overrides in any language, the default CHM search option will build its search dictionary based on the English language. This means that language options such as plurality are not respected in the CHM search options for non-English languages.

Language overrides are performed in two distinct locations. Full localization of the output will require modification in both places, and will require usage of the XML project file.

Table of Contents Overrides

Every folder name used by default in the table of contents can be overridden by providing a value for the XML attribute DisplayText for each item in the Standard group you wish to override. For example, to override the default value of "Indices", you could supply the following XML:

<?xml version="1.0" encoding="Windows-1252" ?>
<project generator='DBDocumentor' version='4.0'>
    <groups>
            <standard>
            <group name="Indices" DisplayText="Indexes">
                <description>The following indexes are defined in this database</description>
            </group>
        </standard>
    </groups>
</project>

For details on the table of contents section of the XML project file, please click here. The upper left header text on object pages in the modern MSDN layout is taken from the top level name associated with the table of contents where the content will be placed. This means that if you supply DisplayText, that text will also be used for the header text.

Page Content Overrides

Complete localization of the output is possible by supplying an alternate language file via the XML project file Config/Settings section item named Language. The alternate language file is a sectioned INI file with the following sections. All default values listed below are for TSQL parsers. If you decide to supply an override file, you must supply values for all options, otherwise errors will occur. You can use the default DBDocumentor language files for reference. They are located in the install folder under the Templates\1033\TSQL\Lang.ini. Firebird defaults are located in Templates\1033\Firebird\Lang.ini.

Column

This section describes the column layout of a table, or of a table valued user defined function. The following keys are present:

  • Column. This key is used as a section header and has the default value is "Columns".
  • Name. This key is used as a column header and has the default value of "Name".
  • DataType. This key is used as a column header and has the default value of "Data type".
  • Nullable. This key is used as a column header and has the default value of "Nullable".
  • SeedValue. This key is used as inline description text and has the default value of "Column has identity seed value of".
  • Step Value. This key is used as inline description text and has the default value of "with a step value of".

Constraint

This section describes the constraints section of a table. The following keys are present:

  • Constraint. This key is used as a section header and has the default value of "Constraints".
  • Name. This key is used as a column header and has the default value of "Name".
  • Type. This key is used as a column header and has the default value of "Type".
  • Columns. This key is used as a column header and has the default value of "Columns".
  • NA. This key is used as a column header and has the default value of "N/A".
  • Unknown. This key is used as inline description text when the constraint type is not known, and has the default value of "Unknown".
  • Value. This key is used as inline description text if a default value is supplied for the constraint. The default value is "Value".
  • Reference Table. This key is used as inline description text if a foreign key is defined. The default value is "Reference table".

Error

This section describes the errors raised section of a trigger, stored procedure, view or user defined function summary listing. The following keys are present:

  • Message. This key is used as a column header and has the default value of "Message".
  • ID. This key is used as a column header and has the default value of "ID".
  • Severity. This key is used as a column header and has the default value of "Severity".
  • State. This key is used as a column header and has the default value of "State".
  • Errors Raised. This key is used as a section header and has the default value of "Errors raised".

General

This section contains a listing of common textual elements. The following keys are defined:

  • Description. This key is used for all "Description" headers.
  • Yes. This key is used for all values requiring the word "yes".
  • No. This key is used for all values requiring the word "No".
  • Data Source Activity. This key is used as a section header and has the default value of "Data Source Activity".
  • Modifies. This key is used as a column header and has the value of "Modifies".
  • Accesses. This key is used as a column header and has the value of "Accesses".
  • Modifications. This key is used as a column header and has the value of "Modifications".
  • Called Procedures. This key is used as a section header and has the value of "Called procedures".
  • Called Functions. This key is used as a section header and has the value of "Called functions".
  • Calling Procedures. This key is used as a section header and has the value of "Calling procedures".
  • Calling Functions. This key is used as a section header and has the value of "Calling functions".
  • Calling Triggers. This key is used as a section header and has the value of "Calling triggers".
  • Calling Views. This key is used as a section header and has the value of "Calling views".
  • Calling Generic Batches. This key is used as a section header and has the value of "Calling generic batches".
  • Referring Functions. This key is used as a section header and has the value of "Referring functions".
  • Referring Procedures. This key is used as a section header and has the value of "Referring procedures".
  • Referring Tables. This key is used as a section header and has the value of "Referring tables".
  • Referring Views. This key is used as a section header and has the value of "Referring views".
  • Accessed By. This key is used as a section header and has the value of "Accessed by".
  • Modified By. This key is used as a section header and has the value of "Modified by".
  • Override Message. The key supplies the message used when the ##OV tag is used in a batch.
  • Used In View. This key is used as a section header and has the value of "Used in view:".
  • Used In Trigger. This key is used as a section header and has the value of "Used in trigger:".
  • Used In Procedure. This key is used as a section header and has the value of "Used in procedure:".
  • Used In Function. This key is used as a section header and has the value of "Used in function:".
  • On Function. This key is used as a section header and has the value of "On function:".
  • On Object. This key is used as a section header and has the value of "On object:".
  • On Procedure. This key is used as a section header and has the value of "On procedure:".
  • On Table. This key is used as a section header and has the value of "On table:".
  • On View. This key is used as a section header and has the value of "On view:".
  • Linked Tables. This key is used as a section header and has the value of "Linked tables".
  • Source Core. This key is used as a navigational entry and has the value of "Source code".
  • Summary Listing. This key is used as a navigational entry and has the value of "Summary listing".
  • Return Values. This key is used as a section header and has the value of "Return values".
  • Value. This key is used in inline descriptions and has a default value of "Value". Please note that other sections may define a key of Value, and that if they do, then that section's key is always used. In other words, a locally defined key is always the key for that section.
  • Default value. This key is used in inline descriptions and has a default value of "Default value".
  • Syntax. This key is used as section header and has a value of "Syntax".
  • Object Type. This key is used as a section header and has a value of "Object type".
  • Source Located. This key is used to denote where the source code for the SQL batch is located.
  • CompiledOn. This key is used to denote when the document was prepared.
  • DefinedSynonyms. This key is used as a section header and has the value of "Defined synonyms"
  • Toc Contents Link. This key is used in the HTML output option to provide the text for the "Contents" tab of the table of contents and index pages. If has a default value of "Contents".
  • ToC Contents Title. This key is used in the HTML output option to provide the alternate text for the "Contents" tab of the table of contents and index pages. It has a default value of "Table of Contents".
  • ToC Index Link. This key is used in the HTML output option to provide the text for the "Index" tab of the table of contents and index pages. It has a default value of "Index".
  • ToC Index Title. This key is used in the HTML output option to provide the alternate text for the "Index" tab of the table of contents and index pages. It has a default value of "Index".
  • Bookmark Title. This key is used in the HTML output option to provide hyperlinks in the content presenting an option for the user to bookmark the page. It has a default value of "Bookmark"
  • Print Title. This key is used in the HTML output option to provide hyperlinks in the content presenting an option for the user to print the page content. It has a default value of "Print"
  • Synchronize. This key is used in the HTML output option to provide hyperlinks in the content presenting an option for the user to locate the first occurrence of the page in the table of contents. It has a default value of "Locate in contents"

Index

This section describes the index listing of the summary listing for an index. The following keys are present:

  • On. This key is used in string concatenation forming: Index "on" Object.
  • Clustered. Denotes if the index is clustered. The default value is "Clustered".
  • NonClustered. Denotes if the index is not clustered. The default value is "Non Clustered".
  • Column. This key is used as a column header for the column listing used in the index summary. The default value is "Column".
  • Columns. This key is used as the section header for the column listing in the index summary. The default value is "Columns".
  • Unique. Denotes if the index is unique. The default value is "Unique".
  • XML. Denotes is the index is on XML data. The default value is "XML".
  • Details. This key is used as a column header for the column listing used in the index summary. The default value is "Details".

Message

This section describes the summary listing for a system message. The following keys are defined:

  • Message. This key is used as the section header in the summary listing. The default value is "Message".
  • ObjectsUsing. This key is used as the section header for the listing of objects using this system message. The default value is "Objects using this message".
  • ID. This is the column header for the "ID" column.
  • Severity. This key is used as a column header and has the default value of "Severity".

Parameter

This section describes the parameter listing of a stored procedure or user defined function. The following keys are defined:

  • DataType. This key is used as a column header and has the default value of "Data Type".
  • Required. This key is used as a column header and has the default value of "Required".
  • Output. This key is used as a column header and has the default value of "Output".

Permission

This section describes the permission type of an object. It has a single key.

  • Accesses. This key is used as a column header and has the default value of "Accesses".

Properties

This section describes the various properties listings used for many of the object listings. An example of a property listing is in the summary listing of a stored procedure. The following keys are defined:

  • Properties. This key is used as a section header. It has a default value of "Properties".
  • DataType. This key is used as a column header and has a default value of "Output data type".
  • Transactional. This key is used as a column header and has a default value of "Transactional".
  • Cursors. This key is used as a column header and has a default value of "Uses cursors".
  • Executes. This key is used as a column header and has a default value of "Executes procedures".
  • Dynamic. This key is used as a column header and has a default value of "Dynamic content".
  • Encrypted. This key is used as a column header and has a default value of "Encrypted".
  • Modifies Data. This key is used as a column header and has a default value of "Modifies data".
  • New Data Type. This key is used as a column header for user defined types and has a default value of "New data type".
  • Derived From. This key is used as a column header for user defined types and has a default value of "Derived from".
  • Nullable. This key is used as a column header for user defined types and has a default value of "Nullable".
  • User. This key is used as a column header for user defined types and has a default value of "User".
  • Method. This key is used as a column header for user defined functions and has a default value of "Entry point".
  • Module. This key is used as a column header for user defined functions and has a default value of "Module".

ResultSet

This section describes the summary listing for result listings of stored procedures, views, and multi-valued user defined functions. The following keys are defined:

  • Title. This key is used as a section header. The default value is "Output Recordset".
  • Column. This key is used as a column header and has a default value of "Column".
  • DataSource. This key is used as as column header and has a default value of "Data source".

Trigger

This section describes the summary listing for triggers. The following keys are defined:

  • Before. This key is used to denote "Before" triggers.
  • After. This key is used to denote "After" triggers.
  • Instead. This key is used to denote "Instead of" triggers.
  • Unknown. This key is used to denote triggers of an "Unknown" type.
  • Summary. This key is used as a section header and has a default value of "Summary".
  • Delete. This key is used to denote triggers triggered for "Delete" operations.
  • Update. This key is used to denote triggers triggered for "Update" operations.
  • Insert. This key is used to denote triggers triggered for "Insert" operations.
  • Type. This key is used as a column header and has a default value of "Type".

TypeName

This section describes the various data types or other organizational elements of a DBDocumentor output. The following keys are defined:

  • View. A "Data view".
  • CTE. A "Common table expression".
  • Triggers. A listing of "Triggers".
  • Indices. A listing of "Indices".
  • UDT. An "User defined type".
  • Trigger. A "Trigger".
  • Table. A "Table".
  • Role. A "Database role".
  • Generic. A "Generic batch".
  • Procedure. A "Stored procedure".
  • Message. A "System message".
  • Index. An "Index".
  • Overview. A page header used on overview pages of the modern MSDN layout.
  • Example. An "Example".
  • Examples. A listing of "Examples".
  • Object. An "Object".
  • UDF. An "User defined function."
  • SeeAlso. A "See also" listing.
  • AppliesTo. An "Applies to" listing.


Documentation Licensing Agreement

Please note that this is an abridged version of the licensing agreement associated with DBDocumentor™. This abridged version is present for those users who (a) downloaded the documentation separately from the product, or (b) are viewing the documentation prior to product use. This agreement follows a plain English format.

  1. RIGHTS TO USE

    By downloading this documentation, or viewing this documentation prior to actual use of the product (DBDocumentor™), you are agreeing that the procedures and techniques described in this documentation are proprietary to Pikauba Software. You have the right to use this documentation in the use of and evaluation of DBDocumentor™, but may not use this documentation for any other purpose, including:
  • Product reviews, without previously informing Pikauba Software of this intent. This restriction is in place to ensure that any reviews are conducted with the most recent public version of the product, and to ensure that any reviews are from product usage, not details present in documentation.
  • Design of competing products, or inclusion of feature concepts in products not directly competing with Pikauba Software products. This restriction is in place largely to protect any derivative works from being developed. If you believe that you might wish to make use of any concept presented here in a product, please contact sales@pikauba.com. In many cases a simple agreement can be reached allowing specified derivations to be conducted.
  • Extraction of product screen shots or other images for any use. If you are planning on writing a product review, or providing any level of image linkage related to this product, we have found that use of the most recent image is the most effective course of action. Since product development is ongoing, the images you may have obtained from this documentation may no longer be relevant. Please contact sales@pikauba.com if you wish to make use of product images and details can be arranged to ensure your content is as accurate as possible.
  2. WARRANTY

    Use of this documentation does not convey any warranty, or suitability to purpose of either the documentation or its associated product. This documentation was obtained free of any charge from Pikauba Software. In no event shall Pikauba Software be liable for any damages, including any loss of revenue, loss of profit, incidental, indirect or consequential damages resulting from the use of this documentation, or its associated product. Further details relating to limitation of liability can be found in the file License.txt which is included with the product.
  3. COPYRIGHT AND TRADEMARKS

    The contents of this documentation, and of DBDocumentor™ are protected by copyright. DBDocumentor and SQLDocumentation are trademarks of Pikauba Software. You are not authorized to register or use domain names reflecting DBDocumentor, SQLDocumentation, or variants thereof in whole or in part.

© 2003 - 2006 Pikauba Software. All rights reserved.


DBDocumentor - Default Settings Manager

User Interface DBDocumentor™

Default Settings Manager

During the installation process, the default settings used for new projects will be assigned. The defaults used for an upgrade or a full installation will be the same, but if you are upgrading your installation from a previous version, the installation defaults won't automatically be applied.

Default settings will be one of the following:

  • If DBDocumentor has never been installed on the machine, the default settings will be those from the installation
  • If DBDocumentor has previously been installed, and was not uninstalled, the default settings will match those of the last DBDocumentor project opened prior to the upgrade to DBDocumentor 3.x, or higher.
  • Once DBDocumentor 3.x, or higher, has been installed, the settings are defined by the Default Settings Manager. The Default Settings Manager will allow you to define values to be used for all new projects. The user interface is functionally identical to the advanced project settings dialog of DBDocumentor.

© 2001- 2006 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


DBDocumentor - SQL attributes documented

Documentation Procedures DBDocumentor™

What attributes of SQL objects are documented by DBDocumentor™?

Looking at both the sample files, this manual and running DBDocumentor™ against some of your SQL may not answer this fundamental question. This section seeks to describe those attributes and how they are documented within DBDocumentor. If there is an aspect you are seeking, please don't hesitate to contact us, it may already be in the product, or may be planned for a future version. Each object type will be covered in its turn.

Note: DBDocumentor 4.00 and higher supports multiple SQL dialects, but for the sake of clarity in descriptions, Microsoft SQL Server 2000 terminology is typically used in this manual.

Common items

Several documentation aspects are common to all SQL objects, regardless of type. These common items include:

  • The object type
  • The object name
  • A detailed description for the object
  • Optionally the source file location for the object
  • Optionally the actual source used to build the object
  • If the SQL object supports RAISEERROR then any errors raised will be listed in the output (SQL dialect specific)

Data views

Data views are used to return a list of records meeting a predefined set of criteria. The documentation options present for data views are:

  • If the data view makes use of transactions
  • If the data view makes use of cursors
  • If the data view is the result of dynamic SQL
  • If the data view is encrypted (SQL dialect specific)
  • The output result set, the column name and your description for the column. Note that if the column name is either a table/view or alias of a table/view whose entire column structure is being returned, DBDocumentor will attempt to locate the table/view and hyperlink to it.
  • Any triggers defined for the view
  • Any indices on the view
  • Any data sources accessed by the view
  • If the view is used as a data source in any objects, then those objects will be listed
  • Any user defined functions used in the data view
  • Any security roles on the stored procedure

View the documentation procedure for data views.

Indices (Indexes)

Indices can be defined for both tables and data views. Regardless of the object being indexed, the functionality of the index remains the same, and the documentation details are thus also the same. The following items are documented for indices:

  • Uniqueness
  • Clustering of data
  • If the index is on XML data (SQL dialect specific)
  • The table or view on which the index acts
  • The columns used to build the index

If the table or view used to build the index is also contained in the same documentation project, a hyperlink from the index to the table or view will be enabled. If the table or view used to build the index is not contained in the same documentation project, DBDocumentor can not determine if the object is a view or a table and refer to it as simply "Object".

View the documentation procedure for indices.

Stored procedures

Stored procedures are SQL scripts potentially accepting parameters, and potentially returning data. The output data can be returned via input parameters, as a recordset or as a return value. A stored procedure can manipulate data, make use of cursors, be transactional and execute other (nested) procedures. The DBDocumentor produced documentation reports on all these attributes. General documented items are:

  • Transactional nature of the procedure
  • If the procedure makes use of dynamic SQL
  • If the procedure is encrypted (SQL dialect specific)
  • If the procedure manipulates data under any of its paths of execution
  • If the procedure uses cursors under any of its paths of execution
  • If the procedure executes any other procedure under any of its paths of execution. If the procedure does execute another procedure, and that procedure is present in the same project, a hyperlink will be present between the two procedures allowing you to see both who is calling and who called a given procedure.
  • Any data sources accessed or modified by the stored procedure
  • Any user defined functions used in the stored procedure
  • Any security roles on the stored procedure

View the documentation procedure for stored procedures.

Input parameters

Input parameters to stored procedures have the following attributes in DBDocumentor:

  • The assigned name
  • A data type (if the data type is a user defined data type and is present in the documentation project, a hyperlink will be present between the procedure and the user defined data type)
  • If the parameter is required
  • If the parameter is an output parameter
  • The default value of the parameter (if any)

Output data

Data can be returned from a stored procedure via input parameters (configured as output parameters), as return values, and as a recordset (dataset). DBDocumentor has the following capabilities in describing output data:

  • If output via output parameter, the options are identical to those for input parameters
  • If output via return value, the numerical constant (or SQL variable used to return the constant) being returned
  • If output via result set, the column name and your description for the column. Note that if the column name is either a table/view or alias of a table/view whose entire column structure is being returned, DBDocumentor will attempt to locate the table/view and hyperlink to it.

Tables

Data tables are used to store either permanent or temporary data used in the database. If a table is temporary, its life span can be for the life of the current database connection, or it can be global to the database in which case the life span is governed by the SQL instance. Temporary tables can be documented by DBDocumentor, but only if there is no corresponding drop of the table. If the same table name is used for different temporary tables, DBDocumentor will only retain the details of the last one to be processed.

The following items are documented for all table types:

  • Column structure
  • Column data type (if the data type is a user defined data type present in the same project, a hyperlink will be present between the table and the data type)
  • Nullability of the column
  • If the column is an identity column, both the seed and increment values will be recorded
  • Constraints associated with the table.
  • If the constraint is a DEFAULT, the default value will be listed
  • If the constraint is a FOREIGN KEY, and the referred table is present in the same project, a hyperlink will be present between the two tables
  • Any tables referring to the current table are listed, along with the description supplied for the index
  • Any indices on the table are listed, along with the description supplied for the index
  • Any objects accessing or modifying the table
  • Any security roles on the table

View the documentation procedure for data tables.

Triggers

Triggers can be defined to fire when an underlying table or view is modified. The items documented for triggers are:

  • If the trigger becomes transactional under any path of execution
  • If the trigger modifies data under any path of execution
  • If the trigger makes use of cursors under any path of execution
  • If the trigger makes use of dynamic SQL
  • If the trigger is encrypted (SQL dialect specific)
  • If the trigger executes stored procedures under any path of execution
  • The table or view the trigger acts upon
  • The type of trigger
  • The data modification required to fire the trigger
  • Any data sources accessed or modified by the trigger
  • Any user defined functions used in the trigger
  • Any security roles on the trigger

View the documentation procedure for triggers.

User defined data types

User defined data types allow the database designer to provide a more meaningful description of data by extending a base data type. DBDocumentor only processes added data types. If you remove a data type in a batch after DBDocumentor has processed it, the output documentation will still contain the data type definition.

  • The user define name for the new data type
  • The base data type
  • The nullability of the new data type
  • If a defined type owner is specified, the name of the owner (SQL dialect specific)
  • If a default value is specified, the default value for the data type (SQL dialect specific)
  • If a check constraint is defined, the value for the constraint (SQL dialect specific)
  • Any stored procedures making use of the data type
  • Any tables making use of the data type
  • Any user defined functions making use of the data type
  • Any triggers making use of the data type

View the documentation procedure for user defined data types.

User defined functions

User defined functions (or UDFs to some people) were introduced in SQL Server 2000 and provide the ability to return scalar data types (e.g. bigint, or a user defined type) and return data sets (effectively tables), all while taking parameters. These capabilities make UDFs one of the most versatile SQL query objects available. Consider the UDF as a cross between and a stored procedure and a parameterized data view and you've got the general idea.

The items available for documentation will vary by the type of the function, but generally are:

  • The assigned name of any input parameters
  • The data type associated with any input parameters. If the data type is a user defined data type and is present in the documentation project, a hyperlink will be present between the procedure and the user defined data type.
  • The output return type for the function. If the data type is a user defined data type and is present in the documentation project, a hyperlink will be present between the procedure and the user defined data type.
  • If the function returns a table, the column structure of the table is defined as a result set.
  • If the function makes use of transactions (SQL dialect specific)
  • If the function uses cursors (SQL dialect specific)
  • If the function is encrypted (SQL dialect specific)
  • If the function makes use of dynamic SQL (SQL dialect specific)
  • If the function is row set based and used as a data source in any objects, then these objects will be listed (SQL dialect specific)
  • If the function is scalar and used in any objects, then these objects will be listed (SQL dialect specific)
  • The method name and module entry point (SQL dialect specific)
  • Any security roles on the function

View the documentation procedure for user defined functions.

Security roles

Security roles allow the database designer to restrict or grant access to objects thereby controlling the security risk associated with the data in the database.

View the documentation procedure for security roles.

Generic batches

A generic, or ad-hoc, batch is simply a SQL batch which does not create one of the above SQL objects. Most commonly a generic batch would be used for initial data population, data scrubbing operations, or scheduled tasks.

Generic batches have the following attributes documented:

  • Transactional nature
  • Dynamic SQL usage
  • Cursor usage
  • Function and stored procedure calls
  • Function, data view and table usage in queries

View the documentation procedure for generic batches.

System error messages

System messages are defined in SQL Server databases by executing sp_addmessage. These messages are used in RAISERROR commands. System messages are documented, and categorized in the table of contents.

System messages have the following attributes documented:

  • Message identifier
  • Message text
  • Message severity
  • Functions, data views and procedures referencing the message

View the documentation procedure for system messages.

Synonyms

SQL Server 2005 introduced the concept of object synonyms (or aliases).

Synonyms have the following attributes documented:

  • Parent object type and name
  • Objects referencing the synonym

View the documentation procedure for synonyms

Microsoft Reporting Services RDL

SQL Server 2000 and SQL Server 2005 have an optional component known as Reporting Services. Reporting Services provides an XML based report definition language which can query a data source and generate resultant reports in many different formats. Beginning with DBDocumentor 4.20, the RDL XML files can be processed and reported on.

RDL files have the following attributes documented:

  • If the report makes use of transactions (SQL dialect specific)
  • If the report uses cursors (SQL dialect specific)
  • If the report makes use of dynamic SQL (SQL dialect specific)
  • If the report executes stored procedures
  • If the report manipulates data under any of its paths of execution
  • If the report executes any stored procedures under any of its paths of execution. If the report does execute stored procedures, and that procedure is present in the same project, a hyperlink will be present between the report and the procedure.
  • Any data sources accessed or modified by the report
  • Any user defined functions used in the report
  • Any errors raised from the report

View the documentation procedure for Reporting Services RDL

© 2001- 2006 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


How to Document Data Views

Describing the functionality and interfaces exposed by data views is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a view?

DBDocumentor produced output for data views includes:

  • The output result set from query in the view. See below for the method of annotating the result set.
  • A listing of any tables, views and functions queried in building the output result set. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the view to the source object.
  • A listing of any tables or views whose contents are modified by the query in this view. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the view to the modified object.
  • A listing of any stored procedures used in the views' query. See below for the method of annotation for the usage model of the procedure. If the stored procedure is contained in the project, hyperlinks are present from the view to the stored procedure.
  • A listing of any triggers defined on the view which are contained in the project. As with the data source listing, the descriptions used for the triggers come from the source trigger. Hyperlinks are present from the view to the trigger.
  • A listing of any indices (indexes) defined on the data view, and contained in the project. As with the data source listing, the descriptions used for the indices come from the source index. Hyperlinks are present from the view to the indices.
  • A listing of the security roles (permissions) defined on the data view, and contained in the project. As with the data source listing, the descriptions used for the roles come from the source role. Hyperlinks are present from the view to the security role.
  • A listing of objects contained in the project which modify the data in this data view. As with the data source listing, the descriptions used for the objects come from the source object. Hyperlinks are present from the view to the object modifying this view.
  • A listing of any errors raised from the view. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the view to the system message.
  • An indication of if the view is transactional, or participates in transactions
  • An indication of if the view uses server side cursors
  • An indication of if the view executes stored procedures
  • An indication of if the view contains dynamic SQL
  • An indication of if the views' source code is encrypted. If the source code is marked as encrypted, the source code link will not be present, and the output XML will not contain the source code. Source code encryption does not impact the level of detail present in the summary listing.

Describe the view

To describe the functionality of the view, you use the ##BD tag (or one of its variants). Since data view creation must be unique to a batch, there is no need to specify the name of the view with the ##BD tag.

Describe the result set

You describe the intent of the result set using the ##RSD tag, and the data contained in each column using the ##RS tag.

Note: While a data view only returns a single result set, DBDocumentor will return multiple results for documentation in the event that the output of the view is made up of conditional statements.

Describe the reason for stored procedure usage

If the view executes other stored procedures, you can describe why a given stored procedure is used by using the ##EP tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific view is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the view and objects referencing it, and between objects used in the view. Should you desire to establish a functional relationship (e.g. between a view denoting current versus archive account information), you can use the ##SA tag.

Define any usage examples

The ##EX tag allows you to optionally describe how the view should be used.


How to document indices

Documentation Procedures DBDocumentor™

How to Document Indices (Indexes)

Describing the purpose of an index is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

Note: SQL 2000 introduced the concept of indices on data views. DBDocumentor fully supports indexed views.

What is included in the DBDocumentor output for an index?

DBDocumentor produced output for indices includes:

  • An indication of the type of index, unique, clustered or non clustered.
  • The name of the indexed object. If the indexed object is contained in the project, a hyperlink is present to the indexed object.
  • A listing of the columns making up the index. The descriptions for the individual columns come from the source object.

Describe the purpose of the index

To describe the purpose of an index on a table or view, use the ##IXD tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific index is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the index and its associated table or view. Should you desire to establish a functional relationship (e.g. between the index and the queries for which the index improves performance), you can use the ##SA tag.


How to Document Security Roles

DBDocumentor is able to describe the security roles contained within a database, and the objects the roles apply to. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a role?

DBDocumentor produced output for roles includes:

  • A list of the statement operations granted. If the object being granted a permission is included in the project, its description will be automatically included, and a hyperlink generated to the object.
  • A list of the statement operations denied. As with statement operation grants, if the object is included in the project, its description will be automatically included, and a hyperlink generated to the object.
  • A list of the object access permissions granted. If the object being granted a permission is included in the project, its description will be automatically included, and a hyperlink generated to the object.
  • A list of the object access permissions denied. As with permission grants, if the object is included in the project, its description will be automatically included, and a hyperlink generated to the object.

Describe the purpose of the role

To describe the purpose of a security role, use the ##RLD tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific role is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the role and its SQL objects. Should you desire to establish a functional relationship (e.g. between a role granting access and a corresponding role denying access), you can use the ##SA tag.


How to document Reporting Services RDL

Documentation Procedures DBDocumentor™

How to Document Reporting Services RDL Files

Describing the queries used in and the data sources for a Microsoft Reporting Services RDL file is one of the primary task of DBDocumentor. Unlike documenting raw SQL files, RDL documentation is accomplished using XML namespaces. Please note that the XML namespace used for RDL files differs from the namespace used within raw SQL files. In order to supply the extended annotation supported by DBDocumentor, please defined the following namespace on the Report node of the RDL: http://www.pikauba.com/schemas/microsoft/rdl. For the purposes of this procedure, the namespace alias will be assumed to be pikauba.

Note: DBDocumentor fully supports Microsoft Reporting Services for SQL Server 2000 and Reporting Services 2005. The version of Reporting Services is validated using the XML namespaces contained in the RDL file. If there is no Reporting Services namespace defined, then DBDocumentor will not process the RDL file.

What is included in the DBDocumentor output for an RDL file?

DBDocumentor produced output for RDL files includes:

  • A listing of the named queries in the report
  • For each named query, the input parameters to the query
  • For each named query, the structure of the result set returned from the query
  • For each named query, the data sources used in the query. Please note that this can optionally include any temporary tables and common table expressions which may be defined in the query.
  • A listing of any tables, views and functions queried by all the queries in the report. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the report to the source object.
  • A listing of any tables or views whose contents are modified by the report. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the report to the modified object.
  • A listing of any stored procedures used in the queries of the report. See below for the method of annotation for the usage model of executed procedures. If the stored procedure is contained in the project, hyperlinks are present from the report to the executed stored procedure.
  • A listing of any user defined functions contained in the project which are called by this report. As with the data source listing, the descriptions used for the calling functions come from the calling function. Hyperlinks are present from the report to the user defined function.
  • A listing of any errors raised from the queries in the report. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the report to the system message.
  • An indication of if the procedure is transactional, or participates in transactions
  • An indication of if the procedure uses server side cursors
  • An indication of if the procedure executes stored procedures
  • An indication of if the procedure contains dynamic SQL

Describe the report

If you use the Description element of the Report element, DBDocumentor will automatically use this as the description for the report.

Describe the query parameters

To describe the data transferred in a parameter, in the QueryParameter element, create a pikauba:PD element and supply the description.

The following fragment describes a parameter whose value is the start time for a query.

<QueryParameter Name="@Start">
<Value>=Parameters!Start.Value</Value>
<pikauba:PD>Start time</pikauba:PD>
</QueryParameter>

Describe the data set intent

To describe the intent of the data set used in the report, in the DataSet element, create a pikauba:RSD element and supply a description for the intent.

The following fragment describes the intent for a test data set.

<DataSet Name="RDLTest">
<pikauba:RSD>This is the main query for the report</pikauba:RSD>

Describe the fields in the data set

To describe the data contained in each column, or field, of the data set; in the Field element, create a pikauba:RS element and supply a description for the column.

The following fragment describes the time_stamp column of a data set.

<Field Name="time_stamp">
<DataField>time_stamp</DataField>
<pikauba:RS>Time stamp of the event</pikauba:RS>
</Field>

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific report is a member of a given functional area by using the pikauba:AT element. The pikauba:AT element is a child node of the RDL Report element.

The following fragment associates the report with the Summary Reports table of contents entry.

<Report>
<pikauba:AT>Summary Reports</pikauba:AT>

Establish object relationships

DBDocumentor will automatically establish any SQL relationships between the RDL report and objects referencing it, and between objects used in the report queries. Should you wish to define additional relationships, you can use the pikauba:SA element. The pikauba:SA element is a child node of the RDL Report element. Multiple entities are supported, and are delimited by a semi-colon.

The following fragment associates the report with peer reports quarterly_summary and ytd_summary.

<Report>
<pikauba:SA>quarterly_summary;ytd_summary</pikauba:SA>


How to Document Stored Procedures

Describing the functionality and interfaces exposed by stored procedures is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a stored procedure?

DBDocumentor produced output for stored procedures includes:

  • The input parameters to the procedure. Included with the parameter is its data type, if it is an optional parameter, if the parameter is an output parameter, and any default value. See below for the method of annotating parameters.
  • The output result sets from queries in the stored procedure. See below for the method of annotating result sets.
  • A listing of any tables, views and functions queried in the procedure. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the procedure to the source object.
  • A listing of any tables or views whose contents are modified by the procedure. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the procedure to the modified object.
  • A listing of any return values returned from the procedure. Multiple return values may be listed, each representing the return for a specific code path. See below for the method of annotating return values.
  • A listing of any stored procedures used in the queries in the procedure. See below for the method of annotation for the usage model of executed procedures. If the stored procedure is contained in the project, hyperlinks are present from this procedure to the executed stored procedure.
  • A listing of any stored procedures contained in the project which are calling this procedure. As with the data source listing, the descriptions used for the calling procedures come from the calling procedure. Hyperlinks are present from this procedure to the calling procedures.
  • A listing of any triggers contained in the project which are calling this procedure. As with the data source listing, the descriptions used for the calling triggers come from the calling trigger. Hyperlinks are present from this procedure to the calling triggers.
  • A listing of any data views contained in the project which are calling this procedure. As with the data source listing, the descriptions used for the calling views come from the calling view. Hyperlinks are present from this procedure to the calling data view.
  • A listing of any user defined functions contained in the project which are calling this procedure. As with the data source listing, the descriptions used for the calling functions come from the calling function. Hyperlinks are present from this procedure to the calling user defined function.
  • A listing of any generic batches contained in the project which are calling this procedure. Hyperlinks are present from this procedure to the summary listing for the generic batch.
  • A listing of the security roles (permissions) defined on the procedure, and contained in the project. As with the data source listing, the descriptions used for the roles come from the source role. Hyperlinks are present from the procedure to the security role.
  • A listing of any errors raised from the procedure. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the procedure to the system message.
  • An indication of if the procedure modifies data
  • An indication of if the procedure is transactional, or participates in transactions
  • An indication of if the procedure uses server side cursors
  • An indication of if the procedure executes stored procedures
  • An indication of if the procedure contains dynamic SQL
  • An indication of if the source code is for the procedure is encrypted. If the source code is marked as encrypted, the source code link will not be present, and the output XML will not contain the source code. Source code encryption does not impact the level of detail present in the summary listing.

Describe the procedure

To describe the functionality of the stored procedure, you use the ##BD tag (or one of its variants). Since stored procedure creation must be unique to a batch, there is no need to specify the name of the procedure with the ##BD tag.

Describe the parameters

To describe the data transferred in a parameter, you use the ##PD tag. The name of the parameter is required for this tag, but you do not include the @ symbol which precedes the name of the parameter.

Describe any optional return values

If the stored procedure returns some information via a return value, you describe the intent behind a given return value via the ##RD tag. If one of the values being returned comes from a SQL variable, DBDocumentor will not attempt to determine the valid values, but will list the variable name.

Describe any result sets

If the stored procedure returns data by way of a result set, you describe the intent of the result set using the ##RSD tag, and the data contained in each column using the ##RS tag.

Describe the reason for stored procedure usage

If the stored procedure executes other stored procedures, you can describe why a given stored procedure is used by using the ##EP tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific stored procedure is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the stored procedure and objects referencing it, and between objects used in the procedure. Should you desire to establish a functional relationship (e.g. between a login and logout procedure), you can use the ##SA tag.

Define any usage examples

The ##EX tag allows you to optionally describe how the stored procedure should be used.


How to Document Synonyms

Describing the purpose of an object synonym is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a synonym?

DBDocumentor produced output for synonyms includes:

  • The parent object type
  • A listing of all functions, stored procedures, triggers, ad-hoc queries and data views which reference the synonym, providing the object is included in the project. The description for the referencing objects comes from the source documentation for the referencing object. Hyperlinks are present from the synonym to the referencing objects.

Describe the purpose of the Synonym

To describe the purpose of the synonym, use the ##SYND tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific data type is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the synonym and the objects where the synonym is used. Should you desire to establish a functional relationship, you can use the ##SA tag.

Define any usage examples

The ##EX tag allows you to optionally describe how the synonym should be used.


How to Document System Messages

Describing the purpose of a system message is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

Note: A system message is created in T-SQL using the sp_addmessage system stored procedure.

Note: System messages can not be documented using the SQL Server 2000 extended properties.

What is included in the DBDocumentor output for a system message?

DBDocumentor produced output for system messages includes:

  • The message identifier for the message
  • The message text for the message
  • The severity for the message
  • A listing of all functions, stored procedures, and data views which reference the system message, providing the object is included in the project. The description for the referencing objects comes from the source documentation for the referencing object. Hyperlinks are present from the message to the referencing objects.

Describe the purpose of the system message

To describe the purpose of an system message, use the ##MSGD tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific system message is a member of a given functional area by using the ##AT tag.

© 2005 Pikauba Software. All rights reserved.


How to Document Data Tables

Describing the type of data stored in data tables is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a table?

DBDocumentor produced output for data tables includes:

  • A listing of each column in the table. Included with the column detail is the data type, nullability, default value and any identity information. See below for a method of annotating column information.

Note: Default values for the column are considered constraints and are listed both with the column and in the constraints section.

  • A listing of any constraints on the table. Both named and unnamed constraints are included. If the constraint is a foreign key, and the object being referenced is included in the project, a hyperlink will be present from the constraint to the object. See below for a method of annotating constraints.
  • A listing of any objects included in the project which are accessing the table. The description for the object comes from the source for the object which is accessing the table. Hyperlinks are present from the table to the objects performing the access.
  • A listing of any objects included in the project which are modifying the contents of the table. As with the data source listing, the description for the object comes from the source for the object which is performing the modification. Hyperlinks are present from the table to the objects performing the data modification.
  • A listing of any indices (indexes) included in the project and defined on this table. As with the data source listing, the descriptions used for the indices come from the source index. Hyperlinks are present from the table to the indices.
  • A listing of any triggers included in the project and defined on the table. As with the data source listing, the descriptions used for the triggers come from the source trigger. Hyperlinks are present from the table to the trigger.
  • A listing of the security roles (permissions) defined on the trigger, and contained in the project. As with the data source listing, the descriptions used for the roles come from the source role. Hyperlinks are present from the trigger to the security role.
  • If the table is a temporary table, either as a global temporary object, or connection specific, it will be categorized as such. If the same name is used for multiple temporary tables, the summary listing for the table will be that of the last one encountered.

Describe the purpose of the table

To describe the purpose of a data table, use the ##TBLD tag (or one of the variants). Since SQL Server allows the creation of multiple data tables per SQL batch, the ##TBLD tag requires the name of the table. The table name used must match exactly that used in the create statement, including any object ownership.

Describe the table structure

You describe the type of data stored in each column by using the ##TBLCD tag.

Describe any table constraints

Column constraints are described using the ##TBLCOND tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific data table is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the table and objects referencing it. Should you desire to establish a functional relationship (e.g. between a user table and its associated audit table), you can use the ##SA tag.

Define any usage examples

The ##EX tag allows you to optionally describe how the user defined function should be used.

© 2001-2005 Pikauba Software. All rights reserved.


How to Document Triggers

Describing the functionality of triggers is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

Note: SQL 2000 introduced concepts of triggers on data views, and triggers which would fire if the SQL statement failed. DBDocumentor fully supports these types of triggers.

What is included in the DBDocumentor output for a trigger?

DBDocumentor produced output for triggers includes:

  • A listing of any tables, views and functions queried in the trigger. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the trigger to the source object.
  • A listing of any tables or views whose contents are modified by the trigger. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the trigger to the modified object.

Note: The pseudo tables inserted and deleted are not included in the listing of tables access or modified.

  • A listing of any stored procedures used in the queries in the trigger. See below for the method of annotation for the usage model of executed procedures. If the stored procedure is contained in the project, hyperlinks are present from this trigger to the executed stored procedure.
  • A listing of the security roles (permissions) defined on the trigger, and contained in the project. As with the data source listing, the descriptions used for the roles come from the source role. Hyperlinks are present from the trigger to the security role.
  • A listing of any errors raised from the trigger. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the trigger to the system message.
  • An indication of the what type of data modification the trigger will fire on
  • An indication of when the trigger will fire in relation to the data modification
  • An indication of if the trigger modifies data
  • An indication of if the trigger is transactional, or participates in transactions
  • An indication of if the trigger uses server side cursors
  • An indication of if the trigger executes stored procedures
  • An indication of if the trigger contains dynamic SQL
  • An indication of if the source code is for the trigger is encrypted. If the source code is marked as encrypted, the source code link will not be present, and the output XML will not contain the source code. Source code encryption does not impact the level of detail present in the summary listing.

Describe the trigger

To describe the functionality of the trigger, you use the ##BD tag (or one of its variants). Since trigger creation must be unique to a batch, there is no need to specify the name of the trigger with the ##BD tag.

Describe the reason for stored procedure usage

If the trigger executes other stored procedures, you can describe why a given stored procedure is used by using the ##EP tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific trigger is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the trigger and objects referencing it, and between objects used in the trigger. Should you desire to establish a functional relationship (e.g. between an after trigger and its instead of counterpart), you can use the ##SA tag.

Note: The pseudo-tables inserted and deleted are not included in the documentation.

Define any usage examples

The ##EX tag allows you to optionally describe how the trigger should be used.


How to document user defined data types

Documentation Procedures DBDocumentor™

How to Document User Defined Data Types (UDTs)

Describing the purpose of a user defined data type is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

Note: Throughout this document UDT is used to define those data types which are defined by users in the database. Depending on the SQL dialect in use, an UDT may be created via a system stored procedure or defined as a new TYPE, DOMAIN or DATATYPE.

What is included in the DBDocumentor output for a user defined data type?

DBDocumentor produced output for UDTs includes:

  • The parent data type
  • If the derived data type is NULLable
  • If the derived data type has a specific owner (dialect specific)
  • If the derived date type has a default value (dialect specific)
  • If the derived data type has a check constraint on it (dialect specific)
  • A listing of all functions, stored procedures, tables, and data views which reference the data type, providing the object is included in the project. The description for the referencing objects comes from the source documentation for the referencing object. Hyperlinks are present from the UDT to the referencing objects.

Describe the purpose of the UDT

To describe the type of data encapsulated in the data type, use the ##UDTD tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific data type is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the data type and the objects where the data type is used. Should you desire to establish a functional relationship (e.g. between similar data types), you can use the ##SA tag.

Note: If the data type is used within a stored procedure, or trigger, but is not a parameter to the procedure or trigger, no relationship will be established in the documentation DBDocumentor produces.

Define any usage examples

The ##EX tag allows you to optionally describe how the data type should be used.


How to document user defined functions

Documentation Procedures DBDocumentor™

How to Document User Defined Functions (UDFs)

Describing the functionality and interfaces exposed by user defined functions is one of the primary capabilities of DBDocumentor. This mini-guide describes the tags used for the task. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a user defined function (UDF)?

DBDocumentor produced output for user defined functions includes:

  • The input parameters to the function. Included with the function is its data type and any default value. See below for the method of annotating parameters.
  • The output data type from the function.
  • If the output data type is a table structure, the output will be defined either as a result set (inline table value), or as a table (multi-statement table). See below for the method to annotate table based outputs.
  • A listing of any tables, views and functions queried in the function. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the function to the source object.
  • A listing of any tables or views whose contents are modified by the function. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the function to the modified object.
  • A listing of any stored procedures used in the queries in the function. See below for the method of annotation for the usage model of executed procedures. If the stored procedure is contained in the project, hyperlinks are present from this function to the executed stored procedure.
  • A listing of any stored procedures contained in the project which are calling this function. As with the data source listing, the descriptions used for the calling procedures come from the calling procedure. Hyperlinks are present from this function to the calling procedures.
  • A listing of any triggers contained in the project which are calling this function. As with the data source listing, the descriptions used for the calling triggers come from the calling trigger. Hyperlinks are present from this function to the calling triggers.
  • A listing of any data views contained in the project which are calling this function. As with the data source listing, the descriptions used for the calling views come from the calling view. Hyperlinks are present from this function to the calling data view.
  • A listing of any user defined functions contained in the project which are calling this function. As with the data source listing, the descriptions used for the calling functions come from the calling function. Hyperlinks are present from this function to the calling user defined function.
  • A listing of any generic batches contained in the project which are calling this function. Hyperlinks are present from this function to the summary listing for the generic batch.
  • A listing of the security roles (permissions) defined on the procedure, and contained in the project. As with the data source listing, the descriptions used for the roles come from the source role. Hyperlinks are present from the procedure to the security role.
  • A listing of any errors raised from the function. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the function to the system message.
  • An indication of if the function is transactional, or participates in transactions
  • An indication of if the function uses server side cursors
  • An indication of if the function executes stored procedures
  • An indication of if the function contains dynamic SQL
  • An indication of if the source code is for the function is encrypted. If the source code is marked as encrypted, the source code link will not be present, and the output XML will not contain the source code. Source code encryption does not impact the level of detail present in the summary listing.

Describe the function

To describe the functionality of the user defined function, you use the ##FND tag (or one of its variants). User defined functions come in three varieties; scalar, rowset and table based. No specific documentation options exist for scalar functions, so you are recommended to describe any valid return values are part of the function description.

Note: Since SQL Server 2000 allows the creation of multiple functions per SQL batch, the ##FND tag requires that the name of the function be specified. The name must be identical to that used in the create statement, including any object ownership.

Describe the parameters

To describe any data transferred in a parameter, you use the ##FNPD tag. The names of the function and parameter are required for this tag, but you do not include the @ symbol which precedes the name of the parameter.

Describe any result sets

If the function returns data by way of a result set (described as an inline table valued function in the SQL 2000 books online), you describe the intent of the result set using the ##RSD tag, and the data contained in each column using the ##RS tag.

Describe the table structure

If the function behaves as a table (described as a multi-statement table valued function in the SQL 2000 books online), you describe the table structure using the ##TBLCD tag.

Tip: The ##TBLCD tag is primarily used to describe data tables. Since multi-statement table valued functions exhibit a structure similar to that of a data table, the ##TBLCD tag is used, simply place the name of the function where the tag defines the name of the table.

If the table structure contains any column constraints, the constraints are described using the ##TBLCOND tag.

Tip: The ##TBLCOND tag is primarily used to describe data tables. Since multi-statement table valued functions exhibit a structure similar to that of a data table, the ##TBLCOND tag is used. Simply place the name of the function where the tag defines the name of the table.

Describe the reason for stored procedure usage

If the function executes other stored procedures, you can describe why a given stored procedure is used by using the ##EP tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific user defined function is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the function and objects referencing it, and between objects used in the function. Should you desire to establish a functional relationship (e.g. between a function calculating sales by region and by department), you can use the ##SA tag.

Note: Scalar functions are not cross referenced in this version of DBDocumentor.

Define any usage examples

The ##EX tag allows you to optionally describe how the user defined function should be used.


How to document generic batches

Documentation Procedures DBDocumentor™

How to Document Generic Ad-Hoc Batches

Generic SQL batches are SQL batches which do not contain atomic DDL SQL operations. For example, SQL Server does not allow more than one CREATE PROCEDURE statement per SQL batch, so a SQL batch containing a CREATE PROCEDURE statement is considered atomic and DBDocumentor, once it encounters the CREATE PROCEDURE statement will process the entire batch as belonging to the procedure.

By contrast, many CREATE TABLE statements may be present in a single SQL batch, and in addition to the CREATE table, several operations may manipulate the table. In such a situation DBDocumentor does not consider the batch as being atomic and will process the additional operations as if they were generic operations (i.e. not belonging to a CREATE statement). The same is true for batches containing no CREATE statements at all. By doing so, DBDocumentor can obtain a very good picture of data accesses occurring in the database.

This mini-guide describes the tags used for the task of documenting generic batches. Each of the tags are presented in the order in which they are normally used.

What is included in the DBDocumentor output for a generic batch?

Since generic batches are defined as those which do not contain atomic DDL SQL operations, most users find that documenting them is more difficult than simply working with the DBDocumentor generated output. The following lists those items present in the summary listing for a generic batch.

  • The output "result sets" from queries contained in the batch. In this context, a result set is anything which will return a data set to some client. See below for the procedure for documenting result sets.
  • A listing of any tables, views and functions queried in the batch. The descriptions for these objects come from the source documentation for the individual object. e.g. if the query includes table foo, the description supplied with table foo will be used in the data source listing. If the source object is contained in the project, hyperlinks are present from the batch to the source object.
  • A listing of any tables or views whose contents are modified by the batch. As with the data source listing, the descriptions used for the objects come from the source documentation for the individual object. If the modified object is contained in the project, hyperlinks are present from the batch to the modified object.

Note: DROP operations are not considered content modifications, and will not be listed here.

  • A listing of any stored procedures used in the queries in the batch. See below for the method of annotation for the usage model of executed procedures. If the stored procedure is contained in the project, hyperlinks are present from this batch to the executed stored procedure.
  • A listing of any errors raised from the batch. If the error raised is defined as a system error via sp_addmessage, then a hyperlink will be present from the batch to the system message.
  • An indication of if the batch modifies data
  • An indication of if the batch is transactional, or participates in transactions
  • An indication of if the batch uses server side cursors
  • An indication of if the batch executes stored procedures
  • An indication of if the batch contains dynamic SQL

Describe the intent of the batch

To describe the functionality of the batch, you use the ##BD tag (or one of its variants).

Describe any result sets

If the batch returns data by way of a result set, you describe the intent of the result set using the ##RSD tag, and the data contained in each column using the ##RS tag.

Describe the reason for stored procedure usage

If the batch executes other stored procedures, you can describe why a given stored procedure is used by using the ##EP tag.

Establish table of contents entries

If functional areas have been defined in the table of contents, you can specify that a specific batch is a member of a given functional area by using the ##AT tag.

Establish object relationships

DBDocumentor will establish any SQL relationships between the contents of the batch (i.e. data source usage). Should you desire to establish a functional relationship, you can use the ##SA tag.


Valid HTML for Pikauba Products

Documentation Procedures DBDocumentor™

Valid HTML for Compiled Help

Throughout this manual you will encounter the term "valid HTML". For the purposes of describing your objects, "valid HTML" differs slightly from regular page oriented HTML in a number of ways. For example, "valid HTML" has the following characteristics:

  1. It is an HTML page fragment. That is to say, it can not contain any <HTML> or <BODY> tags.
  2. Descriptions must have valid HTML syntax for inclusion within <P>, <TD> and <BLOCKQUOTE> tags. If this requirement is not met (i.e. the description includes a closing tag, or an object which is not valid for use within these containers), minimally you will have poorly formatted output. Please be aware that very poorly formatted HTML fragments have been known to cause the HTML Help workshop compiler (hhc.exe) to crash.
  3. If you make use of HTML 4.0 or higher tags, please be aware that the HTML Help compiler may not function correctly. The HTML should be HTML 3.2 compliant.
  4. Non-Microsoft Internet Explorer tags may cause problems with the output. Please do remember that the HTMLHelp viewer is using Internet Explorer components and as such may not render tags specific to other browsers.
  5. Only use Microsoft HTML extensions appropriate to the lowest common browser you expect anyone to view your documentation on. For example, if you were to leverage IE 6.0 concepts in you descriptions, those pages may not render correctly when viewed on a base Windows 2000 system using IE 5.0.
  6. If you desire to make use of raw HTML or XML tags in your descriptions, place them within <PRE></PRE> tags. The <PRE> tags will use the system default font, but can be overridden with stylesheets. Alternatively you can place your fixed content within <pikauba> namespace tags to have a fixed font used, but also apply colorization rules to the content.
  7. Each Pikauba Software product comes with a default stylesheet named stylesheet.css. Please feel free to customize this file as your needs warrant, but do bear in mind that if you perform an upgrade of a Pikauba Software product, this file will be overwritten during the upgrade process. In other words, make certain you back this file up before you upgrade.
  8. If you reference a local file in your description and that file is not present when the project compiles, a compilation error may occur in hhc.exe. If you see such an error and have local file references which were not generated by a Pikauba Software product, please contact Pikauba support for assistance in determining a resolution.

Formatting HTML/XML for output

If you are formatting HTML or XML for display to the user (i.e. as part of an example), you must either escape the "<" and ">" characters. Placing the XML/HTML within <PRE> tags without escaping it will not render the "<" and ">" characters. If you are making use of SQL code in a description or example, you can mark this code to be colorized as SQL source by using the <pikauba> namespace.


Enterprise Manager Descriptions

Documentation Procedures DBDocumentor™

Using Enterprise Manager Descriptions

Microsoft SQL Server 2000 introduced a method for providing descriptions for certain objects, or object attributes in the database. These descriptions are stored in the database as extended properties with a property name of MS_Description. Any object or object attribute which has a design time description edit box in SQL Enterprise Manager will have its value stored in the MS_Description extended property.

You can obtain more information on the use of extended properties in general by looking in the SQL Server Books Online (BOL) under the topic "Property Management" and "Using Extended Properties on Database Objects". It is important to note that while the BOL does describe the usage of extended properties, it does not describe the MS_Description property specifically

How DBDocumentor uses the MS_Description Extended Property

If you select the "Use enterprise manager descriptions" SQL option, DBDocumentor will make use of the MS_Description extended property, if it finds one. This can provide for a common location to store your object descriptions, assuming you are using SQL Server 2000. If you are using a combination of both DBDocumentor tags and extended properties, please note that if both are defined for a given object or object attribute, the descriptions from each will be used, with the DBDocumentor tags appearing first.

How to Enter the MS_Description Extended Property Using Enterprise Manager

Using Microsoft SQL Server Enterprise Manager, you can enter extended property descriptions for many of the items in your database. To enter an extended property description, open Enterprise Manager, navigate to the database and object desired and enter the database designer. Any place where you can enter a description for an item will result in the MS_Description property being added. If you then script out the database, with the extended properties, and have DBDocumentor process the script, your database is now fully documented without needing to use the proprietary DBDocumentor syntax for most items.

How to Enter Extended Properties Using Query Analyzer

Using the query analyzer tool for Microsoft SQL Server 2000, you can enter extended property descriptions for most of the items in your database. When entering the extended property, the name of the property must be MS_Description and the value can be what ever you wish to use for the item. As with the Enterprise Manager process above, you will need to script out the database for DBDocumentor to produce the output documentation.

Where Extended Properties Fail

As good as the new extended properties are for documenting SQL elements, they do have some current limitations. For example, there is no mechanism to describe the columns in a result set, nor return values. As such, any complete database documentation solution will need to have a combination of both DBDocumentor tags and the MS_Description extended properties.

Additionally, if you are desiring to compose long descriptions for certain objects (e.g. a complete usage guideline for a critical stored procedure), extended properties may not be appropriate. This stems from the use of the SQL Server 2000 data type of sql_variant which has a maximum length of 8016 bytes (or approximately 4000 UNICODE characters).

Even with these limitations, use of the MS_Description extended property can go a long way towards creating self documented databases.


Pikauba Namespace Tags

Any block comment tag can now contain extended documentation tags following an XML fragment form. The Pikauba namespace allows for the definition of annotation options which are not easily defined in HTML, or which would potentially conflict with SQL statements. As DBDocumentor evolves, additional tags will be defined, but at the moment only the SQL extension is defined. All namespace tags will follow the convention of being XML fragments which must internally be well formed XML. As with all XML tags, the Pikauba namespace is case sensitive.

SQL Extension

The SQL extension is used to indicate to DBDocumentor that the contents of the tag should be treated as SQL source for the purposes of display. This means that any text contained within the SQL extension will be formatted and color coded according to the rules defined for normal source code display, with the exception that the text will always be color coded regardless of the project settings. HTML tags are discouraged from use within the SQL extension, and may cause the output to be rendered incorrectly. Specifically if the SQL extension is included within a <PRE> tag, or a <PRE> tag is included within a SQL extension, the output will not be formatted correctly.

Syntax

<pikauba:SQL>

... SQL text to be syntax highlighted goes here

</pikauba:SQL>

Example

The following text appearing in a block comment tag,

<pikauba:SQL>

    BEGIN TRANSACTION
    EXEC UpdateProcedure
    If @@Error = 0
        COMMIT TRANSACTION
    Else
        ROLLBACK TRANSACTION

</pikauba:SQL>

will be formatted on output as:

BEGIN TRANSACTION
EXEC UpdateProcedure
If @@Error = 0
COMMIT TRANSACTION
Else
ROLLBACK TRANSACTION

XML Extension

The XML extension is used to indicate to DBDocumentor that the contents of the tag should be treated as XML source for the purposes of display. In previous versions of DBDocumentor, if you wanted to include XML information in the output document, you were required to escape the XML tags. If you didn't perform the escape, the output would either not compile due to an exception in hhc.exe, or the XML would not appear in the output. In addition to including the XML, the XML namespace extension also performs source code colorization on the XML.

Syntax

<pikauba:XML>

... XML text to be output goes here

</pikauba:XML>

Example

The following text appearing in a block comment tag:
<pikauba:XML>
<Object>
<Type key="0" value="Unknown" />
<Type key="1" value="Stored Procedure" />
<Type key="2" value="Table" />
<Type key="3" value="Trigger" />
<Type key="4" value="View" />
<Type key="5" value="Index" />
<Type key="6" value="Function" />
<Type key="7" value="User Defined Type"
/>
<Type key="8" value="Fixed Content" />
<Type key="9" value="Role" />
<Type key="10" value="Generic Batch" />
<Type key="11" value="Message" />
<Type key="12" value="Common Table Expression"
/>
</Object>
</pikauba:XML>

will be formatted on output as:

<Object>
<Type key="0" value="Unknown" />
<Type key="1" value="Stored Procedure" />
<Type key="2" value="Table" />
<Type key="3" value="Trigger" />
<Type key="4" value="View" />
<Type key="5" value="Index" />
<Type key="6" value="Function" />
<Type key="7" value="User Defined Type" />
<Type key="8" value="Fixed Content" />
<Type key="9" value="Role" />
<Type key="10" value="Generic Batch" />
<Type key="11" value="Message" />
<Type key="12" value="Common Table Expression" />
</Object>


Stylesheet Elements

Documentation Procedures DBDocumentor™

Custom Stylesheets

Using the XML project file, an alternate stylesheet can be defined for a project. This alternate stylesheet must contain all the elements and classes defined in the standard default stylesheet, or presentation errors will result.

Note: The stylesheet must be located in the same folder as the XML file, or in a sub folder beneath it. If the stylesheet can not be found during output compilation, the default stylesheet will be use.

Note: If you are working with an unregistered version of DBDocumentor, the contents of this element will be ignored.

Tip: When defining a custom stylesheet, copy the default stylesheet from the installation path. Failure to do so will result in your changes being overwritten if you upgrade DBDocumentor.

Classes

This section describes the classes contained in the default stylesheet.

clsSource

clsSource is used whenever SQL source is to be formatted. This means on source code pages, or when ever the pikauba:SQL namespace was used.

clsSectionLink

This class is used for the links on any table of contents summary page.

clsSectionHeader

This class is used for any section headers. A section header is the text used to denote a change in context in a summary page. Examples of section headers include Output Recordset, Parameters, and Constraints.

clsTableHeader

This class is used for the header row of all data tables, and the key column of all attribute tables. Examples of data tables include the parameters of stored procedures and columns of SQL tables. Examples of attribute tables include the properties of a trigger.

clsTableBorderKey

This class is used for for the content key used in a table row. The content key is the unique identifier for the row.

clsTableBorderDataType

This class is used for table content which contains a data type.

clsTableBorder

This class is used for all table content which is not keyed or data type content.

clsSyntax

This class is used to define the formatting of the text describing the syntax of the SQL object. The syntax of the SQL object always starts with the name of the object and ends with any parameters (as appropriate).

clsObjectDescription

This class is used for the description of the SQL object, and for the description of any result sets from the SQL object.

clsLabelHeader

This class is used for the object type and file location headers.

clsLabelDescription

This class is used for the object type and file location values.

clsBase

This class contains the last item on each page. By default this class determines how topics in the CHM are printed, but should you desire suppression of the "compiled by Pikauba Software" link at the base of each page, make this class hidden.

clsDate

This class contains the message "Document compiled on" displayed at the base of each page. If you wish to suppress this default message, you can do so by making this class hidden.


XML Layout

XML Files DBDocumentor™

XML File Layout

DBDocumentor supports the use of XML files for input, as well as optionally outputting an XML document describing the database.

XML Files

Contained in the XML folder off the installation path are two XML files used to produce the CHM and XML outputs.

Standard.xml contains the standard (default) table of contents. Do not modify this file as modification could cause DBDocumentor to fail to operate.

Types.xml contains the list of various data types used by DBDocumentor. Do not modify this file as modification could cause DBDocumentor to fail to operate.

XSL Files

Contained in the XSL folder off the installation path are two XSL files used to produce the CHM and XML outputs.

CustomTOCLoad.xsl is used to convert the grouping options of the XML project file into the chapter representation of the SQLDocumentation schema. Modification of this file could cause all custom table of contents (groupings, or applies to entries) to fail to function.

StandardTOCLoad.xsl is used to convert the standard table of contents into the chapter representation of the SQLDocumentation schema. Modification of this file could cause all table of contents to fail to display.

XSD Files

Contained in the XSD folder off the installation path are two XSD files.

Config.xsd is used to describe and validate the XML project file.

SQLDocumentation.xsd is used to describe and validate the XML output file.


XML Project File

DBDocumentor supports the use of an XML file for programmatic control over the project options used during the project execution. This XML project files does not replace .DBDocumentor file used in previous versions, but rather allows for greater control of the textual elements which can be incorporated in the final output (e.g. project descriptions), while offering greater flexibility for command line documentation builds.

Note: Use of the XML project file allows for considerable control over the operation of DBDocumentor, but does not replace the GUI user interface. Specifically, while you can set overrides for many options present in the GUI, were you to open the GUI you would not see the settings defined by the XML file.

Note: If a data error occurs during the processing of the XML project file, the output may not be as expected. Data errors are defined as errors in the content of an attribute defining an override, but where the XML is well formed.

Note: If you make use of the XML file, none of the settings you may have specified for matching items in the INI file will be used. In other words, what is in the XML file is what will always be used. Care must be exercised in order to not create configurations which are not desired. In other words, the GUI protects against configuration conflicts, the XML file simply sets the configuration values. If you are using the XML file, and experience operational problems, a copy of your XML file will likely be required in order to reproduce the problem.

The XML file is defined in the DBDocumentor.ini file as follows:

##XMLINCLUDE project.xml

where project.xml is any XML file residing in the same folder as DBDocumentor.ini, with a structure as defined here. The groups element list is described on this page.

Note: The rules for well formed documents must be followed for this file. Specifically, all items are case sensitive, if an XML reserved character is required in the description, it must be included in a CDATA section, and attention to the encoding may be required depending on the language of the computer DBDocumentor is running on. If the XML document is not well formed, XML errors will occur and DBDocumentor not run with any of the options defined in the file.

Note: An XML schema is included with the project. It is named config.xsd, and follows the XSD syntax. The file can be found in the XSD folder off the installation path.

Tip: If you are using an XML project file, you do not need to use the ##XMLINCLUDE directive if you name the XML file DBDocumentor.xml. The ##XMLINCLUDE directive is available for users wishing to save multiple XML configurations and select them in the INI file.

Details

The XML project file can contain two document elements. One named groups, containing information about the table of contents and described here. The second named Config and described below.

Config Document Element

The Config document element is used to define any textual elements which were previously defined in the DBDocumentor.ini file, and optionally to define any overrides of the settings stored in the DBDocumentor project file. The Config document element is made up of the optional elements named: Settings, CopyrightInfo, StyleSheetLocation, ProjectDescription, ProjectPageHeader.

Settings Document Element

The Settings document element is used to define the overrides present in the XML project file. An entry is present for each of the available options in the GUI. All entries are optional.

AnyUser Attribute

The AnyUser attribute corresponds to the GUI element controlling whether any user is allowed to access the output. Valid values are yes/true and no/false.

CaseSensitive Attribute

The CaseSensitive attribute corresponds to the GUI element controlling whether the input SQL batches are to be considered case sensitive. Valid values are yes/true and no/false.

Colorize Attribute

The Colorize attribute corresponds to the GUI element controlling whether the output is colorized. Valid values are yes/true and no/false.

Override Attribute

The Override attribute corresponds to the GUI element controlling whether parsing of any objects is to occur. Valid values are yes/true and no/false.

IncludeSource Attribute

The IncludeSource attribute corresponds to the GUI element controlling whether the output will contain the source used to define the SQL object being described. Valid values are yes/true and no/false.

LaunchHelp Attribute

The LaunchHelp attribute corresponds to the GUI element controlling whether the output is launched after compilation. Valid values are yes/true and no/false.

Note: If using the command line DBDocConsole application, the /D parameter always takes precedence over the project settings.

ExtendedProperties Attribute

The ExtendedProperties attribute corresponds to the GUI element controlling whether SQL Server Enterprise Manager extended properties will be considered for the final output. Valid values are yes/true and no/false.

ParseFunctions Attribute

The ParseFunctions attribute corresponds to the GUI element controlling whether functions will be processed. Valid values are yes/true and no/false.

ParseIndices Attribute

The ParseIndices attribute corresponds to the GUI element controlling whether indices will be processed. Valid values are yes/true and no/false.

ParseProcs Attribute

The ParseProcs attribute corresponds to the GUI element controlling whether stored procedures will be processed. Valid values are yes/true and no/false.

ParseRaiseErrors Attribute

The ParseRaiseErrors attribute corresponds to the GUI element controlling whether any errors raised in procedures, triggers or functions will be processed. Valid values are yes/true and no/false.

ParseTables Attribute

The ParseTables attribute corresponds to the GUI element controlling whether tables will be processed. Valid values are yes/true and no/false.

ParseTriggers Attribute

The ParseTriggers attribute corresponds to the GUI element controlling whether triggers will be processed. Valid values are yes/true and no/false.

ParseUDTs Attribute

The ParseUDTs attribute corresponds to the GUI element controlling whether user defined types will be processed. Valid values are yes/true and no/false.

ParseViews Attribute

The ParseViews attribute corresponds to the GUI element controlling whether data views will be processed. Valid values are yes/true and no/false.

ParseRDL Attribute

The ParseRDL attribute corresponds to the GUI element controlling whether Microsoft SQL Server Reporting Services RDL files will be processed. Valid values are yes/true and no/false.

IncludeTemps Attribute

The IncludeTemps attribute corresponds to the GUI element controlling whether temporary objects will be processed. Valid values are yes/true and no/false.

ProjectName Attribute

The ProjectName attribute corresponds to the GUI element defining the name of the project used in the final output.

SpaceCount Attribute

The SpaceCount attribute corresponds to the GUI element controlling how many spaces are used to represent horizontal tabs when outputting the SQL source. The value is an integer.

OutputFileName Attribute

The OutputFileName attribute corresponds to the GUI element defining the name of the output file. This file name must not include any pathing elements as the output path is defined using the relative pathing options contained in the DBDocumentor project.

ParseRoles Attribute

The ParseRoles attribute corresponds to the GUI element controlling whether security roles will be processed. Valid values are yes/true and no/false.

ParseGeneric Attribute

The ParseGeneric attribute corresponds to the GUI element controlling whether ad-hoc or generic SQL batches will be processed. Valid values are yes/true and no/false.

IncludeEMSource Attribute

The IncludeEMSource attribute corresponds to the GUI element controlling whether SQL Server or ASA meta data descriptions are included in the output source. Valid values are yes/true and no/false.

ClassicCHM Attribute

The ClassicCHM attribute corresponds to the GUI element controlling whether the output format will follow the classic MSDN layout. Valid values are yes/true and no/false.

Language Attribute

The Language attribute indicates the location of the alternate language files to use when localizing the output. Valid values are yes/true and no/false.

HTMLOutput Attribute

The HTMLOutput attribute corresponds to the GUI element controlling whether DBDocumentor will output an HTML frameset. Valid values are yes/true and no/false.

CHMOutput Attribute

The CHMOutput attribute corresponds to the GUI element controlling whether DBDocumentor will generate a CHM file. Valid values are yes/true and no/false.

HideEncrypted Attribute

The HideEncrypted attribute corresponds to the GUI element controlling whether the output source code will include SQL Server encrypted procedure source. Valid values are yes/true and no/false.

IgnoreFunctions Attribute

The IgnoreFunctions attribute corresponds to the GUI element controlling whether a dropped function will be included in the output. Valid values are yes/true and no/false.

IgnoreIndices Attribute

The IgnoreIndices attribute corresponds to the GUI element controlling whether a dropped index will be included in the output. Valid values are yes/true and no/false.

IgnoreProcs Attribute

The IgnoreProcs attribute corresponds to the GUI element controlling whether a dropped stored procedure will be included in the output. Valid values are yes/true and no/false.

IgnoreTables Attribute

The IgnoreTables attribute corresponds to the GUI element controlling whether a dropped table will be included in the output. Valid values are yes/true and no/false.

IgnoreTriggers Attribute

The IgnoreTriggers attribute corresponds to the GUI element controlling whether a dropped trigger will be included in the output. Valid values are yes/true and no/false.

IgnoreViews Attribute

The IgnoreViews attribute corresponds to the GUI element controlling whether a dropped data view will be included in the output. Valid values are yes/true and no/false.

CopyrightInfo Element

If you are supplying a copyright notice to be placed at the bottom of each page in the output document, place that notice in the CopyrightInfo element. When using the XML project file, the ##CO tag is inoperative.

Note: If you are working with an unregistered version of DBDocumentor, the contents of this element will be ignored.

StyleSheetLocation Element

If you are wishing to override the default stylesheet supplied with DBDocumentor, please supply the name of that stylesheet in the StyleSheetLocation element. The required contents of a custom stylesheet are described here.

Note: The stylesheet must be located in the same folder as the XML file, or in a sub folder beneath it. If the stylesheet can not be found during output compilation, the default stylesheet will be use.

Note: If you are working with an unregistered version of DBDocumentor, the contents of this element will be ignored.

ProjectDescription Element

If you are wishing to supply text to be displayed on the project summary page of the output document, please supply it using this element. When working with the XML project file, the ##PR tag is inoperative.

ProjectPageHeader Element

If you are wishing to define a header for the entire project following the conventions of ##PPH, please supply it using this element. When working with the XML project file, the ##PPH tag is inoperative.

Note: If you are working with an unregistered version of DBDocumentor, the contents of this element will be ignored.


Grouping XML Description

XML Files DBDocumentor™

XML Table of Contents File Description

If you are making use of the XML project file, you will need to specify your grouping, or table of contents, options in XML as well. In addition to the standard options offered with ##AT and ##ATG, with the XML project file you can specify groupings many levels deep, define fixed content for specific groupings, control which of the standard groupings are present, and associate HTML Help icons with any fixed content defined., The XML format permits the definition of multiple sub-groupings, and gives greater control over the layout of the standard groups.

The XML file is defined in the DBDocumentor.ini file as follows:

##XMLINCLUDE project.xml

where project.xml is any XML file residing in the same folder as DBDocumentor.ini, with a structure as defined here. The groups element list is described on this page.

Note: The rules for well formed documents must be followed for this file. Specifically, all items are case sensitive, if an XML reserved character is required in the description, it must be included in a CDATA section, and attention to the encoding may be required depending on the language of the computer DBDocumentor is running on. If the XML document is not well formed, XML errors will occur and DBDocumentor will revert to displaying a default table of contents.

Note: An XML schema is included with the project. It is named config.xsd, and follows the XSD syntax.

Details

The XML project file contains a document element named groups which is used to define the table of contents hierarchy. The groups element contains two document elements named, custom and standard.

Custom Document Element

The custom document element is used to define any custom table of contents items, and the associated descriptions for them. The layout of the table of contents will follow the layout of the custom document elements' group elements.

The custom document element is made up of many group elements. group elements may be nested within each other allowing for a hierarchy as deep as desired. Each group element must have an associated name attribute. The value of the name attribute is the text to display for the node in the table of contents. Each group element may have a description element. The textual description for the page will come from the description element. Failure to define a description element will result in a blank page being used.

By default, DBDocumentor will include on the description page for all groups a list of hyperlinks to the content contained in the group. This default behavior can be suppressed using the optional ShowLinks attribute of any group document element for which this is the desired result. Valid values for the ShowLinks attribute are: yes and no.

By default, DBDocumentor will sort the pages within each table of contents section. This default behavior can be suppressed using the optional SortGroup attribute of any group document element for which this is the desired result. Valid values are: yes and no.

Fixed External Content

If your project requires pre-defined content to be included in the final output, and in the table of contents, this can be specified within the custom document element under the desired group element. A group is marked as supporting pre-defined content with the optional attribute FixedContent. When FixedContent is set to yes, the group will be processed for fixed (pre-defined) content. Fixed content is defined using the content document element. The content document element encapsulates one or more entry elements. Each entry document element represents a single entry in the table of contents for the section defined by its associated group. Each entry element contains two required attributes, name and file. The name attribute defines the name to be displayed within the table of contents. The file attribute defines the name of the file to be included in the project. entry elements may also have an optional attribute named IconIndex. If present, the IconIndex indicates which of the stock HTML Help viewer's icons will be used when displaying the topic.

Note: The file name specified must exist in the output folder when DBDocumentor is run for a valid output document to be produced. DBDocumentor performs no presence validation on the file. If the file specified can not be found by the HTML Help compiler, compilation problems may result. If the file references other files via hyperlink, they too need to be present in the output folder prior to running DBDocumentor. Hyperlinked files, which are not explicitly included as content, will be included in the output document by the HTML Help compiler, regardless of where the files may exist on disk at the time of compilation.

Fixed Content Example

The following XML fragment illustrates how fixed content entries can be created.

<group name="My custom content" FixedContent="yes">
    <description>Test of fixed content</description>
    <content>
        <entry name="The first page" file="page1.htm" IconIndex="15"/>
        <entry name="The second page" file="page2.htm"/>
        <entry name="The last page" file="page3.htm"/>
    </content>
</group>

Standard Document Element

The standard document element is intended to allow the user to override the default description for specific table of contents entries, to control if default table of contents entries are displayed, and to allow control over where the standard table of contents is located in the final document.

The standard document element has two attributes, order and subordinate. The order attribute controls where in the table of contents the standard table of contents is displayed. The values are lead, follow and subordinate.

The value of lead indicates that the standard table of contents will precede any custom entries, and will be a peer to any custom entries. It is the default value.

A value of follow indicates that the standard table of contents will trail any custom entries, and will be a peer to the custom entries. If there are no custom entries, lead and follow will result in the same table of contents structure.

A value of subordinate indicates that the standard table of contents will be placed immediately below the top level custom group entry identified by the subordinate attribute. If the named top level entry isn't present, the default values will be used. No support is included to place the standard table of contents at any custom level other than the top level.

The standard document element is made up of many group elements. Like the group elements of the custom element, standard group elements require a description element, and name attribute. Unlike the custom element, the name attribute values are predefined, and optional suppress and DisplayText attributes are present. The list of predefined name values can be found here. If the suppress attribute is defined, this indicates that the table of contents associated with the group entry and any of its children will be suppressed when the output is written. The actual SQL objects and their documentation will still be present in the final document, but there will be no entry in the table of contents for the specified entry. If a value is supplied for the DisplayText attribute, the DisplayText will be used in the table of contents rather than the name value.

By default, DBDocumentor will sort the pages within each table of contents section. This default behavior can be suppressed using the optional SortGroup attribute of any group document element for which this is the desired result. Valid values are: yes and no.

Example

This example creates a custom table of contents entry, and names it Object summary. All standard table of contents entries are located under this custom entry. The default text for the Stored procedures default group is overridden, and the default grouping of Transactional and Cursors are suppressed from the table of contents.

<?xml version="1.0" encoding="Windows-1252" ?>
<project generator='DBDocumentor' version='4.1'>
    <groups>
        <custom>
            <group name='Object summary'>
                <description>The objects used in this project are summarized here.</description>
            </group>
        </custom>

        <standard order="subordinate" subordinate='Object summary'>
            <group name="Stored procedures" suppress="no">
                <description>Stored procedures go here</description>
                <group name="Transactional" suppress="yes">
                    <description>These are transactional</description>
                </group>
                <group name="Cursors" suppress="yes">
                    <description>These use cursors</description>
                </group>
            </group>
        </standard>
    </groups>
</project>

This would result in the following table of contents layout.


Tag Reference

DBDocumentor provides a rich set of commands for use in the source SQL to produce formatted, professional compiled help. Each of these tags can appear more than once in a batch, but they must appear within the batch whose object is associated with the comment.

If the identical tag name is encountered, the system will append (concatenate) the value to the previous value. This allows for greater readability of the source file, and ease of documentation.

Tags may make use of any valid HTML syntax to create more detailed help.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix of _BEGIN and _END.

Note: When using the block comments, any leading single quote character (--) used to comment SQL will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

In addition to the following tags, for any tag which has a block comment tag defined, the Pikauba namespace is also valid.

Conventional Tag | Block Comment Tag | Description
##AT | n/a | Provides an "Applies To" description. The "Applies To" section allows the developer the capability to group functional procedures in the final compiled output. Note the default organization of returns data, transactional, updates data, and cursors remains. This tag may appear in the DBDocumentor.ini file or the batch as required.
##BD | ##BD_BEGIN - ##BD_END | Provides a stored procedure, trigger, or data view description.
##CO | ##CO_BEGIN - ##CO_END | Provides a copyright description. May only be used in the DBDocumentor.ini file, or a SQLHelp.ini file from a SQLHelp project.
##CU | n/a | When working in annotation override mode, denotes a procedure which uses cursors.
##EP | n/a | Defines the purpose of a called procedure
##EX | ##EX_BEGIN - ##EX_END | Provides an example description. The example must be a fully self contained example of the intended use of a stored procedure.
##EXCL | n/a | Used to indicate an object which while present in the source SQL, should not be included in the output
##FND | ##FND_BEGIN - ##FND_END | Defines the purpose of a function
##FNPD | ##FNPD_BEGIN - ##FNPD_END | Defines the purpose of a parameter of a function
##II | n/a | Defines an alternate icon for the SQL object. The icon is from the standard HTML Help viewer's icon list.
##IXD | ##IXD_BEGIN - ##IXD_END | Defines the purpose of a table index
##MD | n/a | When working in annotation override mode, denotes a procedure which modifies data.
##MSGD | ##MSGD_BEGIN - ##MSGD_END | Defines the purpose of a given system (global) message added via sp_addmessage.
##NOV | n/a | Reverses any override directive in effect. If no override directive is in effect, the ##NOV tag has no effect.
##OV | n/a | Denotes an overridden object. Overridden objects do not have their attributes parsed. Only the values explicitly named are included in the compiled help.
##PD | ##PD_BEGIN - ##PD_END | Provides a parameter description for a stored procedure.
##PH | ##PH_BEGIN - ##PH_END | Provides a mechanism for supplying a page header for the output documentation
##PR | ##PR_BEGIN - ##PR_END | Provides a project description. All ##PR tags in the project are combined to make the final title page. Note: ##PR tags may only appear in the DBDocumentor.ini file, or a SQLHelp.ini file from a SQLHelp project.
##PPH | ##PPH_BEGIN - ##PPH_END | Provides a mechanism for supplying a project level page header for the output documentation. Project level page headers are used whenever there is no explicit page header for the object, and for all non-object oriented pages.
##RD | ##RD_BEGIN - ##RD_END | Provides a return value description from a stored procedure.
##RLD | ##RLD_BEGIN - ##RLD_END | Provides a description of a user role.
##RS | ##RS_BEGIN - ##RS_END | Provides a result set return column description for data views and stored procedures.
##RSD | ##RSD_BEGIN - ##RSD_END | Provides a result set description for a result set from a stored procedure or data view.
##SA | n/a | Provides a "See Also" link description.
##SYND | ##SYND_BEGIN - ##SYND_END | Defines the purpose of an object synonym.
##TBLCD | ##TBLCD_BEGIN - ##TBLCD_END | Defines the purpose of a column of a table.
##TBLCOND | ##TBLCOND_BEGIN - ##TBLCOND_END | Defines the purpose of a constraint on a table.
##TBLD | ##TBLD_BEGIN - ##TBLD_END | Defines the purpose of a table
##TR | n/a | When working in annotation override mode, denotes a procedure which is transactional.
##UDTD | ##UDTD_BEGIN - ##UDTD_END | Defines the purpose of a user defined type.
##XMLINCLUDE | n/a | Defines the XML project file.


##AT Tag

Provides an "Applies To", or table of contents description. The "Applies To" section allows the developer the capability to group functional procedures in the final compiled output. Default categorizations remain as appropriate to the object being documented, but the ##AT tag only applies to your custom categorizations and allows you to span SQL objects.

If a tag is found at the batch level, it must have been defined at the DBDocumentor.ini level or it will be ignored.

Tip: If you are using SQL Server 2000, you may be interested in the Pikauba_AT extended property for object level categorization.

Syntax

SQL Batch: -- ##AT Section

DBDocumentor.ini: -- ##AT Section ^^ Comment

SQL Server 2000 Extended Property: Pikauba_AT, Value is: Section

Where Section is the name of the applies to section the developer wishes to group objects by,
and Comment is the documentation text to use. When using the SQL Server 2000 Extended property, multiple sections can be specified as a semi-colon separated list.

Note: If you are upgrading from SQLHelp, please note that the ability to override the text of the default categorization (i.e. the descriptive text used on the page for stored procedures returning data), is no longer available using the ##AT. If you are using this capability in your SQLHelp.ini file, please change those lines to ##ATG. The ##AT descriptive ability is now performed on an object level basis and, as with SQLHelp, allows the ability to override the default descriptions. More information can be found here.

Note: If the section name contains a space, then it must be followed by the ^^ separator. Failure to include the ^^ separator will result in a section being defined with its name being the first word of the ##AT command.

Tip: In addition to the method described above, the functionality of ##AT at the DBDocumentor.ini level is present and significantly expanded upon using the ##XMLINCLUDE XML file. If you elect to use the ##XMLINCLUDE method, the batch level usage of ##AT remains unchanged.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##ATG and ##AT tags found in the INI file will be ignored.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##ATG and ##AT tags found in the INI file will be ignored.

Tip: When working with XML table of contents, you can define a table of contents which essentially unlimited in depth. If you do make use of table of contents entries whose depth is greater than 1 level deep, you will need to specify Section with the ^^ symbol separating each level.

Example

Single level

In this example, a root level entry is defined for "Product Catalogue".

--##AT Product Catalogue ^^

--##AT Product Catalogue ^^ These procedures are designed to work with the automated update
--##AT Product Catalogue ^^ process of the product catalogue.

Multiple level

The following example shows a table of contents hierarchy of Products -> Management -> Partners

--##AT Products ^^ Management ^^ Partners ^^ Procedures used when managing the partner product catalogue

Sample Output

The following example shows the sample.chm file provided in the installation package. We have the default groupings of Modifies Data, Returns Data, Transactional, Examples and Executes Procedures along with the user defined grouping of UserProfile. Not shown is the Uncategorized grouping which contains those procedures which are neither transactional, use cursors or modify data.

All procedures that are associated with the grouping, either through the default logic, of expressly included by the AT tag are listed.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions
  • System Messages


##BD Tag

The ##BD tag defines a standalone batch. Standalone batches are SQL command blocks which perform either a CREATE PROCEDURE, CREATE TRIGGER, or CREATE VIEW. The ##BD will not document tables, functions, user defined types or indices as those objects can appear multiple times within a batch.

Since the ##BD is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##BD line is intended to be a multiline comment, a ##BD must appear on the line immediately before the text to form part of the comment. ##BD tags can contain valid HTML to assist in formatting.

The block comment version of this tag is ##BD_BEGIN and ##BD_END. The end tag must be present for the tag to be valid. You may also use SQL 2000 extended properties for this task.

Syntax

Single line: -- ##BD Comment

Block format: ##BD_BEGIN Comment ##BD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where Comment is the description of the individual object

Example

-- ##BD The product update procedure (spUpdateProduct) modifies the product table,
-- ##BD and product availability table with the new details.

Sample Output

Taken from the sample.chm file, this detail shows the fully qualified procedure name, with the batch definition highlighted.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Stored Procedures
  • Triggers


##CO Tag

The ##CO tag denotes a copyright. Copyrights will appear at the bottom of all compiled files. The ##CO may only appear in the DBDocumentor.ini file.

Since the #CO is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##CO line is intended to be a multiline comment, a ##CO must appear on the line immediately before the text to form part of the comment.

Note: When running in shareware (evaluation) mode, DBDocumentor will ignore any ##CO tags present in the project.

The block comment version of this tag is ##CO_BEGIN and ##CO_END. The end tag must be present for the tag to be valid.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##CO/##CO_BEGIN tags found in the INI file will be ignored as the functionality is replaced by the XML file.

Syntax

-- ##CO Copyright .

Or

##CO_BEGIN
Copyright
##CO_END

Where Copyright is the text to use for the copyright notice to be placed at the base of each page.

Example

--##CO ©2001 MyCompany.com. All rights reserved.


##CU Tag

When running in annotation override mode, the ##CU tag defines an object which is intended to use cursors. Normally this tag will only be required if there are no cursor elements present in the batch, or if a misread of the presence of cursors in the batch occurs.

This tag is ignored when not running in annotation override mode.

Syntax

-- ##CU

Tag Applies To

This tag can be used to document the following SQL objects:

  • Data Views
  • Stored Procedures
  • Triggers


##EP Tag

The ##EP is used to define the roll a called procedure plays in a specific object. It allows the user to document the rationale associated with calling a specific procedure.

Syntax

SQL Batch: ##EP ProcedureName ^^ Comment

SQL Server 2000 Extended Property: Pikauba_EP, Value is: ProcedureName ^^ Comment

Where ProcedureName is the name of the procedure as called, including all dotted components,
and Comment is the documentation text to use

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Stored Procedures
  • Triggers
  • User Defined Functions


##EX Tag

The ##EX tag defines an example for use with the given object. The example should be valid HTML as no parsing of the content will occur.

Since the ##EX is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##EX line is intended to be a multiline comment, a ##EX must appear on the line immediately before the text to form part of the comment.

Multiple lines are appended to existing lines, thus all ##EX tags will appear in the order in which they were defined in the batch.

Note: In SQLHelp, you could use the ##EX tag without an object name being specified. This functionality does remain for backwards compatibility, but if you have more than one object per batch, then the only mechanisms available to distinguish between the examples is to either split the items into separate batch scripts, or to use the object name in the example.

The block comment version of this tag is ##EX_BEGIN and ##EX_END. The end tag must be present for the tag to be valid. You are strongly encouraged to use the block comment tagging convention as in addition to being cleaner to read, it also offers the use of the <pikauba> namespace to color code your output.

Note: If you wish to not include your examples in the source for the actual procedure, you may define a SQL batch containing the example code and, providing the object has been processed by DBDocumentor at the time the example is encountered, the example will be included in the project. These special batches are only valid using the ##EX_BEGIN syntax.

Syntax

Single line: -- ##EX ObjectName ^^ ExampleText

Block format: ##EX_BEGIN ObjectName ^^ ExampleText ##EX_END

SQL Server 2000 Extended Property: Pikauba_EX, Value is: ExampleText

Where ExampleText is the text to use for the example,
and ObjectName is the name of the object being documented.

Note: If you are using multiple object ownership of objects, then the object name must use the fully qualified name, unless the object owned by dbo is being referenced.

To reference an example defined in another object, use the following syntax:

SQL Server 2000 Extended Property: Pikauba_EXREF, Value is a semi-colon separated list of objects whose example text should be included with the named object.

Example

/*

##EX_BEGIN spMyProc ^^

<P>To use the update procedure, ensure that transactions are on in the calling routine. The update procedure assumes it is part of a transaction and will not create a new one.</P>
<br>
<P>Thus, </P>
<pikauba:SQL>

BEGIN TRANSACTION
EXEC UpdateProcedure
If @@Error = 0
COMMIT TRANSACTION
Else
ROLLBACK TRANSACTION

</pikauba:SQL>
##EX_END

*/

Tag Applies To

This tag can be used to document the following SQL objects:

  • Data Views
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Functions


##EXCL Tag

The ##EXCL tag indicates to DBDocumentor that the named object defined in the current SQL batch should not be included in any output documentation. This tag is useful for situations where there the input SQL source contains objects which are not part of the public interface you wish to expose. For example, you may be building a database solution which contains internal stored procedures that you wish to remain proprietary, but all stored procedures are defined in a single file. In this example, you could use the ##EXCL tag to exclude those proprietary procedures while still allowing DBDocumentor to document those public interfaces.

Note: The ##EXCL tag must appear in the same SQL batch as the object to be excluded. If an ##EXCL tag is found referencing an object not contained in the batch, the tag will be ignored.

Syntax

Single line: -- ##EXCL ObjectName

SQL Server 2000 Extended Property: Pikauba_EXCL

Tag Applies To

This tag can be used to exclude the following SQL objects:

  • Data Views
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Functions
  • User Defined Types
  • Synonyms


##FND Tag

The ##FND tag is used to document the intent behind a given function. Since multiple CREATE FUNCTION commands can appear within a given batch, the ##FND tag requires the name of the function to be documented. Effectively, the ##FND tag corresponds to the ##BD tag used for data views, stored procedures and triggers.

Parameters to functions are defined using the ##FNPD tag.

SQL Server 2000 support multiple types of functions, and the description of each type varies.

  • If you are working with a scalar function, the only documentation you need provide are the ##FND and ##FNPD tags as appropriate.
  • If you are working with a function which returns a TABLE data type whose columns are not specified in the function declaration (described as an inline table valued function in the SQL Server documentation), then DBDocumentor considers the return type to actually be a result set. Assuming the function is defined in its own batch, you can use the ##RS tag to provide the column documentation.
  • If you are working with a function which returns a TABLE data type and the structure of the table is specified (described as a multi-statement table valued function in the SQL Server documentation), then DBDocumentor considers the return type to be a table. You can use the ##TBLCD and ##TBLCOND tags to provide the documentation.

The block comment version of this tag is ##FND_BEGIN and ##FND_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##FND FunctionName ^^ Comment

Block format: ##FND_BEGIN FunctionName ^^ Comment ##FND_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where FunctionName is the name of the function being documented and,
Comment is the comment associated with the function.

Note: Since SQL Server 2000 allows the creation of multiple functions per SQL batch, the ##FND tag requires that the name of the function be specified. The name must be identical to that used in the create statement, including any object ownership.

Tag Applies To

This tag can be used to document the following SQL objects:

  • User Defined Functions


##FNPD Tag

The ##FNPD tag defines a parameter in a user defined function call. The system will parse all the named parameters from the CREATE FUNCTION definition for inclusion in the compiled help. Type information, input/output status, and default values are extracted. If no ##FNPD tag exists for a given parameter, there will be no description associated with it in the help, but the parameter will be named.

Since the ##FNPD is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##FNPD line is intended to be a multiline comment, a ##PD must appear on the line immediately before the text to form part of the comment.

The block comment version of this tag is ##FNPD_BEGIN and ##FNPD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: ##FNPD FunctionName ^^ Parameter Name ^^ Comment

Block format: ##FNPD_BEGIN FunctionName ^^ Parameter Name ^^ Comment ##FNPD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where FunctionName is the name of the function the parameter belongs to and,
Parameter Name is the name of the parameter passed to the function and,
 Comment is the documentation text to use

Example

-- ##FNPD FN_AdjustForTimeZone ^^ SourceDate ^^ The date we are going to adjust for the specified timezone
-- ##FNPD FN_AdjustForTimeZone ^^ TimeZoneOffset ^^ The offset to apply to the source date

Tag Applies To

This tag can be used to document the following SQL objects:

  • User Defined Functions


##II Tag

Provides an alternate icon for the table of contents. The alternate icon is one of the stock icons from the HTML Help viewer. The alternate icon is specified as a number ranging from 1 to 42.

Tip: If you are using SQL Server 2000/2005, you may be interested in the Pikauba_II extended property for storing the icon index with the objects' meta data.

Note: When using the HTML output, the HTML Help viewer is not used to render the output, so the value specified here will have no effect on the table of contents.

Syntax

SQL Batch: ##II LocalObjectName ^^ IconIndex

SQL Server 2000 Extended Property: Pikauba_II, Value is: IconIndex

Where IconIndex is the index of the alternate icon from the HTML Help viewer,
and LocalObjectName is the name of the object being documented.

Example

-- ##II spUpdateProductCatalogue ^^ 21

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions
  • System Messages
  • Synonym


##IXD Tag

The ##IDX tag is used to document the intent behind index usage. Since CREATE INDEX commands can appear multiple times within a given batch, the ##IXD tag requires the name of the index to be documented. Multiple ##IDX entries for a given named index are allowed in a batch. Effectively, the ##IXD tag corresponds to the ##BD tag used for data views, stored procedures and triggers.

Note: The ##IXD tag must appear in the same batch as the index being documented.

The block comment version of this tag is ##IXD_BEGIN and ##IXD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##IXD IndexName ^^ Comment

Block format: ##IXD_BEGIN IndexName ^^ Comment ##IXD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where IndexName is the name of the index being documented and,
Comment is the comment associated with the index

Note: SQL 2000 introduced the concept of indices on data views.

Note: If you are using the same name for indices on different tables, you must create the duplicate names in separate SQL batches. Failure to do so will result in the same documentation being applied to all indices bearing the same name within the SQL batch.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Indices (Indexes)


##MSGD Tag

The ##MSGD tag is used to document the intent behind a given system message. System message are global messages used with RAISERROR and defined using sp_addmessage. Since sp_addmessage can appear multiple times within a given batch, the ##MSGD tag requires the ID of the message to be documented. Multiple ##MSGD entries for a given message ID are allowed in a batch for more detailed descriptions. Effectively, the ##MSGD tag corresponds to the ##BD tag used for data views, stored procedures and triggers.

Note: The ##MSGD tag must appear in the batch being documented.

The block comment version of this tag is ##MSGD_BEGIN and ##MSGD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##MSGD Message ^^ Comment

Block format: ##MSGD_BEGIN Message ^^ Comment ##MSGD_END

SQL Server 2000 Extended Property: No extended property is available for documenting system messages

Where Message is the name of the system message being documented and,
Comment is the comment associated with the message

Tag Applies To

This tag can be used to document the following SQL object:

  • System Messages

© 2005 Pikauba Software. All rights reserved.


##MD Tag

When running in annotation override mode, the ##MD tag defines an object which is intended to modify data. Normally this tag will only be required if there are no directives present in the batch which modify data, or if a misread of the presence of data modification directives in the batch occurs.

This tag is ignored when not running in annotation override mode.

Syntax

-- ##MD

Tag Applies To

This tag can be used to document the following SQL objects:

  • Data Views
  • Stored Procedures
  • Triggers


##NOV Tag

If you have defined a global override as described under the ##OV tag, you can reverse that tags effect on a batch by batch basis by including the ##NOV tag in the page.

Technically there is no reason to remove any existing ##OV tag, but from a readability perspective removal of the ##OV tag is recommended.

If there is no override directive in effect for a page containing the ##NOV tag, it will have no effect on the output file.

Please note that the ##NOV tag can also reverse overrides defined for a project on a batch by batch basis.

Syntax

'##NOV

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions


##OV Tag

If your procedure contains complex SQL, it may not be parsed correctly. These processing errors can extend from missing parameters on procedures, missing columns on result sets to missing whole result sets, and perhaps internal exceptions.

It is recommended that you first try to parse the SQL using DBDocumentor to see if any issues are present before using the override tag. Version 3.0 of DBDocumentor is able to handle dynamic SQL better than prior versions. It is recommended that you review the dynamic SQL parser rules before concluding that ##OV is required.

Common issues include:

  • Use of dynamic column names. A dynamic column name is one built from the result set. (e.g. SELECT 'string' + table.Name FROM table)
  • Use of multiple paths of execution. If a conditional expression returns a result set, the parser will assume it to be present under all situations. i.e. the parser does not evaluate the potential paths of execution. The net result is the appearance of additional result sets.
  • Selecting values into a return value. The return values parsed from the SQL procedure are static values. The parser makes no attempt to parse dynamic values.
  • Result sets returned as the result of an EXECUTE on additional procedures.

If the ##OV tag is present, neither the return values, nor the result sets will be parsed. If you use the ##OV tag, incorrect results may be obtained unless the ##RD, ##RS, ##MD, ##CU and ##TR tags are kept in sync with changes to the procedures.

You can also set the entire project as being overridden. This eliminates the need to enter ##OV on each batch during design time.

To reverse the effect of the override tag, either remove it from the batch, of use the ##NOV tag.

Syntax

-- ##OV

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions


##PD Tag

The ##PD tag defines a parameter in a stored procedure call. The system will parse all the named parameters from the CREATE PROCEDURE definition for inclusion in the compiled help. Type information, input/output status, and default values are extracted. If no ##PD tag exists for a given parameter, there will be no description associated with it in the help, but the parameter will be named.

Since the ##PD is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##PD line is intended to be a multiline comment, a ##PD must appear on the line immediately before the text to form part of the comment.

The block comment version of this tag is ##PD_BEGIN and ##PD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: ##PD Parameter Name ^^ Comment

Block format: ##PD_BEGIN Parameter Name ^^ Comment ##PD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where Parameter Name is the name of the parameter passed to the procedure,
and Comment is the documentation text to use

Example

-- ##PD Title ^^ The title of the book to be modified.

Sample Output

When DBDocumentor parses the SQL forming the batch, it determines both the data type, and if the parameter is optional. If the parameter is required, this is indicated. If it is optional, the default value is supplied such that the user can know if the default is appropriate.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Stored Procedures


##PH Tag

The ##PH tag provides a mechanism for supplying a page header for the output documentation. Page headers are placed as the first item in the output HTML. A page header directive will apply to all objects contained in the input batch. This is very important for object types which can occur multiple times per batch, such as CREATE TABLE and CREATE INDEX commands. If there is no batch level page header, but a project level page header is defined, the project level page header will be used.

##PH tags can contain any HTML syntax which is valid for use within the BODY tag, and which is fully encapsulated. If the HTML fragment used for a page header is not well formed, the HTML Help compiler may not render the output correctly.

Note: Page headers can only be defined in the registered version of DBDocumentor.

The block comment version of this tag is ##PH_BEGIN and ##PH_END. The end tag must be present for the tag to be valid.

Syntax

-- ##PH PageHeaderHTML

Or

##PH_BEGIN
PageHeaderHTML
##PH_END

Example

/*

##PH_BEGIN

<table cellpadding="0" cellspacing="0" bgcolor="lightblue" width="100%">
<tr>
<td> &nbsp;</td>
</tr>
<tr>
<td><b><i>&nbsp;&nbsp;DBDocumentor stored procedure sample files </i></b></td>
</tr>
<tr>
<td>&nbsp;</td>
</tr>
</table>

##PH_END

*/

DBDocumentor stored procedure sample files

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions
  • System Messages


##PR Tag

The ##PR tag denotes a project definition. The project definition is included in the default page of the compiled help file. ##PR tags may only appear in the DBDocumentor.ini file. Multiple lines are permitted and will be concatenated together to form the full project definition.

Since the ##PR is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##PR line is intended to be a multiline comment, a ##PR must appear on the line immediately before the text to form part of the comment.

The block comment version of this tag is ##PR_BEGIN and ##PR_END. The end tag must be present for the tag to be valid.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##PR/##PR_BEGIN tags found in the INI file will be ignored as the functionality is replaced by the XML file.

Syntax

-- ##PR Comment

Or

##PR_BEGIN
Comment
##PR_END

Where Comment is the description of the database project

Example

/*

##PR_BEGIN

This project forms the database procedures for the transaction processing
system for our new book store. Only those procedures relating to the sale
of merchandise are included. For other items, including web logs and historical
PR analysis, please refer to other projects.

##PR_END

*/


##PPH Tag

The ##PPH tag provides a mechanism for supplying a project level page header for the output documentation. Page headers are placed as the first item in the output HTML. Project level page headers are used for all non-object description pages (i.e. summary pages). Object level page headers can be defined with the ##PH directive.

##PPH tags can contain any HTML syntax which is valid for use within the BODY tag, and which is fully encapsulated. If the HTML fragment used for a page header is not well formed, the HTML Help compiler may not render the output correctly.

Note: Page headers can only be defined in the registered version of DBDocumentor.

The block comment version of this tag is ##PPH_BEGIN and ##PPH_END. The end tag must be present for the tag to be valid.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##PPH/##PPH_BEGIN tags found in the INI file will be ignored as the functionality is replaced by the XML file.

Syntax

-- ##PPH PageHeaderHTML

Or

##PPH_BEGIN
PageHeaderHTML
##PPH_END

Example

/*

##PPH_BEGIN

<table cellpadding="0" cellspacing="0" bgcolor="lightblue" width="100%">
<tr>
<td> &nbsp;</td>
</tr>
<tr>
<td><b><i>&nbsp;&nbsp;DBDocumentor stored procedure sample files </i></b></td>
</tr>
<tr>
<td>&nbsp;</td>
</tr>
</table>

##PPH_END

*/

DBDocumentor sample files


##RLD Tag

The ##RLD tag is used to document the intent behind a given role. Since multiple role creation (sp_addrole) commands can appear within a given batch, the ##RLD tag requires the name of the role to be documented. Effectively, the ##RLD tag corresponds to the ##BD tag used for data views, stored procedures and triggers.

Note: DBDocumentor will automatically pre-create a role if a GRANT, DENY or sp_addrolemember is encountered prior to the sp_addrole procedure being executed. The ##RLD tag is only valid when encountered in the same batch as the sp_addrole corresponding to the role being added.

The block comment version of this tag is ##RLD_BEGIN and ##RLD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##RLD RoleName ^^ Comment

Block format: ##RLD_BEGIN RoleName ^^ Comment ##RLD_END

Where RoleName is the name of the role being documented and,
Comment is the comment associated with the role.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Security roles


##RS Tag

The system is capable of parsing out the result sets associated with stored procedures and data views. The ##RS tag allows the developer the ability to document each of the columns parsed out. The ##RS tag is immediately followed by a number indicating the result set the parameter belongs too.

Since the ##RS is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##RS line is intended to be a multiline comment, a ##RS must appear on the line immediately before the text to form part of the comment.

The values returned from the ##RS tag can be overridden with the ##OV tag.

When defining multiple result sets from a given procedure, use the ##RSD tag to define the intent of each result set.

Note: If a result set does not use named columns, DBDocumentor will assign a name of Unnamed column #nnn, where nnn is the ordinal of the column in the result set.

Note: If a result set has column names which are duplicated, DBDocumentor will assign an ordinal offset to the column name to provide for uniqueness. Thus if a named column of Products were repeated in the same result set, the second time it would appear as Products #nnn, where nnn represents the duplicate columns ordinal in the output result set.

Note: Since a procedure might return more than one result set depending upon the path of execution in the procedure, or could return the same column alias template for multiple paths of execution, it is not uncommon to find the same result set described more than once.

Note: When working with Select * From Table result sets, DBDocumentor will attempt to determine the table associated with the Select * command. If it is able to determine the table name, the column name in the documentation will be pre-pended with the determined table name. Thus in the Select * From Table example, the column would become Table.* in the DBDocumentor produced HTML Help file.

Of further interest; should the table also be contained in the project, DBDocumentor will attempt to hyperlink to the table so that the columns can be determined by users of the documentation.

The block comment version of this tag is ##RS_BEGIN and ##RS_END. The end tag must be present for the tag to be valid.

Syntax

Single line: ##RSNumber Column ^^ Comment

Block format: ##RS_BEGINNumber Column ^^ Comment ##RS_ENDNumber

SQL Server 2000 Extended Property: Pikauba_RS^Number, Value is: Column ^^ Comment

Where Number is the number of the result set as it appears in the batch. For block comments, both the start and the end tags must have Number specified,
and Column is the name of the column,
and Comment is the documentation text to use

Examples

-- ##RS1 ProductName ^^ The product name.

-- ##RS2 SupplierName ^^ The supplier name.

-- ##RS2 Supplier Sku ^^ The SKU Number associated with the product as defined by the supplier.

-- ##RS3 Sales.* ^^ All columns from the sales table

Sample Output

During SQL parsing, DBDocumentor attempts to determine all result sets returned from the procedure. If there is only one result set, the output file will contain a header labeled Output Recordset. If more than one result set was found, each one will be numbered as in this sample. Please note that the values are listed as found. Thus for this result set, the first column is labeled UserType.

Occasionally you might find the a description value that contains the phrase Dynamic Column. This normally will occur if the procedure returns different column aliases for the same absolute column position, or contains a column alias that is built from the concatenation of one or more strings. While perfectly legitimate, this SQL could pose difficulties for procedure consumers (via ADO or other access means) who expect specific column names to be present in the result set.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Stored Procedures
  • User Defined Functions


##RSD Tag

The ##RSD tag allows the developer the ability to document each of the result sets associated with a data view or stored procedures independently. The ##RSD tag is immediately followed by a number indicating the result set the comment pertains too. ##RSD tags are associated with the corresponding result set defined by the ##RS tag.

Since the ##RSD is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##RSD line is intended to be a multiline comment, a ##RSD must appear on the line immediately before the text to form part of the comment.

When defining multiple result sets from a given procedure, use the ##RSD tag to define the intent of each result set.

Note: Since a procedure might return more than one result set depending upon the path of execution in the procedure, or could return the same column alias template for multiple paths of execution, it is not uncommon to find the same result set described more than once.

The block comment version of this tag is ##RSD_BEGIN and ##RSD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: ##RSDNumber Comment

Block format: ##RSD_BEGINNumber Comment ##RSD_ENDNumber

SQL Server 2000 Extended Property: Pikauba_RSD^Number, Value is: Comment

Where Number s the number of the result set as it appears in the batch. For block comments, both the start and the end tags must have Number specified,
and Comment is the documentation text to use

Examples

-- ##RSD1 The product details result set.

-- ##RSD2 The stock status for each supplier.

Sample Output

During SQL parsing, DBDocumentor attempts to determine all result sets returned from the procedure. If there is only one result set, the output file will contain a header labeled Output Recordset. If more than one result set was found, each one will be numbered as in this sample. ##RSD will work equally well for each situation. In the case of a single result set, ##RSD1 is the key. In the case of multiple result sets, the developer should be aware that conditional execution could lead to differences in the expected number of result sets returned (e.g. if a SELECT is executed as part of each branch in an IF block).

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Stored Procedures
  • User Defined Functions


##RD Tag

The ##RD tag is used to define return values from a stored procedure. Return values are generally numeric in nature, but when dynamic values are defined (either as a result of @@IDENTITY or similar, or column data), the parameter name will be displayed.

Since the ##RD is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##RD line is intended to be a multiline comment, a ##RD must appear on the line immediately before the text to form part of the comment.

The values returned from the ##RD tag can be overridden with the ##OV tag.

If a non-numerical value is found, the parser will attempt to determine its meaning. Thus you can define help for return values of @@IDENTITY.

The block comment version of this tag is ##RD_BEGIN and ##RD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##RD Value ^^ Comment

Block format: ##RD_BEGIN Value ^^ Comment ##RD_END

SQL Server 2000 Extended Property: Pikauba_RD, Value is: Value ^^ Comment

Where Value is the value returned from the procedure,
and Comment is the documentation text to use

Note: The only values you can describe are those explicitly returned by the procedure. For example, if you are returning a value from a variable, DBDocumentor will list the variables' name. DBDocumentor won't attempt to determine the valid return values for the variable. To describe the valid values, use the comment field.

Note: Variable names require the leading @ symbol.

Example

-- ##RD 0 ^^ Procedure executed with no errors
-- ##RD -1 ^^ Procedure was not able to update the sales table.
-- ##RD

Sample Output

This sample illustrates a procedure with three numeric return values. With the documentation provided, the consumer of the procedure can develop their application accordingly.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Stored Procedures


##SA Tag

Provides a "See Also" link description. A "See Also" link is a link name describing an object that is part of the project. If the object name does not match an object in the project (either due to typographical errors or absence of the file), then clicking on the "See Also" link in the compiled help will generate an error.

Note: In SQLHelp, you could use the ##SA tag without a local object name being specified. This functionality does remain for backwards compatibility, but if you have more than one object per batch, then the only mechanisms available to distinguish between the examples is to either split the items into separate batch scripts, or to use the object name in the example.

Tip: If you are using SQL Server 2000, you may be interested in the Pikauba_SA extended property for "See Also" functionality.

Syntax

SQL batch: ##SA LocalObjectName ^^ LinkedObjectName

SQL Server 2000 Extended Property: Pikauba_SA, Value is: LinkedObjectName

Where LinkedObjectName is the name of the object to link to,
and LocalObjectName is the name of the object being documented. For the SQL Server 2000 extended property format, multiple linked objects can be defined by making LinkedObjectName a semi-colon separated list of objects.

Note: If you are using multiple object ownership of objects, then the names of both the local and linked objects must use the fully qualified name, unless the object owned by dbo is being referenced.

Example

-- ##SA spUpdateProductCatalogue ^^ tblProductCatalog

Tag Applies To

This tag can be used to document the following SQL objects:

  • Ad-Hoc Generic Batches
  • Data Views
  • Indices (Indexes)
  • Security Roles
  • Stored Procedures
  • Tables
  • Triggers
  • User Defined Data Types
  • User Defined Functions


##BD Tag

Documentation Tags DBDocumentor™

##SYND Tag

The ##SYND tag describes a SQL Server 2005 Synonym.

Since the ##SYND is not legal SQL syntax, it must appear between comment tags. The tag may be between multiline comment tags (/* ... */), but only the first line will be read. If the ##SYND line is intended to be a multiline comment, a ##SYND must appear on the line immediately before the text to form part of the comment. ##SYND tags can contain valid HTML to assist in formatting.

The block comment version of this tag is ##SYND _BEGIN and ##SYND _END. The end tag must be present for the tag to be valid. You may also use SQL 2005 extended properties for this task.

Syntax

Single line: -- ##BD Comment

Block format: ##BD_BEGIN Comment ##BD_END

SQL Server 2005 Extended Property: MS_Description, Value is: Comment

Where Comment is the description of the individual object

Example

-- ##SYND tblProducts ^^ This is a synonym for the base product legacy table

Tag Applies To

This tag can be used to document the following SQL objects:

  • Synonyms


##TBLCD Tag

The ##TBLCD tag is used to document the intent behind a given column of a table. Since CREATE TABLE commands can appear multiple times within a given batch, the ##TBLCD tag requires the name of the table to be documented. Multiple ##TBLCD entries for a given named table are allowed in a batch for more detailed descriptions.

Note: The ##TBLCD tag must appear in the same batch as the table being documented.

Note: Table documentation is performed using the ##TBLD tag, and column constraint documentation is performed using the ##TBLCOND tag.

Note: If the column being documented is a computed column, the data type will be the equation forming the computed column. e.g. if column 'c' is formed by adding columns 'a' and 'b', then the data type for column 'c' will be a + b.

The block comment version of this tag is ##TBLCD_BEGIN and ##TBLCD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##TBLCD TableName ^^ ColumnName ^^ Comment

Block format: ##TBLCD_BEGIN TableName ^^ ColumnName ^^ Comment ##TBLCD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where TableName is the name of the table being documented and,
ColumnName is the name of the column being documented in the table and,
Comment is the comment associated with the column

Tip: The ##TBLCD tag is also used when documenting certain table valued user defined functions in SQL 2000. In such a situation, replace the table name with the name of the function.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Tables
  • User Defined Functions

© 2001-2005 Pikauba Software. All rights reserved.


##TBLCOND Tag

The ##TBLCOND tag is used to document the intent behind a given constraint of a table. Since CREATE TABLE commands can appear multiple times within a given batch, the ##TBLCOND tag requires the name of the table to be documented. Multiple ##TBLCOND entries for a given named table are allowed in a batch for more detailed descriptions.

Note: The ##TBLCOND tag must appear in the same batch as the table being documented.

The block comment version of this tag is ##TBLCOND_BEGIN and ##TBLCOND_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##TBLCOND TableName ^^ ConstraintName ^^ Comment

Block format: ##TBLCOND_BEGIN TableName ^^ ConstraintName ^^ Comment ##TBLCOND_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where TableName is the name of the table being documented and,
ConstraintName is the name of the constraint being documented in the table and,
Comment is the comment associated with the constraint

Tip: The ##TBLCOND tag is also used when documenting certain table valued user defined functions in SQL 2000. In such a situation, replace the table name with the name of the function.

Tag Applies To

This tag can be used to document the following SQL objects:

  • Tables
  • User Defined Functions


##TBLD Tag

The ##TBLD tag is used to document the intent behind a given table. Since CREATE TABLE commands can appear multiple times within a given batch, the ##TBLD tag requires the name of the table to be documented. Multiple ##TBLD entries for a given named table are allowed in a batch for more detailed descriptions. Effectively, the ##TBLD tag corresponds to the ##BD tag used for data views, stored procedures and triggers.

Note: The ##TBLD tag must appear in the same batch as the table being documented.

Note: Columns on tables can be documented with the ##TBLCD tag.

The block comment version of this tag is ##TBLD_BEGIN and ##TBLD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##TBLD TableName ^^ Comment

Block format: ##TBLD_BEGIN TableName ^^ Comment ##TBLD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where TableName is the name of the table being documented and,
Comment is the comment associated with the table

Tag Applies To

This tag can be used to document the following SQL objects:

  • Tables
  • User Defined Functions

© 2001 - 2006 Pikauba Software. All rights reserved.


##TR Tag

When running in annotation override mode, the ##TR tag defines an object which is intended to be transactional. Normally this tag will only be required if there are no transactional elements present in the batch, or if a misread of the transactional nature of the batch occurs.

This tag is ignored when not running in annotation override mode.

Syntax

-- ##TR

Tag Applies To

This tag can be used to document the following SQL objects:

  • Data Views
  • Stored Procedures
  • Triggers


##UDTD Tag

The ##UDTD tag is used to document the intent behind of a user defined type. Since you can execute multiple sp_addtype commands per batch script, the ##UDTD tag requires the name of the type being documented to be specified. Effectively, the ##UDTD tag corresponds to the ##BD tag.

Note: The ##UDTD tag must appear in the same batch as the type being documented.

The block comment version of this tag is ##UDTD_BEGIN and ##UDTD_END. The end tag must be present for the tag to be valid.

Syntax

Single line: -- ##UDTD UserDefinedTypeName ^^ Comment

Block format: ##UDTD_BEGIN UserDefinedTypeName ^^ Comment ##UDTD_END

SQL Server 2000 Extended Property: MS_Description, Value is: Comment

Where UserDefinedTypeName is the name of the user defined type being documented and,
Comment is the comment associated with the user defined type.

Tag Applies To

This tag can be used to document the following SQL objects:

  • User Defined Data Types

© 2001-2005 Pikauba Software. All rights reserved.


DBDocumentor - User Interface

User Interface DBDocumentor™

User Interface

The DBDocumentor user interface uses a simple wizard philosophy for its user interface. Depending upon the project options the number of steps in the wizard range from one to four.

The wizard pages are:

  • Licensing Like all software products, DBDocumentor has a licensing agreement that grants you, the user, the ability to use the product, as long as you play nice.
  • Registration Since DBDocumentor is distributed via the shareware and trialware channels, the version you have now probably has 90% of the feature set working. Registration gives you that lacking 10%, and is well worth the price. You can purchase a license for DBDocumentor by going to Pikauba.com
  • Step 1 is the first step a registered user sees when running the program. Here you can select to start a new project or load an existing one.
  • Step 2 prompts you to select the directory where the source files, and destination files should be located. You are also able to set various project level options that will govern this project.
  • Step 3 prompts you to select the files to form part of the project.
  • Step 4 displays the progress as the project runs.
  • Step 5 is displayed when processing has completed and offers the option of exiting DBDocumentor or continuing with the same or different projects.

Additional user interface pages are:

  • Testing of components DBDocumentor has the ability to test your system to verify that all the components it requires to function are installed and accessible.

© 2001- 2006 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


DBDocumentor - Test installed components

User Interface DBDocumentor™

Test installed components

When DBDocumentor starts up it will test your computer system to ensure that the components it needs to function are installed and present. Should a component be found to be missing, a window will appear with information regarding the component. If this window is displayed, and you elect to continue without installing a missing component, operational errors may result ranging from a lack of relevant output to program crash.

Tip: If no components are missing, this window will not appear.

Windows NT and Higher Notes

When running on Windows NT and higher (that is Windows NT/2000/XP/2003), the installation of software can only be performed by local machine administrators (members of the Administrators local security group). If you are missing one or more components on your system, these components may only be installed by a local machine administrator.

Microsoft Windows Server 2003 Notes

When running on Windows Server 2003 with the Internet Explorer Enhanced Security Settings in place, you may experience difficulties locating some of the missing components. Specifically:

  • If you are missing the Common Controls, you will need to add *.pikauba.com to your trusted sites list otherwise you will not be able to download the installation package.
  • If you are missing any other component, you will be redirected to a web page within the microsoft.com domain structure. If you have not added *.microsoft.com as a trusted site, you will receive many warnings of unsafe content and will not be able to download the missing components.

After the installation of DBDocumentor is complete, you can safely remove both *.pikauba.com and *.microsoft.com from your trusted sites list if you so desire.

Why Each Component is Required

If you do not install compatible versions of each component, DBDocumentor will not function as designed. Each component has a specific role in DBDocumentor and certain machine administrators may wish to know the version of the component, and why it is required.

Common Controls

The common controls component contains all the user interface ActiveX controls required by DBDocumentor. Normally if either of Office 97 or higher, or Visual Studio 6 have been installed, these components will be present. While more than one control is required, the Common Controls installer will only install newer versions of the controls following Microsoft best practices.

Internet Explorer

Internet Explorer version 4.0 and higher is required as a sub-system for the HTML Help system. In addition to this, DBDocumentor will script Internet Explorer to provide certain web based functionality such as the Locate button on this page. If a compatible version of Internet Explorer is not found (generally all supported operating systems will have a compatible version), you will need to manually obtain a version from Microsoft.

HTML Help Workshop

Most Windows 2000 and higher based systems will have the HTML Help compiler installed, but will not have the HTML Workshop. Without the HTML Help Workshop, no HTML Help (CHM) output can be generated. When installing the HTML Workshop on these systems, a warning about a newer compiler may be generated. This warning is safe to ignore.

Data Access Components (MDAC)

The Data Access components, commonly referred to as MDAC, are used both in sorting operations and in working with the table of contents. Without at least MDAC version 2.5, no output can be generated and internal errors will occur.

Note: If you believe that you have a correct version of MDAC installed, but the DBDocumentor test shows an error, this generally means that your system has a corrupted MDAC stack. During the MDAC test, DBDocumentor will attempt to work with MDAC directly. Any errors during the test will cause DBDocumentor to prompt for an MDAC installation. Correcting a corrupted MDAC can be a difficult process, but if you install the latest version of MDAC, this generally corrects the problem.

Scripting Components

The scripting components are used for a variety of operations ranging from file access to parsing. The scripting library must be at version 5.5 or higher or no output will be generated.

MSXML3

Unlike version 2.x of DBDocumentor, version 3 is XML dependent. No table of contents can be generated, nor will any XML operations work without at least MSXML3 service pack 3 installed. If you have MSXML4 installed, it too will function properly with DBDocumentor.

  • Locate For each missing component a locate button may be present. Press the locate button to be taken a web page on pikauba.com containing information on how to obtain the missing component.
  • Refresh If you have installed a missing component while DBDocumentor was running, press Refresh to determine if there are additional requirements. If all the components are present, you'll be taken to Step 1.
  • Continue You always have the option of attempting to use DBDocumentor to process your SQL files without the required component. Depending upon the missing piece, DBDocumentor may still function in a limited fashion, or may not function at all
  • Cancel Press cancel to exit DBDocumentor


DBDocumentor - Licensing

User Interface DBDocumentor™

Licensing

When you first run DBDocumentor, and each day that you run the shareware version, you will be presented with the Licensing Agreement.

Written mostly in legalese, it simply states that you will use the shareware version of DBDocumentor for evaluation only. If it meets your needs, great, purchase a license for it. If it fails to meet your needs (and we hope you'll let us know if this is the case), fine, delete it.

The shareware version of DBDocumentor will only run for 30 days from the date of installation without beginning to present other varied licensing screens.

Basically, we all will be pressing I Agree and going to the next screen, but it is important to read what's in there.

© 2001-2005 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.


DBDocumentor - Registration

User Interface DBDocumentor™

Registration

After pressing "I Agree" on the licensing page, you'll be taken to the registration page. On this page you have the option of registering DBDocumentor, or trying it out. If you do elect to try it out, you'll be taken through this process daily until you either determine the program is worth it's registration fee, or decide to delete it. Unlike some shareware programs, this period is not fixed in time or duration, thus the DBDocumentor shareware version will not expire. It is important to note though that while DBDocumentor will not expire, it will begin to alert you to its shareware status periodically after 20 days of usage. After 30 days of usage you will be able to continue to use the unregistered shareware version, but you will be prompted once per use that you have exhausted the evaluation limits.

Microsoft Windows Server 2003 Server Notes

If you are using Windows Server 2003 with Enhanced Internet Security and wish to purchase DBDocumentor, you should add both *.pikauba.com and *.regsoft.net to your trusted sites list. If you decide not to add these sites to your trusted sites list, during the purchasing process you may receive one or more warning messages from Internet Explorer Enhanced Security indicating that content has been blocked. These warnings are due to the client side script used to validate form input.

User Interface

If you are looking to purchase DBDocumentor, please click here.

The registration key and code will be sent to you via email after your payment has been verified. Normally the time between order placement and email generation is several minutes. If after 12 hours you have not received your email, please send an email to support@pikauba.com with your name, email address (as used during purchase), and payment method and we will look into the reason for the delay.

Note: DBDocumentor 4.00 and higher uses a basic product activation strategy. Product activation will occur when you press the "Unlock" button, and will open a new Internet Explorer window. The only information sent during product activation is the key being activated, the machine the key will be associated with, and the version of DBDocumentor being activated.

Privacy note: Once activated, DBDocumentor will not contact Pikauba Software for any updates, to download any additional components, or to update the license key usage information. The information collected during activation is governed by our privacy policy.

Users upgrading from a previous version of DBDocumentor, or from any version of SQLHelp may be eligible for a preferential rate on their upgrade. If you are presented with an "Upgrade" button, when you press the button, DBDocumentor will open an Internet Explorer window which will take you to pikauba.com and show you the upgrade options available to you.

Press Register to go to the registration page on the Pikauba Software site. Current pricing will be listed. Unlocking DBDocumentor will eliminate the licensing and registration prompts, remove the file count lockout, and enable your copyright notice to be placed on the output.

Press Try Me! to enter shareware mode and go to step 1.

© 2001-2005 Pikauba Software. All rights reserved.


DBDocumentor - Step 1 - Welcome

User Interface DBDocumentor™

Define or Select a Project

This wizard page is the entry point for the registered version of DBDocumentor.

DBDocumentor stores the settings you chose in project files. These project files all have the file extension of .DBDocumentor and are not user editable (if you do so they probably won't work). There is an option in DBDocumentor to specify project settings in an XML file. Full details on the XML project file can be found here.

The first page of the DBDocumentor wizard is where you will either define a new project file, or select an existing one. Once a new project has been defined, it will automatically appear on the recent projects list.

Note: If you are a SQLHelp user, SQLHelp project files may also be loaded for use with DBDocumentor. DBDocumentor is intended as an upgrade to SQLHelp, and when a SQLHelp project is loaded that project file will be converted to a DBDocumentor file documenting only stored procedures for the Microsoft SQL Server dialect.

If you upgrade a SQLHelp project file and wish to document more than stored procedures with DBDocumentor, simply select an existing SQLHelp project file, load it and add the desired SQL objects. Please note that beginning with version 4.00 of DBDocumentor, the user interface has changed from that of the SQLHelp template.

Define a new project

To define a new project, start by entering the name for the project. Press Create project to create the new project.

Select an existing project

The recent project list will contain the ten most recently used projects, sorted alphabetically. By default the last project file is selected. If you wish to load this project, press the Load project button to continue. If a project file is listed which you no longer use, you can press the Delete project button to remove it from the list. If a project you wish to work with isn't listed in the recent projects list, you can browse for it by pressing the Browse for an existing project button.

Note: If you load a project file from either a previous version of DBDocumentor, or from SQLHelp, the project file will be upgraded. When the project file is closed you will be prompted to save the changes. Previous versions of DBDocumentor only supported the Microsoft SQL Server 2000 and below dialect, so an upgraded project will default to using SQL Server 2000 and below. If you are using Microsoft SQL Server 2005, the new functionality of SQL Server 2005 will not be processed until the dialect is changed to SQL Server 2005.

Unlocking the shareware version

If you are running in shareware mode, an Unlock button will be displayed. Pressing Unlock will take you to the registration page. This button will only be displayed if DBDocumentor is not currently registered.

Pressing "?" will display this page.


DBDocumentor - Step 6 - Select Files

User Interface DBDocumentor™

Select the files to include in the project

The user interface for this step is common between the basic and advanced modes, and is only displayed if you selected to specify the files in the project (installation default).

Note: If you are working with an unregistered version of DBDocumentor, the number of files you can select is limited. To bypass this limitation will require registration of the software. For more information on registration options, click here.

In addition to the limitation on the number of files that can be processed, the unregistered version of DBDocumentor also places a limitation on the number of script batches that can be processed in a given run. This limitation is the same as the number of files, the value of which is currently set to 10.

  1. Select the files you wish to be included in the output document. The tree will be anchored at the folder specified as the source folder for the project.

    Tip: Checking a folder will select all the files below it. Clearing a folder will remove all files listed below it from the project.

    Note: If there are no matching files in the source folder, or below, a note to that effect will be displayed next to the source folder's name.
  2. Once at least one file is selected, the Finish button will become enabled.
  • Press Back to return to the source options page.
  • Pressing "?" will display this page.


DBDocumentor - Step 7 - Final

User Interface DBDocumentor™

Processing files ...

While the project is being processed, DBDocumentor will display both an overall progress bar, and a progress bar associated with the current file. The upper progress bar represents the overall progress of the project, while the lower progress bar is associated with the current file.

Above the overall progress bar you will find the source file being processed, and an estimated time of completion for the project. This estimated time of completion is based on the current elapsed time and the files yet to be processed. This estimate is just that, an estimate, and it will be affected by such things as DBDocumentor encountering a large file as the final file in the file list.

Note: Large files, and files with a large number of SQL batches will cause DBDocumentor to spend significant resources loading the file and determining the batch structure. If possible, files should be kept below approximately 1 to 2 Megabytes in size, and contain less than 1000 separate batches. There are no limitations on the number of files DBDocumentor can process (beyond limitations imposed by the trail version, and available system memory), and these sizing guidelines are intended to offer the best overall performance.

Above the file progress bar is displayed the object most recently encountered. Generally this will be the object currently being processed.

During the processing of SQL scripts, DBDocumentor will enable the cancel button. Once output compilation begins, it is not possible to abort processing so the cancel button will be disabled. Pressing the cancel button will cause DBDocumentor to prompt to continue. If you elect to abort processing, the abort will be effective at the end of the current file operation and no project settings will be saved.

Once the project has been processed, the objects encountered will be compiled into the output document. Once that compilation process has completed, you will be presented with the option to exit or continue working.

Pressing "?" will display this page.


DBDocumentor - Processing completed

User Interface DBDocumentor™

Processing has Completed

When processing of the project has completed, your document will be ready for viewing, and assuming the installation defaults are currently in force, will have opened.

  • Exit DBDocumentor If selected, when you press the close button DBDocumentor will exit.
  • Select a different project or define a new project If selected, when you press continue, DBDocumentor will go to Step 1 where you can select a different project, or define a new project.
  • Reload the current project and change project options If selected, when you press continue, DBDocumentor will go to Step 2 from which you can change the current projects options.
  • Rerun the current project with all current processing options If selected, when you press continue, will reprocess the current project. If the output document is open, and locked on disk, a warning will be issued requesting that the document be closed.

Pressing "?" will display this page.


DBDocumentor - Step 2 - Select the SQL options

User Interface DBDocumentor™

Select the SQL options

If you have loaded a project file, and that project file has files listed to process, the Finish button will be active and pressing it will begin processing of the project.

  • Project title: This is the title DBDocumentor will use when describing this project. It will appear in the recent projects list, and will be the title given to the output documentation. In versions prior to 2.42, this option was not available and the title defaulted to the output file name.

    Note: You are required to enter a title for your project.
  • SQL Dialect: The SQL dialect DBDocumentor will use to parse your source files. Because each SQL dialect uses slightly different syntax, if you choose a dialect which doesn't match the dialect used in your SQL source files, DBDocumentor may not be able to process your source SQL, or might process it incorrectly.

The following dialects are supported:

  1. SQL Server 2000 and below. This is considered a compatibility mode for DBDocumentor as previous versions of DBDocumentor, and all versions of SQLHelp are only able to reliably process TSQL batches from SQL Server 2000 and below
  2. Firebird 1.5. Firebird is an open source database derived from InterBase. While it is possible that DBDocumentor can process some InterBase files, DBDocumentor specifically only supports Dialect 3, or Firebird 1.5. Within Firebird 1.5, ESQL is not supported, while DSQL and PSQL are supported along with all DDL commands.
  3. Sybase ASA 9 and below. Sybase ASA can operate in both a TSQL mode and in Watcom SQL mode. DBDocumentor supports both sub dialects interchangeably. Please note that while ASA uses stored procedures and user defined functions interchangeably, DBDocumentor will list an object based on how it was created, not how it is used.
  4. SQL Server 2005. You can use the SQL Server 2005 or the SQL Server 2000 dialect when documenting SQL Server 2000 databases, but if you do choose to use the SQL Server 2005 dialect for pure SQL Server 2000 database script, DBDocumentor performance will be reduced due to the additional language checks.
  • Case sensitive database: When working with case sensitive databases, or databases that have collation settings that are sensitive to case, accents, or have a character set that is UNICODE, selecting this option instructs DBDocumentor to treat all procedural elements as UNICODE data.

Note: It is very important to note that when running case sensitive mode, all of the annotation tags present for a given procedure must also be case sensitive. Additionally, if the See Also syntax is being used, it must be case sensitive.

Caution: While DBDocumentor is able to process all UNICODE source files, the HTML Workshop and compiler are not UNICODE aware applications. If your SQL application, or the descriptions used to describe the objects, do not use the ANSI character set (which is independent of whether the source file is in UNICODE), you may experience compiler errors ranging from missing objects to actual compiler (hhc.exe) crashes. If you experience problems of this nature, please contact support@pikauba.com describing your environment and Pikauba Software Support will attempt to determine a solution for your situation.

  • SQL objects to include: In this section you specify which SQL objects to include in the output documentation. Your choices are data views, user defined functions, indices (indexes), stored procedures, tables, triggers, user defined data types (domains), security roles, generic batches (adhoc queries) and Reporting Services RDL.

Note: Selecting Tables will automatically process any constraints and will allow for various object hyperlinks to table schema to be generated.

Note: Any object alterations (e.g. ALTER TABLE) will only be valid if the corresponding object is selected for inclusion (e.g. Tables), and the object has already been processed. Thus, if in the sequence of files an ALTER TABLE were to be encountered prior to the CREATE TABLE, then the ALTER will be ignored. A method to avoid this problem is to use an external file list in which the files to be processed are ordered correctly.

Note: SQLHelp projects will default to selecting only the stored procedures option.

Tip: If you have temporary objects (e.g. stored procedures) which are used and then dropped, you may want to ignore drops on those objects.

  • Ignore DROP for these objects: Under normal operations, it is advisable to have DBDocumentor respect all drop operations. Doing so generally results in an accurate representation of the database structure if DBDocumentor is instructed to process SQL source which performs version upgrades to a database. Occasionally this default is not appropriate, and here you can ignore drop instructions for those objects which the default is not appropriate. An example of a situation where the default behavior of DBDocumentor might not be appropriate is for temporary stored procedures create for data maintenance operations and dropped once those operations are completed. By ignoring DROPs of stored procedures, DBDocumentor can cross reference those procedures to the objects they interact with.

  • Press Next to set the parser options.
  • Press Back to return to the welcome screen.
  • Pressing "?" will display this page.


DBDocumentor - Step 3 - Set parser options

User Interface DBDocumentor™

Set parser options

The parser options page lets you set the various options that control how the SQL parser operates.

  • If RAISERROR is included, any object for which RAISERROR is valid will have error events listed. This option is available for T-SQL based parsers.
  • SQL Server extended properties, or Enterprise manager descriptions are an alternate method to provide descriptions for use in DBDocumentor. Beginning with SQL Server 2000, Microsoft has provided a means for describing SQL object elements. Using SQL enterprise manager, developers can associate descriptions with the objects they are creating while in "design" mode of enterprise manager. These descriptions are stored internally as extended properties with a name of MS_Description. For more information on SQL Server extended properties, search the Books Online for "extended properties".

    If selected, this option indicates that the enterprise manager supplied description will be used if a DBDocumentor tag is not present. If a corresponding DBDocumentor tag is present, it will always be used regardless of this setting.

    In addition to the MS_Description property natively supported by SQL Server 2000, DBDocumentor offers several additional properties which can be used to enhance the meta data stored with your database.
    Note: If you do select to use SQL Server extended properties, and have selected to include SQL sources in the output documentation, you will have the option to include the extended properties in the SQL source listing for the object.
  • Spaces per tab character: Provides DBDocumentor with the number of spaces to insert in the output source code for each tab character found.
  • Override mode: Instructs DBDocumentor to only use the tags present in each batch. Use this setting to define the database interface before any code has been developed.
  • If you process temporary objects, DBDocumentor will include SQL Server temporary objects. SQL Server temporary objects are defined to begin with either # or ##, are temporary table variables or Common Table Expressions. There is no relationship between ignoring a drop and processing temporary objects.

Note: In versions of DBDocumentor prior to 4.00, DBDocumentor made no attempt to ensure that the named temporary object is unique within the documentation. Beginning with version 4.00 of DBDocumentor, temporary objects are encapsulated locally to the object which created them. This process results in accurate documentation, and hyperlinks.

  • If you choose to process temporary objects, you can optionally choose to suppress temporary objects in the data modifications list. This means that any listing which includes an object as modifying the data of a temporary object will not reference the temporary object. This option is particularly useful for suppressing the data population operation of a temporary table used in a query.
  • If you choose to process temporary objects, you can optionally choose to include the temporary objects in the table of contents. If you elect to not include the temporary objects in the table of contents, the only way to view the temporary objects will be via CHM search, and from the links of referenced objects.
  • Process dynamic SQL. If you wish to not include an of the SQL determined by the dynamic SQL processing engine, de-select this option.
  • If you choose to process dynamic SQL, you can suppress the Dynamic SQL # listings for procedure execution by de-selecting the Include dynamic SQL EXECUTEs.
  • If you are using dynamic SQL to create objects, and the names of the objects are dynamically created, DBDocumentor will incorrectly name the object being created. To eliminate this problem, de-select the Include dynamic SQL object creation option.

  • Press Next to set the output options.
  • Press Back to return to the SQL options page.
  • Pressing "?" will display this page.


DBDocumentor - Step 4 - Output options

User Interface DBDocumentor™

Output options

If you have loaded a project file, and that project file has files listed to process, the Finish button will be active and pressing it will begin processing of the project.

  • Output filename: You may enter any filename you wish, but if the extension is not .chm, .chm will be assumed.

Note: XML output following the SQLDocumentation schema will be written using this output filename. For example: if the output filename is Project.chm, then the XML file will be named Project.chm.xml.

  • Output directory: Allows you to specify where the output compiled help file is stored. Generally, this should be a working directory as DBDocumentor will generate various working files. This value is stored between runs and with new projects the most recent saved folder will be used as a default. A fully qualified path must be entered.

    If you enter the folder directly and it does not exist, you will be prompted to create it. Alternatively, you can press . . . and browse for a directory.

Note: You are strongly recommended to select an output folder that is not identical to the input folder. While there is no restriction on having the same folders, DBDocumentor will generate at least one output file for each object contained in the source SQL which could result in a large number of temporary files.

  • Save output location relative to source location: If the source drive and the output drive are the same physical drive, DBDocumentor can treat the output directory as being relative to the source directory. In other words, if you are storing your DBDocumentor generated documentation in a folder relative to the source, and decide to move the entire project to a different location, the DBDocumentor project will continue to be valid after the migration.

Note: Should you decide to migrate the project to a new location, if the relative path from source to destination is no longer a valid relative path (e.g. due to a reduction in the number of folders from the drive root), the source will be correct relative to the project file, but the destination will have the same path as it originally did. If the migration occurs to a different drive, the output will be on the new drive, and subject to the above rules will be relative to the source.

Note: You must always enter the full path for the output directory. Relative paths are not valid for this edit control. DBDocumentor determines at startup how relative paths will affect any given project.

Note: DBDocumentor will not consider UNC paths when determining a relative path. All UNC paths are considered absolutes.

  • If you do not select Output a CHM file, no output CHM (HTML Help) file will be create and the value for Launch compiled help will be ignored. If you do select to Output a CHM file, then you have the option to use a Modern MSDN layout. For those familiar with versions of DBDocumentor prior to 3.20, all output followed the "Classic" MSDN style.

Note: If none of the output options CHM, HTML or XML file are output, DBDocumentor will produce no output.

  • Beginning with DBDocumentor 4.10, there is an explicit option to output an HTML frameset. In prior versions, if you wished to generate a pure HTML output, you were required to select the CHM option, and deselect temporary file cleanup. This approach had two distinct downsides; there were unnecessary CHM files created, and it was the authors responsibility to create a frameset for the output.

    If you select HTML frameset output, DBDocumentor will create a frameset file named SQLDoc.htm. The frameset will contain a table of contents which mirrors that of the CHM output, and an index file. The output is JavaScript enabled, and opening any generated HTML file will cause the frameset to appear. If you are including custom fixed HTML content, please contact Pikauba Support for details on how to format your content such that it can automatically be loaded into the frameset if a user attempts to load the fixed content directly.

    The generated HTML files have been tested with Internet Explorer 6.0, Firefox 1.0 and Opera 8.5 running on a Microsoft Windows 2000 or higher platform. If you experience problems with the generated HTML output, Pikauba support will request browser details, operating system details and a screen shot of the problem. While reasonable efforts have been made to produce generated output which renders appropriately in all browsers, not every browser vendor implements the same functionality to the same degree.
  • If you do not select Output an XML file, no SQLDocumentation XML output file will be created.

Note: If none of the output options CHM, HTML or XML file are output, DBDocumentor will produce no output.

  • Launch compiled help: instructs DBDocumentor to launch the compiled help file after compilation has completed.

Note: If the file is open in the HTML Help viewer when compilation occurs, a warning message will be displayed. You will have the option of closing the open output file and continuing with the project.

  • Include source: Instructs DBDocumentor to include all text found in each batch in the compiled output. Source code is accessed by clicking the "Source" button at the top to the generated HTML page.
  • Colorize source code: Instructs DBDocumentor to apply Query Analyzer color syntax highlighting to the included source. This option is only valid if Include source is selected.

Note: Colorization is CPU intensive. Depending upon the SQL in your batches, and the available resources on your machine, it may take significant time to colorize the output. If you experience delays in producing colorized output, you may wish to run DBDocumentor with colorization selected for final documentation, or to run DBDocumentor in command line mode.

  • Hide encrypted source: If an encrypted object is found, and this option is selected, the source code of the object will be not be included in the output document.

Note: If the encrypted object creates other objects, and those objects are not encrypted, the source code for the encrypted object may be visible in these secondary objects. An example of such a condition is a stored procedure used to create objects.

  • Remove temporary files: Instructs DBDocumentor to delete any intermediate files generated as a part of building the project. DBDocumentor will produce at least one temporary file for each object being documented.
  • Allow any user to modify output: When working under Windows Server 2003, the output file will be owned by the user running DBDocumentor. Ownership implies that user account (and the Administrators security group) are the only users able to modify the output file. By selecting this checkbox, DBDocumentor will allow the default behavior but will also make any user who is a member of the Users security group able to modify the output file.

    This option is only enabled under Windows NT based operating systems, including Windows 2000 and XP.
  • Show source filename: if selected, this option instructs DBDocumentor to include the name of the file containing the given object.

  • Press Next to set the source options.
  • Press Back to return to the parser options page.
  • Pressing "?" will display this page.


DBDocumentor - Step 5 - Set source options

User Interface DBDocumentor™

Set source options

The file options page lets you define the various file types to use when building the list of files for the project, and the file inclusion rules. These options are only valid when the external file list is not selected.

  • Specify source directory: Indicates that you wish to specify a source directory and optionally the specific files to include in the project, but have not defined any external file list. This is the default option and corresponds to SQLHelp behavior.

Note: If you select the root of a drive, and to recurse from that point, there will likely be a large number of files for DBDocumentor to list and potentially process. It is advisable to choose a directory as close to the actual files to be documented as possible, or to use the external file list if the output document is to include content from multiple source locations.

  • Source directory: Allows you to specify where the source files are located if no external file list is used. For new projects, this value is always blank.

You can either enter the value directly, or press . . . to browse for the folder. If you enter the folder directly it must already exist.

Note: If "Specify source directory" is selected, DBDocumentor stores its project configuration file in the source directory specified here. When DBDocumentor opens the project, if it determines that the source directory defined in the project file is different than the location directory of the project file, the source directory defined for the project (and listed in this edit control), will be updated to reflect the project having moved. This capability allows for the project file and all its source files to be migrated from one source hierarchy to another with no loss of configuration. In other words, if you decide to move a DBDocumentor project, and all its sources files to a different location, the project file will remain valid. The command line version never updates its project file, but does follow these rules.

  • Use external file list: If selected indicates that an external file list is to be used for the list of SQL files to process. The location of the file list is specified in the File list edit box, or can be selected by pressing the . . . button to the right of the File list edit box.
  • External file list location: The location of the external file list. For new projects, this value is always blank.

    The file used for the external file list will need to have the files for the project listed with a carriage return line feed pair separating each file. The files need to have a fully qualified path to them (i.e. full drive letters or UNC path names) and will be processed in the order in which they appear in the list. If it becomes desirable to comment out a file, simply place two hyphens (--) in front of the file name.

    If an external file list is selected, you will not have the opportunity to specify a source directory or file extensions.

Note: If "Use external file list" is selected, DBDocumentor stores its project configuration file in the directory containing the external file list. When DBDocumentor opens the project, if it determines that directory containing the project file and the directory specified for the external file list are different, it will adjust the external file list location to be relative to the project file. This capability allows for the project file and all its source files to be migrated from one source hierarchy to another with no loss of configuration. In other words, if you decide to move a DBDocumentor project, and all its sources files to a different location, the project file will remain valid. The command line version never updates its project file, but does follow these rules.

  • Included file types: This option box indicates the file types DBDocumentor will work with. The supported default file types (or extensions) are: SQL, TSQ, SSQ, TXT, QUERY, SP, DB and if Reporting Services RDL is selected as an SQL object to process, XML and RDL. In addition to these predefined file types, DBDocumentor supports the definition of a custom file extension.

Note: The source files DBDocumentor processes are SQL script files, not the SQL database files (e.g. not the MDF or LDF if the dialect is Microsoft SQL Server).

  • Look in sub folders: If selected, this option will cause DBDocumentor to recurse the specified input folder for files to process. The file types to search for are defined in the Include file types option boxes.
  • Include all files meeting these criteria indicates that DBDocumentor will automatically include all files whose file extension matches the included file types in the source folder, and if recursion is turned on, all sub folders.

    Note: If this option is selected, the Next button will be disabled and the Finish button will become enabled. Press Finish when ready to process the SQL files into documentation.
  • Select the specific files to include indicates that you want DBDocumentor to display a list of files and have you specify which files to include in the project.

  • Press Next to select the files to include
  • Press Back to return to the output options page.
  • Pressing "?" will display this page.


Trouble Shooting

Troubleshooting DBDocumentor™

Troubleshooting the System

This page is a collection of items that have been shown to come up in the installation or operation of the system.

Installation

1. The system is designed under Microsoft Visual Basic® system. In order to run properly, the system needs to have Service Pack 5 installed. If it is not installed, the DLLs will be updated. Running the Setup application will normally take care of this step automatically.

2. The system also needs to have the Windows Script Host installed. The current version can be obtained from Microsoft at: http://msdn.microsoft.com/scripting/. DBDocumentor has been tested with Version 5.5 and 5.6 of the Windows Script Host.

3. Under no situations should the files located in the installation directory be modified. These files are encrypted, and if modified will cause the system to perform poorly at best, or not at all at worst.

4. You need to have the HTML Help Workshop installed on your system for the application to compile an output file. If this is not installed, you may experience errors in the application during its final phase. The current version of the HTML Help Workshop Compiler can be obtained from Microsoft at: http://msdn.microsoft.com/library/default.asp?URL=/library/tools/htmlhelp/chm/hh1start.htm

Note that while Windows 2000 and higher comes with the HTML Help compiler, the workshop compiler is required to perform the compilation.

Compiled Output Errors

The majority of errors associated with the compiled HTML output can be traced to misreads of the SQL. Most of these can be solved using the ##OV tag. We are constantly working to improve the reliability of the SQL parser we use. If you run into problems, and are comfortable sending us some of your SQL that is producing errors, please send it to support@pikauba.com indicating where the error is being tripped. We recognize that if you send us SQL that it is ours only to use in debugging your situation, and for the betterment of DBDocumentor for all. We will not make any use of SQL batches sent to use without express written consent from the submitter.

Common Issues

Error message box during compilation. This normally indicates the absence of the HTML Help workshop. The current version of the HTML Help workshop can be obtained from Microsoft at: http://msdn.microsoft.com/library/default.asp?URL=/library/tools/htmlhelp/chm/hh1start.htm

No output file is generated. Verify that the HTML Help Workshop from Microsoft® is installed.

Note that this situation may also manifest itself as a warning error box at the end of compilation of the project.

The project name is incorrect. The project name is determined by the destination file name chosen in step 2. If the name is incorrect, then verify you've chosen the correct name.

How do I remove the Pikauba shareware copyright? If you are not seeing your organizations' copyright notice (as defined in the ##CO tag) at the bottom of the pages then you are working with an unregistered version of the software. When you register the software, this notice is removed.

How do I remove the document preparation copyright? The Pikauba copyright notice stating that this document was prepared by a Pikauba software product can not be removed. If the presence of this copyright notice posses an issue for your organization, please contact Pikauba Software for details on how to remove the notice.

I do not see any project definition or copyright notices. Copyright and project definition information may only be present in the DBDocumentor .ini, or project XML files. If the file is not present, then no information can be obtained. Placing the ##PR and ##CO tags in any other location will cause them to be ignored.


DBDocumentor - Error Messages

Troubleshooting DBDocumentor™

Error Messages

In the course of DBDocumentor operation, you may experience a number of popup messages boxes. These message boxes are intended to provide users with the information they need to resolve issues arising during DBDocumentor execution. If you find an error message that does not guide you in the correct direction, please consult the troubleshooting guide, or send an email to our support staff at support@pikauba.com.

Configuration Warning

DBDocumentor has been designed to run on Windows 98, Windows ME, Windows NT 4.0 SP6a and above, Windows 2000, and Windows XP so the probability that you do not have a version of Internet Explorer installed on your system is fairly remote. If you have gone to the difficulty of removing all instances of Internet Explorer from your system, you will not be able to view compiled HTML Help files due to the HTML Help file viewers' dependency upon Internet Explorer.

Please note that DBDocumentor does not require you to set your default browser to Internet Explorer, rather a version of Internet Explorer must be installed on your system.

Note also that the absence of Internet Explorer does not affect the systems' ability to correctly process you ASP files.

This error message may appear at DBDocumentor system startup.

Which Version of IE?

We would generally recommend IE 4.01 SP1 or higher. This is due to various issues including support for DHTML, and resolution of various Y2K bugs that were present in previous versions.

DBDocumentor Validation Error

Input folder validation

If you elect to enter a folder name for the input folder directly, rather than browsing for it, you may inadvertently enter a folder that does not exist. This warning indicates just that situation.

This condition is validated when the next button is pressed on step 2.

Output folder validation

If you elect to enter a folder name for the output folder directly, rather than just browsing for it, you may inadvertently or intentionally enter a folder that does not exist. This warning indicates just that situation. If you accidentally entered an incorrect folder, simply press No and update the folder name (perhaps to the extent of browsing for it). If you intentionally entered a folder name that does not exist, pressing Yes will instruct DBDocumentor to attempt to create it. If no system error message occurs, the folder has been created.

This condition is validated when the next button is pressed on step 2.

Output Filename validation

If you enter a filename extension other than .chm, this warning will be generated. By default, the HTML Help viewer provided by Microsoft works only with .chm extensions. Even in the absence of the correct extension, DBDocumentor will correctly launch the output file, if instructed to do so in the project options.

Note: If no extension is supplied, DBDocumentor will assume .chm is intended and produce the appropriate output.

This condition is validated when the next button is pressed on step 2.

DBDocumentor Evaluation Warning

While in evaluation mode (i.e. not yet purchased), DBDocumentor has certain limitations. One of these limitations is the number of files it will process. All versions are limited to 10 files in evaluation mode. Pikauba Software feels that generating compiled help against a 10 file project provides sufficient data points with which to properly evaluate DBDocumentor.

You will see this warning whenever you attempt to add more than 10 files to the project while running in evaluation mode.

In addition to the 10 file limit, there is an effective 10 object limit as well. In the event that your project contains more than 10 objects, during evaluation, a similar dialog box will also be displayed.

Compilation Error - Missing Microsoft HTML Help Workshop

This error message will occur after all processing has occurred if your system does not have the requisite Microsoft HTML Help workshop compiler installed. The current version of the HTML Help Workshop can be obtained from Microsoft at: http://msdn.microsoft.com/library/default.asp?URL=/library/tools/htmlhelp/chm/hh1start.htm

The required files to generate the output have been created, so once the HTML Help Workshop is installed, you have the option of either re-running DBDocumentor, or simply running the .hhp file located in the output directory.

Please note that while Windows 2000 and higher does come with the HTML Help compiler, HHA.DLL installed by default, this is not the only component DBDocumentor requires. Installing the HTML help Workshop on a Windows 2000 or higher based system will result in the HTML Help Workshop installation program indicating that the HTML Help Compiler version on the system is the same or newer. This warning can safely be ignored.

DBDocumentor Internal Exception

If DBDocumentor encounters an internal error it generally will present a message box similar to the one shown above. If you encounter such a box, the indicated file, or object within the file has encountered a processing error that will prevent its inclusion in the final output file. The reason is also indicated. Generally this information is helpful to Pikauba support personnel. If you elect to contact Pikauba support at mailto:support@pikauba.com, please include the error message and a detailed description of what your system configuration is.

You are presented with the option of continuing processing. If you elect to continue, the file which experienced the error will be skipped, but other files will be included. If you elect to not continue, DBDocumentor will exit.


##AT Tag for Default Descriptions

Documentation Tags DBDocumentor™

Use of the ##AT Tag for Default Object Descriptions

DBDocumentor provides a simple method for categorizing the SQL objects being documented, the ##AT tag. This tag both allows for the definition of custom user groupings of SQL objects (e.g. all the product catalogue objects are grouped), but also provides a mechanism for overriding the default descriptions for the standard groupings. Overrides of default grouping descriptions are only valid in DBDocumentor.ini. Sub-grouping descriptions can be overridden using the ##ATG tag.

In addition to the method described below, the functionality of ##ATG is present and significantly expanded upon using the ##XMLINCLUDE XML file. The grouping and sub grouping names listed below are for use in the standard XML document element of the file.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##ATG and ##AT tags found in the INI file will be ignored.

The standard groupings in DBDocumentor are:

  • Stored procedures
  • Triggers
  • User defined types
  • Functions
  • Views
  • Tables
  • Indices

To override the default description associated with one of these groupings, you need only construct an ##AT tag using the name above with no description, and then have an ##AT tag with your desired description.

Note: Failure to have a blank description for the first occurrence of the ##AT for a given default grouping override will result in the custom description being appended to the default description.

Note: This usage of the ##AT tag is similar to that of SQLHelp, but differs in that all stored procedures are now located underneath the Stored procedure grouping. If you are a SQLHelp user who overrode their default descriptions, please see the ##ATG tag.

Syntax

-- ##AT Standard grouping ^^ Comment

Where Standard grouping is one of the standard grouping names listed above,
and Comment is the documentation text to use

Note: If the standard grouping name contains a space, then it must be followed by the ^^ separator. Failure to include the ^^ separator will result in a new grouping being defined, with the name of the grouping being the first word of the ##AT command.

Example

For example, to override the default description for stored procedures:

--##AT Stored procedures ^^
--##AT Stored procedures ^^ The new default description to be used


##ATG Tag for Default Descriptions

Documentation Tags DBDocumentor™

##ATG Tag

Use of the ##ATG Tag for Default Object Descriptions

DBDocumentor provides a simple method for categorizing the SQL objects being documented, the ##AT tag. This tag both allows for the definition of custom user groupings of SQL objects (e.g. all the product catalogue objects are grouped), but also provides a mechanism for overriding the default descriptions for the standard groupings. Overrides of default grouping and sub-grouping descriptions are only valid in DBDocumentor.ini.

In addition to the method described below, the functionality of ##ATG is present and significantly expanded upon using the ##XMLINCLUDE XML file. The grouping and sub grouping names listed below are for use in the standard XML document element of the file.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any ##ATG and ##AT tags found in the INI file will be ignored.

The following table describes the combinations of groupings and sub-groupings. Please note that not all combination are valid for all SQL dialects.

Grouping name | Sub-grouping name
Functions | Cursors
 | Modifies data
 | Returns data
 | Transactional
 | Scalar
 | Inline table
 | Multi-value table
 | Dynamic Content
 | Encrypted
 | Uncategorized
Indices | Unique
 | Clustered
 | Non clustered
 | XML
Stored procedures | Cursors
 | Modifies data
 | Returns data
 | Transactional
 | Executes procedures
 | Dynamic Content
 | Encrypted
 | Uncategorized
Tables | User
 | Session temporary
 | Global temporary
Triggers | Cursors
 | Modifies data
 | Returns data
 | Transactional
 | Executes procedures
 | On delete
 | On update
 | On insert
 | Instead of table changes
 | After table changes
 | Dynamic Content
 | Encrypted
 | Uncategorized
Views | Cursors
 | Modifies data
 | Returns data
 | Transactional
 | Executes procedures
 | Dynamic Content
 | Encrypted
 | Uncategorized
User defined types | User defined types

To override the default description associated with one of these groupings, you need only construct an ##ATG tag using the name above with no description, and then have an ##ATG tag with your desired description. Neither the grouping name nor the sub-grouping name is case-sensitive for this operation, but if either the grouping or sub-grouping contains whitespace, that whitespace is significant.

Note: Failure to have a blank description for the first occurrence of the ##ATG for a given default sub-grouping override will result in the custom description being appended to the default description.

Syntax

-- ##ATG Grouping name ^^ Sub-grouping name ^^ Comment

Where Grouping name is one of the standard grouping names listed above,
and Sub-grouping name is the sub grouping from the above table,
and Comment is the documentation text to use

Note: If the standard grouping name, or sub-grouping name contains a space, then it must be followed by the ^^ separator. Failure to include the ^^ separator will result in no modification to the standard descriptions.

Example

For example, to override the default description for stored procedures:

--##ATG Stored procedures
--##ATG Stored procedures ^^ Returns Data ^^ The new default description to be used


SQLHelp/DBDocumentor comparison

Overview DBDocumentor™

SQLHelp vs. DBDocumentor™ Comparison

If you are an existing SQLHelp user, you may be interested in upgrading from SQLHelp to DBDocumentor. The following chart details some of the differences between SQLHelp versions, and DBDocumentor.

Feature | SQLHelp 2.x | DBDocumentor™ 3.x | DBDocumentor ™ 4.x
SQL Parser | Third generation SQL parser able to work with complex SQL, but with primitive support for dynamic SQL | Forth generation SQL parser able to work with the most complex SQL, including support for dynamic SQL | Fifth generation SQL parser able to function with multiple SQL dialects.
SQL Dialects | Microsoft SQL Server 2000 | Microsoft SQL Server 2000 | Microsoft SQL Server 2000, Sybase ASA 9, Firebird 1.5, Microsoft SQL Server 2005
Dynamic SQL control | None | None | Can specify if dynamic SQL is to be processed, and if processed the types of data to be included
Temporary object processing | None | Flag to indicate if temporary objects are processed | Can specify if temporary objects are processed, and if so how they are treated in the output
Objects documented | Stored Procedures | Data views, stored procedures, user defined data types, user defined functions, tables, indices, constraints, security roles, system messages and generic SQL batches | Data views, stored procedures, user defined data types, user defined functions, tables, indices, constraints, security roles, system messages and generic SQL batches Beginning with version 4.20, DBDocumentor can process Microsoft Reporting Services RDL.
Support for ALTER and DROP | Yes, on stored procedures only | Yes, and DROP can be optionally ignored | Yes, and DROP can be optionally ignored
Support for RAISERROR | Yes | Yes | Support for dialect specific error and exception handling
Support for SQL Server 2000 enterprise manager object descriptions (extended properties) | Only for stored procedures | Yes, and includes specialized Pikauba Software extended properties | Support for dialect specific extended properties and meta data. If the SQL dialect supports user defined values, Pikauba Software extended properties can be used.
Colorization of output | Yes | Yes | Yes
Support for external file lists | Yes | Yes | Yes
Linkage between source files and summary documentation | Yes | Yes | Yes
Object hyperlinking (Cross references) | Called and calling procedures are hyperlinked | Hyperlinks are present between all documented objects. For example, to find all the objects making use of a table, simply open the table description in the output document and a list of all objects linking to the table are displayed. If the object is in the project, a hyperlink will be present. | Hyperlinks are present between all documented objects. For example, to find all the objects making use of a table, simply open the table description in the output document and a list of all objects linking to the table are displayed. If the object is in the project, a hyperlink will be present.
Evaluation limits | 10 Stored procedures | 10 SQL objects | 10 SQL objects
XML output file | No | XML output is optional and follows the SQLDocumentation schema | XML output is optional and follows the SQLDocumentation schema, updated for version 4.x
HTML output option | No table of contents | No table of contents | Full HTML output option
Command line operations | No | Yes | Yes
Parsing errors abort | A parsing error will skip to the next batch script | A parsing error will skip to the next batch script | A parsing error will skip to the next batch script

© 2005 Pikauba Software. All rights reserved.


Extended Block Commenting Tags

Extended block commenting (annotation) tags are intended for those users who are providing long descriptions for object descriptions, or project descriptions. If a regular comment tag is present, any block comment tag for the same object, or object element (e.g. procedure parameter), will be ignored. Block comment tags are designed for use within the multi-line comment block delimited by /* ... */, though they can be used in a single line comment.

Please see the individual commenting tags, or the tag reference page for a list of tags supporting extended block comments.

Since extended block comments make HTML fragments easier to work with for descriptions, users should familiarize themselves with the valid HTML rules.


DBDocumentor - Select Input

User Interface DBDocumentor™

Select Input Location

In this dialog you select the location of the files for the project. The default extension is will match the file types you've defined for the project.

Note: DBDocumentor will not recurse into folders by default. If you wish to recurse folders, you will need to select that option under File Options.

Both the folder and the default extension are saved for future runs of DBDocumentor.

Press Save when done


DBDocumentor - Select Output

User Interface DBDocumentor™

Select Output Location

In this dialog you select the location of the output files for the project. The output files consist of the project chm file, and all HTML files required to prepare a web site containing the documentation.

Important: You are required to enter a name for the chm file. This name, including case, will become the project name for this project. You can enter it in this dialog.

Note that these values are saved for future runs of DBDocumentor.

Press Save when done


DBDocumentor.ini

Documentation Tags DBDocumentor™

DBDocumentor.ini File

The DBDocumentor.ini file is a simple text file that you should create in the same folder as the SQL batches. That is to say, in the same folder as the project file (*.DBDocumentor) is located. DBDocumentor.ini is used to contain project specific information. The DBDocumentor.ini file is the only valid location for ##CO, ##PR and ##PPH tags.

The ##AT tag is also valid syntax for DBDocumentor.ini. In addition to allowing the definition of new object groups, the ##ATG tag, when used in DBDocumentor.ini, can define the text displayed with the stock groupings of Stored procedures, Tables, Triggers, Views, Indices, User defined types, and Functions.

In addition to the method described above for custom group definition, the functionality of ##AT and ##ATG is present and significantly expanded upon using the ##XMLINCLUDE XML project file.

Note: If the ##XMLINCLUDE directive is found in the DBDocumentor.ini file, any other tags found in the INI file will be ignored.

Note: Definitions made in a SQLHelp project which you are now using DBDocumentor to process will continue to be read.