DBDocumentor ™ Runtime Issues

The issues listed here are specific to DBDocumentor . If you do not see the issue you're facing addressed, it may be addressed in the general section, or it may be new to us. If after checking the general section, you still don't find a resolution, please drop us an email, with as many details as possible.

Some of my objects are missing from the output, why?
I occasionally receive an access violation in hhc.exe during output compilation. Is there a fix for this?
When the project starts processing, my CPU goes to 100% for a rather long time, and task manager shows it as not responding. Why?
During the processing of my project, my CPU goes to 100% and task manager show it as not responding, why?
My procedure, data view, or table function returns only one result set, but DBDocumentor lists more than one, why?
I have a procedure that returns information via SELECT *. Why do I not see the column names?
I have joins that return the same column name from multiple tables, but DBDocumentor only lists the column name once.
My procedure returns a result set from a nested procedure. How can I get that result set to be included?
I run DBDocumentor against my files, but get no output. Am I doing something wrong?
When I try to print a topic and its subtopics, I receive a script error. Please explain.

Some of my objects are missing from the output. What could be causing this?

When DBDocumentor processes a script file, the SQL parser will break the script into individual batches. The breaking point is a GO directive. If no GO is found in a script file, the entire file is treated as a single batch. The DBDocumentor SQL parser does not process the file sequentially, rather it processes each batch sequentially and looks in each batch first for CREATE statements and then for any DROP statements. If a DROP statement is present for an object already present in the project, the object is dropped.

If the DROP for an object is present in the same batch as its CREATE, and occurs after the CREATE, then DBDocumentor will add and then remove the object from the project, creating the scenario of missing objects for DBDocumentor.

To work around this issue, ensure that if a DROP is present in a script file for an object you wish to have documented, that the DROP is contained in a batch occurring prior to the CREATE.

Back to Top

I occasionally receive an access violation in hhc.exe during output compilation. Is there a fix for this?

There are a variety of reasons under which this may occur. By way of background, hhc.exe is a component of the Microsoft HTML Help Workshop, and is the actual compiler of your CHM file. Most reasons for access violations in hhc.exe are not under the control of Pikauba Software, but here are a few scenarios:

If the HTML Help Workshop is installed on a different drive from the location where the output CHM is being generated, then an access violation could occur. This scenario was fixed in version 3.20.
If you are working in a language which can not be represented in the US English ANSI character set, access violations in hhc.exe may occur. Normally this scenario should only occur with the actual annotation (documentation) associated with your project. If this is the case, please use HTML literals to escape the characters you wish to represent.
If you are entering HTML into any documentation element, or are including fixed content pages in the output CHM, all your HTML must be well formed (validated). In addition to the well-formedness criteria, experience has shown that all HTML attributes must be enclosed in double quotes. Single quoted HTML attributes and non-well formed HTML has been shown to generate access violations in hhc.exe.

If these situations do not describe what you're seeing, please contact support with the following information:

OS Version and Language
Version of hhc.exe
Version of DBDocumentor

While it is our objective to mitigate this problem within DBDocumentor, an actual resolution lays with Microsoft.

Back to Top

My CPU goes to 100% when I start processing a project.

It is not uncommon for a computers CPU to go to 100% for a period of time when heavy work is being performed. In the case of DBDocumentor™, this will happen on virtually all classes of CPU regardless of processor speed when a file is first loaded, and only when a file is first loaded. If your SQL project is made up of a single file containing all the script batches of your database, the length of time the CPU is at 100% will be longer. If a file contains a single script, the period of time maybe undetectable.

During file load operations a number of sanity checks are performed on the file and the larger the file, the greater the number of checks. It is also possible that Task Manager will report the DBDocumentor™ or DBDocumentor™ process as not responding.

By way of example, if a single file is used to contain a database of 50 tables and their indices, with approximately 400 stored procedures for these tables, and all the associated DROP statements and default data, this file will take between 10 and 15 seconds to load on a Pentium IV class machine. If this same file is broken into many files with each individual file containing a single SQL object, the load time is not noticeable.

For DBDocumentor, this problem was resolved in version 2.31.

Back to Top

My CPU goes to 100% during the processing of a project.

