adm_ai_error

Centralized error handling for the AI Pack.

The mechanism lives in adm_error: this package holds only the codes, messages and exceptions the AI Pack raises, and hands the work to adm_error.raise_error. One formatter, one logger, one place a customer looks up a code.

adm_ai_error.raise_error(
  p_error_code => adm_ai_error.c_err_collection_not_found
, p_scope      => l_scope
, p0           => p_collection_id
);
-- raises: ORA-20600: RAG collection not found: 42

Everything adm_error documents applies here too: %0 .. %9 for substitutions, a doubled %% for a literal percent sign, and diagnostics in p_extra rather than in the message. adm_error’s predicates work on these codes as well:

exception
  when adm_ai_error.e_collection_not_found then ...

exception
  when others then
    if adm_error.is_not_found(sqlcode) then ...

Codes are allocated by category, not by domain

The base product’s blocks are grouped by domain with categories mixed inside, and adm_error maps each of those codes to its category one by one. It cannot do that for this package: adm_error ships in the base product, which installs and runs with the AI Pack absent, so it must not reference anything here.

So the AI Pack block is laid out the other way round - by category, in fixed sub-ranges that adm_error.get_category works out arithmetically:

-20600 .. -20609  NOT_FOUND
-20610 .. -20624  INVALID_INPUT
-20625 .. -20634  INVALID_STATE
-20635 .. -20644  EXTERNAL
-20645 .. -20649  INTERNAL
-20650 .. -20699  reserved, same layout when the blocks above fill up

A new code therefore goes in the sub-range for its category, never in the next free slot. Putting it anywhere else makes adm_error report the wrong category for it, and tests/test_adm_error.pkb pins the sub-range boundaries.

Functions and Procedures

raise_error

Log an error and raise it in one call, through adm_error.

Identical to adm_error.raise_error in every respect except that p_error_code is one of this package’s c_err_* constants.

Signature:

procedure raise_error (
  p_error_code in number,
  p_scope in varchar2 default null,
  p0 in varchar2 default null,
  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_message in varchar2 default null,
  p_extra in clob default null,
  p_log in boolean default true
);

Parameters:

Name	Direction	Type	Description
p_error_code	in	number	One of the c_err_* constants
p_scope	in	varchar2 default null	Where it happened, e.g. ‘adm_ai_rag_api.search_chunks’
p0	in	varchar2 default null	Substitution value for %0
p1	in	varchar2 default null	Substitution value for %1
p2	in	varchar2 default null	Substitution value for %2
p3	in	varchar2 default null	Substitution value for %3
p4	in	varchar2 default null	Substitution value for %4
p5	in	varchar2 default null	Substitution value for %5
p6	in	varchar2 default null	Substitution value for %6
p7	in	varchar2 default null	Substitution value for %7
p8	in	varchar2 default null	Substitution value for %8
p9	in	varchar2 default null	Substitution value for %9
p_message	in	varchar2 default null	Message template overriding the default for p_error_code
p_extra	in	clob default null	Diagnostics to log and not show: sqlerrm, a backtrace, a response body
p_log	in	boolean default true	Whether to log before raising

---

get_default_message

The default message template for an AI Pack error code.

Signature:

function get_default_message (
  p_error_code in number
) return varchar2;

Parameters:

Name	Direction	Type	Description
p_error_code	in	number	One of the c_err_* constants

Returns: varchar2 - The template, or null when the code does not belong to this package

---