Package wwerr_api_error

This package contains methods to add, retrieve and clear errors from an error stack, a warning stack and other related operations. It is used as part of error handling methodology.

For more information, see Error handling and display methods.

Scope:

Public

Since:

Oracle Portal 3.0.6.6.5

error_record

type error_record is record (
    product varchar2(12),
    code integer,
    text varchar2(2000),
    context varchar2(64),
    msg_domain wwnls_strings$.domain%type,
    msg_sub_domain wwnls_strings$.sub_domain%type default 'all',
    msg_name wwnls_strings$.name%type,
    msg_id wwnls_strings$.id%type,
    msg_p1 varchar2(2000) default null,
    msg_p2 varchar2(2000) default null,
    msg_p3 varchar2(2000) default null,
    msg_p4 varchar2(2000) default null,
    msg_p5 varchar2(2000) default null,
    msg_p6 varchar2(2000) default null,
    msg_p7 varchar2(2000) default null,
    msg_p8 varchar2(2000) default null,
    msg_p9 varchar2(2000) default null,
    call_stack varchar2(4000) default null,
    show_to_user boolean default true
)

A record structure containing details of an error record.

Fields:

product - the name of the product that owns the error

code - the record ID returned as an NLS string ID

text - the text string of the error message

context - the name of the method in which the error occurred

msg_domain - the name of the domain that generated the error

msg_sub_domain - the name of the sub-domain that owns the message

msg_name - an identifier for the message

msg_id - a unique identifier for the messge

msg_p1 - passed-in values for the resulting display message

msg_p2 - passed-in values for the resulting display message

msg_p3 - passed-in values for the resulting display message

msg_p4 - passed-in values for the resulting display message

msg_p5 - passed-in values for the resulting display message

msg_p6 - passed-in values for the resulting display message

msg_p7 - passed-in values for the resulting display message

msg_p8 - passed-in values for the resulting display message

msg_p9 - passed-in values for the resulting display message

call_stack - this field is not currently used

show_to_user - should this error message be shown to the user?

Since:

Oracle Portal 3.0.6.6.5

error_table

type error_table is table of error_record index by binary_integer

A table of error records.

DOMAIN_WOR

DOMAIN_WOR constant varchar2(12) := 'wor'

Reserved domain name. For internal use only.

DOMAIN_WWC

DOMAIN_WWC constant varchar2(12) := 'wwc'

Reserved domain name. For internal use only.

DOMAIN_WWF

DOMAIN_WWF constant varchar2(12) := 'wwf'

Reserved domain name. For internal use only.

DOMAIN_WWS

DOMAIN_WWS constant varchar2(12) := 'wws'

Reserved domain name. For internal use only.

DOMAIN_WWU

DOMAIN_WWU constant varchar2(12) := 'wwu'

Reserved domain name. For internal use only.

DOMAIN_WWV

DOMAIN_WWV constant varchar2(12) := 'wwv'

Reserved domain name. For internal use only.

SUBDOMAIN_POB

SUBDOMAIN_POB constant varchar2(12) := 'pob'

Reserved subdomain name. For internal use only.

SUBDOMAIN_WEBDAV

SUBDOMAIN_WEBDAV constant varchar2(12) := 'webdav'

Reserved subdomain name. For internal user only.

add

procedure add(
    p_domain in varchar2,
    p_sub_domain in varchar2 default 'all',
    p_name in varchar2,
    p_context in varchar2,
    p1 in varchar2 default null,
    p2 in varchar2 default null,
    p3 in varchar2 default null,
    p4 in varchar2 default null,
    p5 in varchar2 default null,
    p6 in varchar2 default null,
    p7 in varchar2 default null,
    p8 in varchar2 default null,
    p9 in varchar2 default null,
    p_show_to_user in boolean default true
) 

Adds an error to the error stack, given domain, sub-domain, name and context.

The add procedure searches the NLS string storage and retrieves an NLS string for the given domain, sub domain, name and current session language. The returned NLS string is then used as an error message that is added to the error stack. You can define values for the substitution parameters when calling this procedure. The error message must contain the markup characters %1 to %9 in order to pass in the appropriate parameter values.

Notes:

• Because any specific error may be produced in multiple places in the executing code, each error is identified in its unique context, which includes both package and method names, as: [package].[function], for example: wwpro_api_provider.show.
• There are predefined strings in the NLS store that can be used for displaying error messages. For example, if an Oracle error occurs, you can call the add procedure and specify wwerr_api_error.DOMAIN_WWV for the domain, 'oracle' for the sub domain, 'generic' for the name and sqlerrm for p1.
• Errors are stacked on the name of the method that experienced the error, for example: wwpro_api_provider.show.

Example:

    declare
          l_error_table wwerr_api_error.error_table;
    begin
          wwerr_api_error.add
          (
                p_domain     => wwerr_api_error.DOMAIN_WWV,
                p_sub_domain => 'oracle',
                p_name       => 'generic',
                p_context    => 'example.test',
                p1           => sqlerrm
          );
          l_error_table := wwerr_api_error.get_errors;
    end;
 

Parameters:

p_domain - the short name of the product or domain in which the error occurred

p_sub_domain - the subsystem that generated the error

p_name - the name of the error within the domain and sub-domain

p_context - the name of the function in which the error occurred

p1 - first passed-in value for the resulting display message

p2 - second passed-in value for the resulting display message

p3 - third passed-in value for the resulting display message

p4 - fourth passed-in value for the resulting display message

p5 - fifth passed-in value for the resulting display message

p6 - sixth passed-in value for the resulting display message

p7 - seventh passed-in value for the resulting display message

p8 - eighth passed-in value for the resulting display message

p9 - nineth passed-in value for the resulting display message

p_show_to_user - should this error message be shown to the user?

Since:

Oracle Portal 3.0.6.6.5

add

procedure add(
    p_domain in varchar2,
    p_id in integer,
    p_context in varchar2,
    p1 in varchar2 default null,
    p2 in varchar2 default null,
    p3 in varchar2 default null,
    p4 in varchar2 default null,
    p5 in varchar2 default null,
    p6 in varchar2 default null,
    p7 in varchar2 default null,
    p8 in varchar2 default null,
    p9 in varchar2 default null,
    p_show_to_user in boolean default true
) 

Adds an error to the error stack, given domain, ID, and context.

The add procedure searches the NLS string storage and retrieves an NLS string for the given domain, message ID and current session language. The returned NLS string is then used as an error message that is added to the error stack. You can define values for the substitution parameters when calling this procedure. The error message must contain the mark up characters %1 to %9 in order to pass in the appropriate parameter values.

Notes:

• Because any specific error may be produced in multiple places in the executing code, each error is identified in its unique context, which includes both package and method names, as: [package].[function], for example: wwpro_api_provider.show.
• There are predefined strings in the NLS store that can be used for displaying error messages. For example, if an Oracle error occurs, you can call the add procedure and specify wwerr_api_error.DOMAIN_WWV for the domain, '11230' for the ID and sqlerrm for p1.
• Errors are stacked on the name of the method that experienced the error, for example: wwpro_api_provider.show.

Example:

    declare
          l_error_table wwerr_api_error.error_table;
    begin
          wwerr_api_error.add
          (
                p_domain  => wwerr_api_error.WWV,
                p_id      => 11230,
                p_context => 'example.test',
                p1        => sqlerrm
          );
          l_error_table := wwerr_api_error.get_errors;
    end;
 

Parameters:

p_domain - the short name of the product in which the error occurred

p_id - the ID number of the error

p_context - the name of the function in which the error occurred

p1 - first passed-in value for the resulting display message

p2 - second passed-in value for the resulting display message

p3 - third passed-in value for the resulting display message

p4 - fourth passed-in value for the resulting display message

p5 - fifth passed-in value for the resulting display message

p6 - sixth passed-in value for the resulting display message

p7 - seventh passed-in value for the resulting display message

p8 - eighth passed-in value for the resulting display message

p9 - nineth passed-in value for the resulting display message

p_show_to_user - should this error message be shown to the user?

Since:

Oracle Portal 3.0.6.6.5

add_warning

procedure add_warning(
    p_domain in varchar2,
    p_sub_domain in varchar2 default 'all',
    p_name in varchar2,
    p_context in varchar2,
    p1 in varchar2 default null,
    p2 in varchar2 default null,
    p3 in varchar2 default null,
    p4 in varchar2 default null,
    p5 in varchar2 default null,
    p6 in varchar2 default null,
    p7 in varchar2 default null,
    p8 in varchar2 default null,
    p9 in varchar2 default null,
    p_show_to_user in boolean default true
) 

Adds a warning to the warning stack, given domain, sub-domain, name and context.