DBDocumentor processes projects as a foreground application and conducts a large number of string based operations when parsing the SQL. Under normal circumstances it is not uncommon for the CPU to be at 100%, but in these situations the system will be responsive and task manager will not indicate that DBDocumentor has stopped responding. Under certain specific scenarios, DBDocumentor versions prior to 3.10 can hang.

If you are experiencing this problem, please first verify that you are running the most recent version of DBDocumentor. If you are and are still experiencing the problem, please contact Pikauba Software to see if a fix is under development.

The following is a list of parsing issues which were present in previous versions, and illustrate workarounds users may try to resolve the problem.

Excess white space in dotted identifiers (e.g. whitespace surrounding the dot)
Lack of whitespace surrounding operators
(e.g. col1/col2 as opposed to col1 / col2)
Use of whitespace in constraint names

Back to Top

My procedure, data view, or table function returns only one result set, but DBDocumentor lists more than one, why?

This is by design, and occurs if conditional logic directs the result set output. It allows you to ensure that the format of the result sets is the same. If differences are noted, this could pose a problem to the consumers of this object.

Back to Top

I have a procedure that returns information via SELECT *. Why do I not see the column information?

This is by design. If you are including the table, data view or table function in the project, DBDocumentor will attempt to locate and hyperlink to the table. DBDocumentor will not expand the column information as this result set is intrinsically non-deterministic. From an interface design perspective, you may wish to consider redefining the procedure to return only named columns.

Back to Top

I have joins that return the same column name from multiple tables, but DBDocumentor lists the column name followed by a numeral.

This is by design and indicates that duplicate column names are present. It should be noted that any access to objects containing duplicate column names will present difficulties to client side APIs such as ADO and ADO.Net.

Back to Top

My procedure returns a result set from a nested procedure. How can I get that procedure to be included?

Currently the only method to accomplish this is via the override tag. You would need to include the parameters of the nested result set in the upper level procedures' documentation, then use the override tag in the upper level procedures' documentation. e.g.

--##OV
--##BD We are using a nested procedure here
--##RS1 UserName ^^ The user's name
--##RS1 Address ^^ The user's address

Back to Top

I run DBDocumentor against my files, but get no output. Am I doing something wrong?

There are a number of reasons why no output might be returned. For the purposes of this discussion, it will be assumed that DBDocumentor runs to completion with no obvious errors and a compiled help file is produced. This help file would contain only an overview section. Some of the reasons for this situation include:

Your SQL batch contains no CREATE statements for the SQL objects you selected to be documented, or you have not instructed DBDocumentor to process any SQL objects.
If in the same batch (i.e. in the same text area containing a GO statement, or the entire file if no GO is found), a drop for an object was found, then DBDocumentor will first parse the procedure adding it to the project, then parse the DROP and remove it. To resolve this issue, ensure that all CREATE and DROP statements are contained in separate batches, and that the DROP statements are processed prior to the CREATE. If working with version 3.10 or higher, you can also change the project settings to ignore DROP statements for the SQL object type you are working with.
You have defined in the XML project file to not include any stock categories, and none of your custom categories have associated objects defined by ##AT tags.

Back to Top

When I try to print a topic and its subtopics, I receive a script error. Please explain.

In order to present the modern MSDN layout option (and by extension the classic layout), DBDocumentor makes use of an external JavaScript file. If you select the "print the selected heading and all subtopics" print option, the HTML Help viewer extracts all the pages to be included and concatenates them into a single web page, then prints the temporary page. The problem arises due to a bug in the viewer's extraction logic and external files.

Specifically, since the JavaScript used by DBDocumentor is contained in an external file and the HTML Help viewer fails to extract external JavaScript files, the "object error" occurs when the HTML Help viewer print function attempts to render the concatenated HTML. DBDocumentor 3.31 resolved this problem to the best extent possible, but if you're using external JavaScript to create effects in your content (fixed content, object descriptions, summary descriptions), then you could experience a similar problem during printing.

If you're using a Pikauba Software product, and are experiencing this problem with your external JavaScript files, please contact support (support@pikauba.com) with a sample of your document and we'll try to see if there is any solution for your specific situation.

Developers interested in more information on this subject may wish to view:

HTML Help Frequently Asked Questions

PRB: Text Missing When You Print "Selected Heading and All Subtopics" from HTML Help

Style sheets are not applied when you print multiple Help topics from an HTML Help Workshop application

Printing Books from CHM Causes Message

RoboHelp Support Forums - Script Error when printing Help Topics