Overview

Implement error checking at every query in a consistent way and integrate errors generated in the database backend more cleanly with the GUI client frontend.

Functional Requirements

• Be able to translate errors returned by and exceptions raised by stored procedures and triggers using the GUI client's preferred language.
• Simplify the error checking code where possible.
• Make it more difficult for errors to be ignored.
• Reduce redundancy in GUI client error messages (eliminate duplicate strings).
• Ensure that every query in the GUI client has appropriate error checks.
• Allow users to see differing degrees of detail, so casual users aren't put off by computerese but administrators still have enough detail to diagnose and either fix problems or report bugs.

New Terms and Definitions

This is the place to define new words and phrases to be used in the application and the documentation. If this feature introduces a new concept or changes the semantics of an existing concept in the application then define it here. Define it even if you think the definition should be obvious, since your definition might not match the definition used by the reader, like so:

• new term

  • new definition

• revised concept

  • new definition, followed by how the new semantics differ from the old

Related Existing Functionality

• Some functions return

  • < 0 for error

  • 0 or id > 0 for success

• Some functions return true/false
• Some functions raise exceptions on error conditions

C++ code currently should, but doesn't always,

if the query returned a result
{
  if result is an error indicator then
    display a message
    quit
  do stuff if there was no error indicator
}
else if the query got a backend error
{
  display an error
  quit
}
else // if no rows were returned
  handle the empty case

but it would be nice if this could simply be

if the query returned without an error
  do stuff
else
  display an error
  quit
else // if no rows were returned
  handle the empty case

Similar and Related Requests

What other requests have we gotten that might tie in nicely with this feature?

What open issues might be addressed by this feature?

Try to create hyperlinks to web-accessible data, such as this link to Mantis issue 2949.

Conflicting Features

What features currently exist and what feature requests have we received that might conflict with the feature described here?

User-Level Functionality

Describe how the new functionality will appear to and behave for the application user. To write this properly you will need to jump back and forth between this section and the Internal Design section.

Describe the menu changes and overall application structure changes here then get detailed in the subsections.

Window Changes

What windows do we expect to change?

What windows do we expect to eliminate?

What windows do we expect to add?

Insert screen shots of window mock-ups like this:

[Insert image here.]

Describe what each window does, what its fields mean, what the buttons do, what right-click menu items are available in the list views, etc.

Report Changes

What reports do we expect to create, eliminate, or change?

Batch Manager Changes

What functionality do we expect to add to, remove from, or change in the Batch Manager?

Usability Considerations

How do we think this will affect user access to existing functionality?

What problems do we anticipate users might have with this functionality and how can we minimize the impact of these problems?

What errors or abnormal situations do we expect users might encounter during normal processing and how can we make it easy for the user to fix these problems using the application?

Problems and Alternatives

What might go wrong with the solution described in this document?

Why might this not be the best solution?

What are the limitations of this approach? What's missing that might be desirable?

Describe briefly other ways to solve the basic problem and the advantages and disadvantages of each alternative.

Justify the chosen solution or argue why one of the alternatives would be better. Be as broad as possible here, since an important purpose of this section is to provide alternatives in case the initial attempt at implementation encounters a significant implementation block.

Internal Design

Now that we have defined what we have to do and how we think it should look to the user, we can describe the internal structure of the application. If possible, outline the architecture of the feature implementation here. Then in the sections below describe the changes and additions to the application to create this architecture.

Basic Algorithms

Are there particular algorithms required to implement this feature? If so, describe them here.

If you are going to outline a particular algorithm in pseudo-code
    put it in a programlisting
    try to limit lines to approximately 80 characters
    try to limit programming constructs while still being clear about intent
end if // a programming construct that may be unavoidable to maintain clarity

Custom Widget Changes

Do we expect to modify existing custom widgets to support the windows described above?

What new custom widgets will we need? Will they be derived from existing widgets? What behavior do we expect from them?

Schema Changes

What changes do we anticipate making to the database schema? New tables? Views? Indexes?

The new whatever-you-call-it table

What privileges do we need?

Stored Procedure Changes

What stored procedures do we expect to create, eliminate, or change?

Performance Considerations

How will this feature impact the performance of the application overall?

Error Handling

What internal errors do we anticipate might occur?

How can we best hide them from the user, prevent them, or fix them automatically?

QA Considerations

Does this feature require any special tools or data to test? Is it testable (some features may be hard to reach from the user level)?

What are some anticipated areas of concern that require special attention?

Documentation Considerations

Is there a significant documentation impact?

Does the feature require a standalone essay or only field-level descriptions?

Release Considerations

What release would we like to target?

What is the potential impact on a release if we don't finish in time?

What happens if we only get some of the functionality done?

Are there any pieces that would be useful on their own?

Are there any dependencies on other features or applications (such as Qt 4 or a particular release of OpenRPT)?

What is the anticipated impact on users, particularly those who have customized the sources, reports, and database schema?