Call this procedure to add a warning to the warning stack, given the domain, sub-domain, name and context.

Notes:

- Because any specific warning may be produced in multiple places in the executing code, each warning is identified in its unique context, which includes both package and method names, as: [package].[function], for example: wwpro_api_provider.show.
- When other errors exist, push the Oracle error onto the stack. The WWV name space is predefined with the warning message: oracle. generic(11230), and with one parameter, which is passed as sqlerrm.
- Warnings are stacked on the name of the method that experienced the warning, for example: wwpro_api_provider.show.

Example:

    declare
          l_warning_table wwerr_api_error.error_table;
    begin
          wwerr_api_error.add_warning
          (
                p_domain     => wwerr_api_error.DOMAIN_WWC,
                p_sub_domain => 'err',
                p_name       => 'oracle_generic',
                p_context    => 'example.test',
                p1           => 'test_error'
          );
          l_warning_table := wwerr_api_error.get_warnings;
    end;
 

Parameters:

p_domain - the short name of the product or domain in which the warning occurred

p_sub_domain - the subsystem that generated the warning

p_name - the name of the warning within the domain and sub-domain

p_context - the name of the function in which the warning occurred

p1 - first passed-in value for the resulting display message

p2 - second passed-in value for the resulting display message

p3 - third passed-in value for the resulting display message

p4 - fourth passed-in value for the resulting display message

p5 - fifth passed-in value for the resulting display message

p6 - sixth passed-in value for the resulting display message

p7 - seventh passed-in value for the resulting display message

p8 - eighth passed-in value for the resulting display message

p9 - nineth passed-in value for the resulting display message

p_show_to_user - should this warning message be shown to the user?

Since:

Oracle Portal 9.0.2.6

add_warning

procedure add_warning(
    p_domain in varchar2,
    p_id in integer,
    p_context in varchar2,
    p1 in varchar2 default null,
    p2 in varchar2 default null,
    p3 in varchar2 default null,
    p4 in varchar2 default null,
    p5 in varchar2 default null,
    p6 in varchar2 default null,
    p7 in varchar2 default null,
    p8 in varchar2 default null,
    p9 in varchar2 default null,
    p_show_to_user in boolean default true
) 

Adds a warning to the warning stack, given domain, ID, and context.

Call this procedure to add a warning to the warning stack, given the domain, ID, and context.

Notes:

- Because any specific warning may be produced in multiple places in the executing code, each warning is identified in its unique context, which includes both package and method names, as: [package].[function], for example: wwpro_api_provider.show.
- When other warnings exist, push the Oracle error onto the stack. The WWV name space is predefined with the warning message: oracle. generic(11230), and with one parameter, which is passed as sqlerrm.
- Warnings are stacked on the name of the method that experienced the warning, for example: wwpro_api_provider.show.

Example:

    declare
          l_warning_table wwerr_api_error.error_table;
    begin
          wwerr_api_error.add_warning
          (
                p_domain  => wwerr_api_error.WWV,
                p_id      => 36000,
                p_context => 'example.test',
                p1        => 'test_warning'
          );
          l_warning_table := wwerr_api_error.get_warnings;
    end;
 

Parameters:

p_domain - the short name of the product in which the warning occurred

p_id - the ID number of the warning

p_context - the name of the function in which the warning occurred

p1 - first passed-in value for the resulting display message

p2 - second passed-in value for the resulting display message

p3 - third passed-in value for the resulting display message

p4 - fourth passed-in value for the resulting display message

p5 - fifth passed-in value for the resulting display message

p6 - sixth passed-in value for the resulting display message

p7 - seventh passed-in value for the resulting display message

p8 - eighth passed-in value for the resulting display message

p9 - nineth passed-in value for the resulting display message

p_show_to_user - should this warning message be shown to the user?

Since:

Oracle Portal 9.0.2.6

clear

procedure clear

Clears the error stack.

Call this procedure to delete all records in the error stack.

Example:

    wwerr_api_err.clear;
 

Since:

Oracle Portal 3.0.6.6.5

clear_warning

procedure clear_warning

Clears the warning stack.

Call this procedure to delete all records in the warning stack.

Example:

    wwerr_api_err.clear_warning;
 

Since:

Oracle Portal 9.0.2.6

get_count

function get_count
return number

Reports the number of entries in the current error stack.

Example:

    declare
        l_err_cnt number
    begin
        l_err_cnt := wwerr_api_error.get_count;
    end;
 

