Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE | DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE

## 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

Type Summary
`error_record` A record structure containing details of an error record. | `record`
`error_table` A table of error records. | `table`

Constant Summary
`DOMAIN_WOR` Reserved domain name. | `varchar2(12)`
`DOMAIN_WWC` Reserved domain name. | `varchar2(12)`
`DOMAIN_WWF` Reserved domain name. | `varchar2(12)`
`DOMAIN_WWS` Reserved domain name. | `varchar2(12)`
`DOMAIN_WWU` Reserved domain name. | `varchar2(12)`
`DOMAIN_WWV` Reserved domain name. | `varchar2(12)`
`SUBDOMAIN_POB` Reserved subdomain name. | `varchar2(12)`
`SUBDOMAIN_WEBDAV` Reserved subdomain name. | `varchar2(12)`

Function/Procedure Summary
`add` Adds an error to the error stack, given domain, sub-domain, name and context. | ``
`add` Adds an error to the error stack, given domain, ID, and context. | ``
`add_warning` Adds a warning to the warning stack, given domain, sub-domain, name and context. | ``
`add_warning` Adds a warning to the warning stack, given domain, ID, and context. | ``
`clear` Clears the error stack. | ``
`clear_warning` Clears the warning stack. | ``
`get_count` Reports the number of entries in the current error stack. | `number`
`get_errors` Returns a list of the entries in the error stack. | `error_table`
`get_text_stack` Reports the current error stack as varchar2. | `varchar2`
`get_text_warning_stack` Reports the current warning stack as varchar2. | `varchar2`
`get_top` Returns the uppermost entry of the error stack. | `error_record`
`get_warning_count` Reports the number of entries in the current warning stack. | `number`
`get_warning_top` Returns the uppermost entry of the warning stack. | `error_record`
`get_warnings` Returns a list of the entries in the warning stack. | `error_table`
`is_empty` Determines if the error stack is empty. | `boolean`
`is_warning_empty` Determines if the warning stack is empty. | `boolean`

Type Detail

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

Constant Detail

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

Function/Procedure Detail

### 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

Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE | DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE