Oracle® Fusion Middleware Oracle Reports ServicesレポートWeb公開ガイド 11g リリース 1 (11.1.1) B61375-02 |
|
![]() 前 |
![]() 次 |
Event-Driven Publishing APIは、データベース内のイベントに応じるプロシージャの開発に必要な、基本的なファンクションを提供するPL/SQLパッケージです。イベント・ドリブン・ジョブは、HTTPプロトコルを使用して送信されます。サーバーは、すべてのコールに一意のjob_ident
レコードを割り当てます。これは、ジョブのステータスを追跡する際に役立ちます。
このAPIは、いくつかの重要な要素から構成されています。
SRWパッケージには、ジョブの送信、ジョブ・ステータスのチェック、ジョブの取消しおよびパラメータ・リストの操作に関連するすべてのファンクションとプロシージャが含まれています。
SRW_ParamListは、パラメータ・リストを定義します。パラメータ・リストは、ジョブを送信する際に値を渡すための主要な手段です。パラメータ・リストは、ジョブ送信ごとに必要となります。このリストには、複数の重要なパラメータが含まれています。
SRW_ParamList_Objectは、アドバンスト・キューイングなどの機能に必要です。これらの機能では、パラメータ・リストをデータベースに格納して、メッセージとともに渡せるようにする必要があります。
APIの各要素については、この後の項で詳しく説明します。
このAPIは、Oracle Reports Services SecurityおよびOracle Portalとともにインストールされますが、どちらも必須ではありません。Oracle Portalを使用しないデータベースにもAPIをインストールできるように、インストール・スクリプトが別途用意されています。
パラメータ・リストは、SRW_PARAMLIST
タイプのPL/SQL変数です。このタイプの変数は、SRW_PARAMETER
タイプの255個の要素からなる配列です。この要素自体は、2つの属性NAME
およびVALUE
から構成されます。APIには、パラメータ・リストを操作するための次のプロシージャが用意されています。
パラメータ・リストを初めて使用するときは、そのパラメータ・リストを初期化してからパラメータを追加する必要があります。例:
DECLARE
myPlist SRW_PARAMLIST;
BEGIN
myPlist := SRW_PARAMLIST(SRW_PARAMETER('','')); srw.add_parameter(myPlist,'myParameter','myValue');
END;
パラメータの属性(NAME
とVALUE
)はどちらもVARCHAR2
タイプで、その長さはNAME
が80文字、VALUEが255文字に制限されています。
ADD_PARAMETER
ファンクションには、オプションでMODE
という4番目の属性を指定できます。MODE
は、同じ名前のパラメータがすでに存在する場合に、そのパラメータを上書きするか、またはエラーが発生するかを決定します。重複する名前があった場合にエラーが発生するように指定するには、定数CHECK_FOR_EXISTANCE
を使用します。これは、MODE
属性のデフォルト値です。重複する名前があった場合にパラメータを上書きするように指定するには、定数OVERWRITE_IF_EXISTS
を使用します。
REMOVE_PARAMETER
は、パラメータ・リストからパラメータを削除するために使用します。このプロシージャを呼び出し、対象となるパラメータ・リストとともに削除するパラメータの名前を渡します。
例:
DECLARE
myPlist SRW_PARAMLIST;
BEGIN
myPlist := SRW_PARAMLIST(SRW_PARAMETER('','')); srw.add_parameter(myPlist,'myParameter','myValue'); srw.remove_parameter(myPlist,'myParameter');
END;
Event-Driven Publishing APIの使用時に、ユーザー・パラメータの名前と値に非ASCII文字を使用するには、パラメータDEFAULTCHARSET
を、有効なキャラクタ・セット名に値を設定して、パラメータ・リストに追加する必要があります。このキャラクタ・セット名は、データベースのNLS_CHARACTERSET
(JA16SJIS
など)、またはIANA定義キャラクタ・セット名(WINDOWS-31J
など)に指定できます。また、rwservlet.properties
ファイルに指定されているdefaultcharsetパラメータとDEFAULTCHARSET
パラメータの値が一致していることを確認する必要があります。ユーザー・パラメータの名前と値においてASCIIでない文字のエンコードに、DEFAULTCHARSET
で指定されたキャラクタ・セットをOracle Reports Servicesで使用されます。このため、パラメータの名前と値においてASCIIでない文字のあるレポートにEvent-Driven Publishing APIを使用できます。
注意: パラメータ・リストにDEFAULTCHARSET パラメータを追加しないと、Oracle Reports Servicesでは、ユーザー・パラメータの名前と値のエンコードに、データベースのNLS_CHARACTERSET が使用されます。 |
パラメータ・リストには、ジョブの送信に不可欠なすべてのパラメータが含まれている必要があります。ジョブ・タイプによって、リストに必要なパラメータが決まり、Reports Serverでリクエストを処理できるようになります。
リスト内のパラメータは、ブラウザからOracle Reports Servlet(rwservlet
)にジョブを送信する際に指定するパラメータと同じです。この場合、ジョブがレポートであるときは、少なくとも次のパラメータが必要です(それ以上指定してもかまいません)。
GATEWAY
により、リクエストの処理に使用するOracle Reports Servlet(rwservlet
)へのURLを渡します。
SERVER
により、Oracle Reports Servlet(rwservlet
)とともに使用されるReports Serverを特定します。
各リクエストからは、job_identレコードが返されます。このレコードには、ジョブを一意に識別するための情報が含まれています。この情報は、SRW.JOB_IDENT
タイプの変数に格納されます。この情報はPACKAGE-TYPE
であり、SRW.JOB_IDENT
として参照する必要があることに注意してください。一方、パラメータ・リストはOBJECT-TYPE
であり、SRW_PARAMLIST
として参照する必要があります。
例:
DECLARE
myPlist SRW_PARAMLIST; myIdent SRW.Job_Ident;
BEGIN
myPlist := SRW_PARAMLIST(SRW_PARAMETER('','')); srw.add_parameter(myPlist,'GATEWAY','http://…'); srw.add_parameter(myPlist,'SERVER','mySVR'); srw.add_parameter(myPlist,'REPORT','myReport.RDF'); srw.add_parameter(myPlist,'USERID','me/secret'); myIdent := srw.run_report(myPlist);
END;
APIのRUN_REPORT
メソッドは、必要不可欠なすべての情報を含んだパラメータ・リストを入力として(ADD_PARAMETER
を使用)、リクエストを作成して送信するとともに、job_identレコードを返します。
返されたjob_ident
レコード(MyIdent)には、次のパラメータが含まれます。
これらのパラメータは、SRW.REPORT_STATUS
ファンクションが、送信されたジョブのステータス情報を取得するために必要となります。
Event-Driven Publishing APIにより、Reports Serverとの双方向通信を実現します。ユーザーは、サーバーにジョブを送信するとともに、SRW.REPORT_STATUS
ファンクションを使用して、このジョブのステータスをサーバーに問い合せることができます。
このファンクションからは、SRW.STATUS_RECORD
タイプのレコードが返されます。このレコードには、rwservlet
のWebコマンドshowjobs
を実行したときにジョブ・ステータス表示に示される情報と同じ情報が含まれています。
例:
DECLARE
myPlist SRW_PARAMLIST; myIdent SRW.Job_Ident; myStatus SRW.Status_Record;
BEGIN
myPlist := SRW_PARAMLIST(SRW_PARAMETER('','')); srw.add_parameter(myPlist,'GATEWAY','http://…'); srw.add_parameter(myPlist,'SERVER','mySVR'); srw.add_parameter(myPlist,'REPORT','MyReport.RDF'); srw.add_parameter(myPlist,'USERID','me/secret'); myIdent := srw.run_report(myPlist); myStatus := srw.report_status(myIdent);
END;
返されたステータス・レコードを使用して、ジョブのステータスに関する情報をフェッチできます。
ステータス・レコードには、ジョブに関する処理情報が含まれています。これには、サーバー・キュー内の情報(showjobs
で表示)と同じ情報が含まれます。さらに、終了したジョブに対して生成されたファイルに関する情報、およびスケジュールされたジョブの系統に関する情報も含まれます。
ステータス・レコードで最も重要な情報は、ランタイム・エラーとその原因をチェックするために使用される、現行ジョブ・ステータスとステータス・テキストです。
タイミング情報を使用して、完了までの予測時間を超過した場合にジョブが取り消されるかどうかを確認できます。
ステータス・レコードの用途の1つに、ジョブの取消しがあります。Event-Driven Publishing APIでは、サーバーに送信されたジョブを取り消す方法を提供しています。この方法は、許可されている実行時間を超過したジョブを削除する場合、または単にスケジュールされているジョブを取り消す場合に便利です。
ジョブを取り消すには、次のプロシージャを使用します。
DECLARE
myPlist SRW_PARAMLIST; myIdent SRW.JOB_IDENT; myStatus SRW.STATUS_RECORD;
BEGIN
myPlist := SRW_PARAMLIST(SRW_PARAMETER('','')); SRW.ADD_PARAMETER(myPlist,'GATEWAY','http://…'); SRW.ADD_PARAMETER(myPlist,'SERVER','mySVR'); SRW.ADD_PARAMETER(myPlist,'REPORT','myReport.RDF'); SRW.ADD_PARAMETER(myPlist,'USERID','me/secret'); myIdent := SRW.RUN_REPORT(myPlist); myStatus := SRW.REPORT_STATUS(myIdent); if myStatus.StatusCode != srw.RUNNING then SRW.CANCEL_REPORT(myIdent);
END;
この例からわかるように、レポートを取り消す場合は、CANCEL_REPORT
プロシージャ(SRW.CANCEL_REPORT
)をコールし、取り消すジョブのjob_ident
レコードをそのプロシージャに渡します。このプロシージャでは、オプションのパラメータ・リストによって、必要な追加のパラメータを渡すことができます。