Returns:

this functions returns a number indicating how many entries are in the error stack

Since:

Oracle9iAS Portal 9.0.2

get_errors

function get_errors
return error_table

Returns a list of the entries in the error stack.

Call this function to return the error stack records in a table. Error handling routines can use this information to take specific corrective action or to provide their own UI.

Example:

    declare
         l_error_table wwerr_api_error.error_table;
    begin
        wwerr_api_error.add
        (
             p_domain     => wwerr_api_error.DOMAIN_WWC,
             p_sub_domain => 'err',
             p_name       => 'oracle_generic',
             p_context    => 'example.test',
             p1           => 'test_error'
        );
        l_error_table := wwerr_api_error.get_errors;
    end;
 

Returns:

a list of the entries in the error stack

Since:

Oracle Portal 3.0.6.6.5

get_text_stack

function get_text_stack(
    p_sep in varchar2 default owa . nl_char
) return varchar2

Reports the current error stack as varchar2.

Call this function to return the current error stack in a string.

Example:

    wwerr_api_error.get_text_stack;
 

Parameters:

p_sep - the delimiter used between fields in an error stack record. Note that a delimiter is a character, such as a comma or string, that is used to separate or to mark the start and end of column items of data in a database, or some other type of file or data container.

Returns:

this functions returns a string containing all the error messages currently in the error stack. The list includes: exception message, context, domain, and product or provider name. Note that the exception context is presented as: [package].[function], as in wwnls.add_string.

Since:

Oracle9iAS Portal 9.0.2

get_text_warning_stack

function get_text_warning_stack(
    p_sep in varchar2 default owa . nl_char
) return varchar2

Reports the current warning stack as varchar2.

Call this function to return the current warning stack in a string.

Example:

    wwerr_api_error.get_text_warning_stack;
 

Parameters:

p_sep - the delimiter used between fields in a warning stack record. Note that a delimiter is a character, such as a comma or string, that is used to separate or to mark the start and end of column items of data in a database, or some other type of file or data container.

Returns:

this functions returns the warning messages in a string

Since:

Oracle9iAS Portal 9.0.2

get_top

function get_top
return error_record

Returns the uppermost entry of the error stack.

Call this function to return the uppermost entry in the error stack. Error handling routines can use this information to take specific corrective action or to provide their own UI, such as placing the error on a status line.

Example:

    l_error_rec wwerr_api_error.error_record;
    l_error_rec := wwerr_api_error.get_top;
 

Returns:

the topmost error on the error stack

Since:

Oracle Portal 3.0.6.6.5

get_warning_count

function get_warning_count
return number

Reports the number of entries in the current warning stack.

Example:

    declare
        l_wrn_cnt number
    begin
        l_wrn_cnt := wwerr_api_error.get_warning_count;
    end;
 

Returns:

this functions returns a number indicating how many entries are in the warning stack

Since:

Oracle9iAS Portal 9.0.2

get_warning_top

function get_warning_top
return error_record

Returns the uppermost entry of the warning stack.

Call this function to return the uppermost entry in the warning stack. Error handling routines can use this information to take specific corrective action or to provide their own UI, such as placing the warning on a status line.

Example:

    l_warning_rec wwerr_api_error.error_record;
    l_warning_rec := wwerr_api_error.get_warning_top;
 

Returns:

the topmost warning on the warning stack

Since:

Oracle Portal 9.0.2.6

get_warnings

function get_warnings
return error_table

Returns a list of the entries in the warning stack.

Call this function to return the warning stack records in a table. Error handling routines can use this information to take specific corrective action or to provide their own UI.

Example:

    declare
        l_warnings wwerr_api_error.error_table;
    begin
        l_warnings := wwerr_api_error.get_warnings;
    end;
 

Returns:

a list of the entries in the warning stack

Since:

Oracle Portal 9.0.2.6

is_empty

function is_empty
return boolean

Determines if the error stack is empty.

Example:

    wwerr_api_error.is_empty;
 

Returns:

This function returns TRUE if the error stack is empty, FALSE otherwise.

Since:

Oracle Portal 3.0.6.6.5

is_warning_empty

function is_warning_empty
return boolean

Determines if the warning stack is empty.

Example:

    wwerr_api_error.is_warning_empty;
 

Returns:

returns TRUE if the warning stack is empty, FALSE otherwise

Since:

Oracle Portal 9.0.2.6