What attributes of SQL objects are documented by DBDocumentor?

Looking at both the sample files, the 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.  You may also want to refer to how DBDocumentor handles dynamic SQL.  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:

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:

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:

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".

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:

Input parameters

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

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:

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:

Triggers

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

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.

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:

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. 

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:

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:

Synonyms

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

Synonyms have the following attributes documented:

Microsoft Reporting Services RDL

Microsoft 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:

 

© 2001 - 2009 Pikauba Software. All rights reserved.

DBDocumentor and SQLDocumentation are trademarks of Pikauba Software.