Oracle9iAS Portal provides consistent ways to trap erroneous input and provide meaningful error messages.  The Portal has methods for managing the internal error stack.  This stack keeps track of raised exceptions and information about those errors.  Oracle9iAS Portal also has a set of APIs for presenting errors in a standardized way.

Error handling services are available through the  wwerr_api_error  and  wwerr_api_error_ui packages.

Key Features

Error handling services in the Oracle9iAS Portal framework have the following key features.

Error Messages

Error handling services provide a way to define meaningful error messages.  To define your own error messages, you need to define its name space.  That name space consists of:

• Name :  Error Name
• Domain :  Area of the product where the error occurred.
• Sub-domain :  Sub-system that generated the error.
• Context :  Name of the function where the error occurred.

The name space uniquely identifies your error message. If it does not do so, a 'wwc-0000' error message will be generated.

The default domains include the Portal (WWC), Application (WWV) and Content Areas (WWS).  Each domain is further classified into sub-domains which define the object types.  The Oracle9iAS Portal domain includes Portlet, Page, Document object types; the Application domain includes Form, Menu, Report, Chart etc.; and the Content Area domain includes Folder, Item, Category, Perspective etc.  If you need to define a different type of error that does not fall within these domains and sub-domains classification, define your own domain and sub-domains for your errors.

Error Stack

Oracle9iAS Portal uses an error stack to keep track of the error messages.  The error messages are pushed on to an Error Stack whenever errors occur. Whenever procedures or function calls are nested, the error stack keeps track of all the error messages.  You can choose to retrieve only the top error ( or most recent error) by using the wwerr_api_error.get_top method.  Alternatively you can get all the error messages on the stack by using wwerr_api_error.get_errors method.  The stack can also be checked for presence of any errors by calling the wwerr_api_error.is_empty method.

Message Parameters

The NLS strings that you create for your errors can take substitution parameters for your messages. For example with NLS string: 

(domain='yahoo', subdomain='provider', name='generalerror', string='Error: %1') 

an error can be added as :
wwerr_api_error.add(p_domain=>'yahoo',  p_sub_domain=>'provider',  p_name=>'generalerror',  p_context=>'yahoo.show',  p1
=> sqlerrm);

The p1, p2, p3.. parameters can be used to pass substitution parameters to the error messages. 

Error Display

The wwerr_api_error_ui package provides a means to generate a standard User Interface for displaying the errors in Oracle9iAS Portal. The error messages can be displayed in two different ways:

• Full Screen UI :  These error messages are displayed in a full screen mode.  You may want to display full screen errors when the system encounters fatal or show-stopper errors.
• In-line UI :  These error messages are displayed in-line within the current page itself.  You may use in-line errors for minor errors or warnings.  

Additionally you can choose the output format of the display from:

• HTML output
• XML output
• ASCII text output

How to Use Error Handling

The general model for working with the error handling can be described as follows:

1. On detecting erroneous conditions, add the error message, with an appropriate domain and sub-domain combination, using the wwerr_api_error.add method.  This adds the error message to the stack.
2. At the end of a routine, or as per your requirement, expose the error messages using the wwerr_api_error_ui calls.  To display full screen messages, use the methods show_html, show_xml or show_text depending on the output type you desire.  To display inline messages, use the methods show_inline_html, show_inline_xml or show_inline_text depending on the output type you desire.

Note: Remember to seed the NLS strings for your error messages.  The document on Implementing NLS Service describes how string definitions are loaded into the database.

The standard UI for error messages also provides a navigation link to go back to the previous page.  It also includes a 'Help' icon to link to the specified Help URL.

Tips for using Error Handling

While handling errors with the provided API, keep in mind the following:

Error Handling usage hints

• While defining your own error messages, use your own error domain for these messages.  Never use the domain WWC, WWV or WWS for your error messages.  You will need to write a small loader script to load these into the NLS tables.

• Avoid unnecessary error messages.  If you do not want to do anything in a function just return null, not an error.  For example, say you are coding a copy_portlet procedure in a portlet since the provider calls it for its other portlets.  If you do not wish the copy_portlet procedure for this particular portlet to do anything, then just return null.  If you return errors, this will unnecessarily disrupt the portlet functionality. 

• Maximum of 10 error messages on the stack. Keep in mind that you can add up to 10 error messages on the stack at a time. Beyond that number, additional messages get ignored when an wwerr_api_error.add call is made. 

• Output format for HTML works. In the future the XML and ASCII text format for output will also be implemented.

• Use the API for a programmatic way of finding the problem. You can use a non-ui format for determining the problems.  For example when programmatically registering a provider the exception block can use get_text_stack to get the error messages and then can print them out. This helps when debugging calls to Public APIs since all of them add errors to the stack when exceptions are raised. 

For further details regarding implementation, refer to Implementing Error Handling.

Revision History

• November 14, 2000.