| Oracle® Application Express APIリファレンス リリース4.2 for Oracle Database 12c B71340-03 |
|
 前 |
 次 |
APEX_ERRORパッケージには、インタフェース宣言と、エラー処理ファンクションのためのいくつかのユーティリティ・ファンクションが用意されており、Application Expressアプリケーションでエラーを発生させるプロシージャおよびファンクションが含まれています。
トピック:
このセクションでは、APEX_ERRORパッケージで使用するデータ型および定数について説明します。
次の定数は、t_errorおよびt_error_result型のAPIパラメータp_display_locationおよび属性display_locationに使用されます。
c_inline_with_field constant varchar2(40):='INLINE_WITH_FIELD'; c_inline_with_field_and_notif constant varchar2(40):='INLINE_WITH_FIELD_AND_NOTIFICATION'; c_inline_in_notification constant varchar2(40):='INLINE_IN_NOTIFICATION'; c_on_error_page constant varchar2(40):='ON_ERROR_PAGE';
次の定数は、t_error型でAPIパラメータassociated_typeに使用されます。
c_ass_type_page_item constant varchar2(30):='PAGE_ITEM'; c_ass_type_region constant varchar2(30):='REGION'; c_ass_type_region_column constant varchar2(30):='REGION_COLUMN';
次の型はエラー処理ファンクションに渡され、また関連するエラー情報のすべてを含んでいます。
type t_error is record (
message varchar2(32767), /* Displayed error message */
additional_info varchar2(32767), /* Only used for display_location ON_ERROR_PAGE to display additional error information */
display_location varchar2(40), /* Use constants "used for display_location" below */
association_type varchar2(40), /* Use constants "used for asociation_type" below */
page_item_name varchar2(255), /* Associated page item name */
region_id number, /* Associated tabular form region id of the primary application */
column_alias varchar2(255), /* Associated tabular form column alias */
row_num pls_integer, /* Associated tabular form row */
is_internal_error boolean, /* Set to TRUE if it's a critical error raised by the Application Express engine, like an invalid SQL/PLSQL statements, ... Internal Errors are always displayed on the Error Page */
apex_error_code varchar2(255), /* Contains the system message code if it's an error raised by Application Express */
ora_sqlcode number, /* SQLCODE on exception stack which triggered the error, NULL if the error was not raised by an ORA error */
ora_sqlerrm varchar2(32767), /* SQLERRM which triggered the error, NULL if the error was not raised by an ORA error */
error_backtrace varchar2(32767), /* Output of dbms_utility.format_error_backtrace or dbms_utility.format_call_stack */
component wwv_flow.t_component /* Component which has been processed when the error occurred */
);
次の型は、エラー処理ファンクションの結果の型として使用されます。
type t_error_result is record (
message varchar2(32767), /* Displayed error message */
additional_info varchar2(32767), /* Only used for display_location ON_ERROR_PAGE to display additional error information */
display_location varchar2(40), /* Use constants "used for display_location" below */
page_item_name varchar2(255), /* Associated page item name */
column_alias varchar2(255) /* Associated tabular form column alias */
);
create or replace function apex_error_handling_example (
p_error in apex_error.t_error )
return apex_error.t_error_result
is
l_result apex_error.t_error_result;
l_reference_id number;
l_constraint_name varchar2(255);
begin
l_result := apex_error.init_error_result (
p_error => p_error );
-- If it's an internal error raised by APEX, like an invalid statement or
-- code which cannot be executed, the error text might contain security sensitive
-- information. To avoid this security problem rewrite the error to
-- a generic error message and log the original error message for further
-- investigation by the help desk.
if p_error.is_internal_error then
-- Access Denied errors raised by application or page authorization should
-- still show up with the original error message
if p_error.apex_error_code <> 'APEX.AUTHORIZATION.ACCESS_DENIED' and p_error.apex_error_code not like 'APEX.SESSION_STATE.%' then
-- log error for example with an autonomous transaction and return
-- l_reference_id as reference#
-- l_reference_id := log_error (
-- p_error => p_error );
--
-- Change the message to the generic error message which is not exposed
-- any sensitive information.
l_result.message := 'An unexpected internal application error has occurred. '||
'Please get in contact with XXX and provide '||
'reference# '||to_char(l_reference_id, '999G999G999G990')||
' for further investigation.';
l_result.additional_info := null;
end if;
else
-- Always show the error as inline error
-- Note: If you have created manual tabular forms (using the package
-- apex_item/htmldb_item in the SQL statement) you should still
-- use "On error page" on that pages to avoid loosing entered data
l_result.display_location := case
when l_result.display_location = apex_error.c_on_error_page then apex_error.c_inline_in_notification
else l_result.display_location
end;
-- If it's a constraint violation like
--
-- -) ORA-00001: unique constraint violated
-- -) ORA-02091: transaction rolled back (-> can hide a deferred constraint)
-- -) ORA-02290: check constraint violated
-- -) ORA-02291: integrity constraint violated - parent key not found
-- -) ORA-02292: integrity constraint violated - child record found
--
-- try to get a friendly error message from our constraint lookup configuration.
-- If the constraint in our lookup table is not found, fallback to
-- the original ORA error message.
if p_error.ora_sqlcode in (-1, -2091, -2290, -2291, -2292) then
l_constraint_name := apex_error.extract_constraint_name (
p_error => p_error );
begin
select message
into l_result.message
from constraint_lookup
where constraint_name = l_constraint_name;
exception when no_data_found then null; -- not every constraint has to be in our lookup table
end;
end if;
-- If an ORA error has been raised, for example a raise_application_error(-20xxx, '...')
-- in a table trigger or in a PL/SQL package called by a process and the
-- error has not been found in the lookup table, then display
-- the actual error text and not the full error stack with all the ORA error numbers.
if p_error.ora_sqlcode is not null and l_result.message = p_error.message then
l_result.message := apex_error.get_first_ora_error_text (
p_error => p_error );
end if;
-- If no associated page item/tabular form column has been set, use
-- apex_error.auto_set_associated_item to automatically guess the affected
-- error field by examine the ORA error for constraint names or column names.
if l_result.page_item_name is null and l_result.column_alias is null then
apex_error.auto_set_associated_item (
p_error => p_error,
p_error_result => l_result );
end if;
end if;
return l_result;
end apex_error_handling_example;
構文
APEX_ERROR.ADD_ERROR (
p_message in varchar2,
p_additional_info in varchar2 default null,
p_display_location in varchar2 );
パラメータ
表8-1に、ADD_ERRORプロシージャのシグネチャ1で使用可能なパラメータを示します。
表8-1 ADD_ERRORプロシージャのシグネチャ1のパラメータ
| パラメータ | 説明 |
|---|---|
|
|
表示されるエラー・メッセージ |
|
|
エラーがエラー・ページに表示される場合に必要なその他のエラー情報。 |
|
|
エラー・メッセージの表示位置を指定します。定数 |
例
この例では、エラー・スタックにカスタム・エラー・メッセージを追加する方法を示しています。エラー・メッセージは通知にインラインで表示されます。この例は、検証または処理の際に使用できます。
apex_error.add_error (
p_message => 'This custom account is not active!',
p_display_location => apex_error.c_inline_in_notification );
このプロシージャは、通知にインラインでページ・アイテムのエラーを表示するために使用されるエラー・スタックにエラー・メッセージを追加します。検証または処理時にコールして、1つ以上のエラーをエラー・スタックに追加することができます。
|
注意: このプロシージャは、Application Expressアプリケーションが最後の検証または処理を行う前にコールする必要があります。そのようにしないと、apex_error.c_on_error_pageの表示位置が指定されている場合を除いて、エラーは無視されます。 |
構文
APEX_ERROR.ADD_ERROR (
p_message in varchar2,
p_additional_info in varchar2 default null,
p_display_location in varchar2,
p_page_item_name in varchar2);
パラメータ
表8-2に、ADD_ERRORプロシージャのシグネチャ2で使用可能なパラメータを示します。
表8-2 ADD_ERRORプロシージャのシグネチャ2のパラメータ
| パラメータ | 説明 |
|---|---|
|
|
表示されるエラー・メッセージ |
|
|
エラーがエラー・ページに表示される場合に必要なその他のエラー情報。 |
|
|
エラー・メッセージの表示位置を指定します。定数 |
|
|
|
例
この例では、エラー・スタックにカスタム・エラー・メッセージを追加する方法を示しています。P5_CUSTOMER_IDアイテムがページ上で強調表示されます。エラー・メッセージは通知にインラインで表示されます。この例は、検証または処理の際に使用できます。
apex_error.add_error (
p_message => 'Invalid Customer ID!',
p_display_location => apex_error.c_inline_with_field_and_notif,
p_page_item_name => 'P5_CUSTOMER_ID');
このプロシージャは、テキストを共有コンポーネントで定義したとおりに表示するために使用するエラー・スタックにエラー・メッセージを追加します。このエラー・メッセージはすべての表示位置に表示できます。検証または処理時にコールして、1つ以上のエラーをエラー・スタックに追加することができます。
|
注意: このプロシージャは、Application Expressアプリケーションが最後の検証または処理を行う前にコールする必要があります。そのようにしないと、apex_error.c_on_error_pageの表示位置が指定されている場合を除いて、エラーは無視されます。 |
構文
APEX_ERROR.ADD_ERROR (
p_error_code in varchar2,
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_escape_placeholders in boolean default true,
p_additional_info in varchar2 default null,
p_display_location in varchar2,
p_page_item_name in varchar2 );
パラメータ
表8-3に、ADD_ERRORプロシージャのシグネチャ3で使用可能なパラメータを示します。
表8-3 ADD_ERRORプロシージャのシグネチャ3のパラメータ
| パラメータ | 説明 |
|---|---|
|
|
共有コンポーネントのテキスト・メッセージの名前。 |
|
|
エラーがエラー・ページに表示される場合に必要なその他のエラー情報。 |
|
|
テキスト・メッセージに定義された%0から%9までのプレースホルダの値。 |
|
|
|
|
|
エラー・メッセージの表示位置を指定します。 |
|
|
|
例
この例では、テキスト・メッセージに格納されているカスタム・エラー・メッセージをエラー・スタックに追加する方法を示しています。P5_CUSTOMER_IDアイテムがページ上で強調表示されます。エラー・メッセージは通知にインラインで表示されます。この例は、検証または処理の際に使用できます。
apex_error.add_error (
p_error_code => 'INVALID_CUSTOMER_ID',
p0 => l_customer_id,
p_display_location => apex_error.c_inline_with_field_and_notif,
p_page_item_name => 'P5_CUSTOMER_ID' );
構文
APEX_ERROR.ADD_ERROR (
p_message in varchar2,
p_additional_info in varchar2 default null,
p_display_location in varchar2,
p_region_id in number,
p_column_alias in varchar2 default null,
p_row_num in number );
パラメータ
表8-4に、ADD_ERRORプロシージャのシグネチャ4で使用可能なパラメータを示します。
表8-4 ADD_ERRORプロシージャのシグネチャ4のパラメータ
| パラメータ | 説明 |
|---|---|
|
|
表示されるエラー・メッセージ |
|
|
エラーがエラー・ページに表示される場合に必要なその他のエラー情報。 |
|
|
エラー・メッセージの表示位置を指定します。定数 |
|
|
現在ページの表形式フォーム・リージョンのID。IDは、ビュー |
|
|
|
|
|
エラーが発生した表形式フォームの行数。 |
例
この例では、列CUSTOMER_IDが強調表示されている、表形式フォームのカスタム・エラー・メッセージをエラー・スタックに追加する方法を示しています。エラー・メッセージは通知にインラインで表示されます。この例は、検証または処理の際に使用できます。
apex_error.add_error (
p_message => 'Invalid Customer ID!',
p_display_location => apex_error.c_inline_with_field_and_notif,
p_region_id => l_region_id,
p_column_alias => 'CUSTOMER_ID',
p_row_num => l_row_num );
このプロシージャは、テキストを共有コンポーネントで定義したとおりに表示するために使用される、表形式のフォームのエラー・スタックにエラー・メッセージを追加します。このエラー・メッセージはすべての表示位置に表示できます。検証または処理時にコールして、1つ以上のエラーをエラー・スタックに追加することができます。
|
注意: このプロシージャは、Application Expressアプリケーションが最後の検証または処理を行う前にコールする必要があります。そのようにしないと、apex_error.c_on_error_pageの表示位置が指定されている場合を除いて、エラーは無視されます。 |
構文
APEX_ERROR.ADD_ERROR (
p_error_code in varchar2,
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_escape_placeholders in boolean default true,
p_additional_info in varchar2 default null,
p_display_location in varchar2,
p_region_id in number,
p_column_alias in varchar2 default null,
p_row_num in number );
パラメータ
表8-5に、ADD_ERRORプロシージャのシグネチャ5で使用可能なパラメータを示します。
表8-5 ADD_ERRORプロシージャのシグネチャ5のパラメータ
| パラメータ | 説明 |
|---|---|
|
|
共有コンポーネントのテキスト・メッセージの名前。 |
|
|
テキスト・メッセージに定義された%0から%9までのプレースホルダの値。 |
|
|
|
|
|
エラーがエラー・ページに表示される場合に必要なその他のエラー情報。 |
|
|
エラー・メッセージの表示位置を指定します。 |
|
|
現在ページの表形式フォーム・リージョンのID。IDは、ビュー |
|
|
|
|
|
エラーが発生した表形式フォームの行数。 |
例
この例では、テキスト・メッセージに格納されているカスタム・エラー・メッセージをエラー・スタックに追加する方法を示しています。表形式フォームのCUSTOMER_ID列が強調表示されます。エラー・メッセージは通知にインラインで表示されます。この例は、検証または処理の際に使用できます。
apex_error.add_error (
p_error_code => 'INVALID_CUSTOMER_ID',
p0 => l_customer_id,
p_display_location => apex_error.c_inline_with_field_and_notif,
p_region_id => l_region_id,
p_column_alias => 'CUSTOMER_ID',
p_row_num => l_row_num );
このプロシージャは関連付けられたページ・アイテムまたは表形式フォームの列を、p_error.ora_sqlerrmで指定されている制約に基づいて自動的に設定します。このプロシージャの機能は次のとおりです。
schema.constraintパターンを検索して、制約を特定します。
P、U、RおよびCタイプの制約のみをサポートします。
タイプCの制約の場合(制約のチェック)、プロシージャは式を解析して制約式で使用されているそれらの列を特定します。
これらの列を使用すると、プロシージャはその列に基づいて、最初に表示されるページ・アイテムまたは表形式フォームの列を取得し、それを関連するp_error_result.page_item_nameまたはp_error_result.column_aliasとして設定します。
ページ・アイテムまたは表形式フォームの列が見つかった場合、p_error_result.display_locationがapex_error.c_inline_with_field_and_notifに設定されます。
構文
APEX_ERROR.AUTO_SET_ASSOCIATED_ITEM (
p_error_result in out nocopy t_error_result,
p_error in t_error );
パラメータ
表8-10に、AUTO_SET_ASSOCIATED_ITEMプロシージャで使用可能なパラメータを示します。
表8-6 AUTO_SET_ASSOCIATED_ITEMプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
エラー処理ファンクションの結果の変数。 |
|
|
エラー処理ファンクションの |
例
このプロシージャの使用方法の例については、「エラー処理ファンクションの例」を参照してください。
このファンクションは、p_error.ora_sqlerrmに含まれる制約名を抽出します。制約は、パターンschema.constraintと一致する必要があります。
構文
APEX_ERROR.EXTRACT_CONSTRAINT_NAME (
p_error in t_error,
p_include_schema in boolean default false )
return varchar2;
パラメータ
表8-7に、EXTRACT_CONSTRAINT_NAMEファンクションで使用可能なパラメータを示します。
表8-7 EXTRACT_CONSTRAINT_NAMEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
エラー処理ファンクションの |
|
|
|
例
このプロシージャの使用方法の例については、「エラー処理ファンクションの例」を参照してください。
このファンクションは、アイテムがページのエラーに関連付けられている場合は特に、アイテムのスクリーンショット・リーダー・ユーザビリティを向上させる上で、プラグイン開発者にとって役に立ちます。このファンクションは、メイン・フォーム要素が出力される、アイテムのレンダリング時にコールされます。戻されるWAI-ARIA属性は次のとおりです。
aria-invalid="true" - ページ・アイテムの現在の値が無効であることを示します。ユーザーがページ・アイテムにフォーカスすると、スクリーン・リーダーによって「無効なエントリ」が通知されます。
aria-describedby="[page_item_name]_error" - この属性値は、アイテムの関連付けられたエラー・メッセージを含む<div>タグのIDと組み合わせて、ユーザーがページ・アイテムにフォーカスすると、スクリーン・リーダーによって実際のエラーが通知されるようにできます。
|
注意: これらの属性は、スクリーン・リーダーのユーザビリティを向上させるだけなので、属性は、現在のセッションがスクリーン・リーダー・モードで実行されている場合にしか戻されません。 |
構文
function get_aria_error_attributes (
p_item_name in varchar2 )
return varchar2;
パラメータ
表8-9に、GET_ARIA_ERROR_ATTRIBUTESファンクションで使用可能なパラメータを示します。
表8-8 GET_ARIA_ERROR_ATTRIBUTESファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ページ・アイテムの名前。この値は、1番目のパラメータとしてすべてのアイテム・プラグインのレンダリング・ファンクション・コールバックに渡される、 |
例
次の例に、アイテム・プラグインのレンダリング・ファンクション・コールバックの処理時に、SELECT要素のレンダリングでこのファンクションを使用する方法について示します。このファンクションは、ページ・アイテムで、それに関連付けられたエラーが発生した場合や、ユーザーがスクリーン・リーダー・モードで実行している場合に、追加の属性を戻します。
...
l_name := apex_plugin.get_input_name_for_page_item(false);
sys.htp.prn('<select name="'||l_name||'" id="'||p_item.name||'" '||
apex_error.get_aria_error_attributes(p_item.name)||'>');
...
このファンクションは、p_error.ora_sqlerrmに格納されている最初のエラー・メッセージのテキストを戻します。p_error_ora_sqlerrmに値が含まれていない場合、NULLが戻されます。
構文
APEX_ERROR.GET_FIRST_ORA_ERROR_TEXT (
p_error in t_error,
p_include_error_no in boolean default false )
return varchar2;
パラメータ
表8-9に、GET_FIRST_ORA_TEXTファンクションで使用可能なパラメータを示します。
表8-9 GET_FIRST_ORA_TEXTファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
エラー処理ファンクションの |
|
|
|
例
このプロシージャの使用方法の例については、「エラー処理ファンクションの例」を参照してください。
構文
APEX_ERROR.INIT_ERROR_RESULT (
p_error in t_error)
return t_error_result;
パラメータ
表8-10に、INIT_ERROR_RESULTファンクションで使用可能なパラメータを示します。
例
このファンクションの使用方法の例については、「エラー処理ファンクションの例」を参照してください。
