21.1 Event-Driven Publishing API

Event-Driven Publishing APIは、データベース内のイベントに応じるプロシージャの開発に必要な、基本的なファンクションを提供するPL/SQLパッケージです。イベント・ドリブン・ジョブは、HTTPプロトコルを使用して送信されます。サーバーは、すべてのコールに一意のjob_identレコードを割り当てます。これは、ジョブのステータスを追跡する際に役立ちます。

21.1.1 APIの要素

このAPIは、いくつかの重要な要素から構成されています。

SRWパッケージには、ジョブの送信、ジョブ・ステータスのチェック、ジョブの取消しおよびパラメータ・リストの操作に関連するすべてのファンクションとプロシージャが含まれています。
SRW_ParamListは、パラメータ・リストを定義します。パラメータ・リストは、ジョブを送信する際に値を渡すための主要な手段です。パラメータ・リストは、ジョブ送信ごとに必要となります。このリストには、複数の重要なパラメータが含まれています。
SRW_ParamList_Objectは、アドバンスト・キューイングなどの機能に必要です。これらの機能では、パラメータ・リストをデータベースに格納して、メッセージとともに渡せるようにする必要があります。

APIの各要素については、この後の項で詳しく説明します。

このAPIは、Oracle Reports Services SecurityおよびOracle Portalとともにインストールされますが、どちらも必須ではありません。Oracle Portalを使用しないデータベースにもAPIをインストールできるように、インストール・スクリプトが別途用意されています。

srwAPIins.sqlは、Event-Driven Publishing APIをインストールします。
srwAPIgrant.sqlは、APIへのアクセス権限を付与します。このスクリプトは、APIへのアクセス権限を付与するユーザーごとに実行します。全員がアクセス可能である場合は、このスクリプトを1回実行し、PUBLICにアクセス権限を付与できます。
srwAPIdrop.sqlは、APIを削除します。

21.1.2 パラメータ・リストの作成と操作

パラメータ・リストは、SRW_PARAMLISTタイプの PL/SQL変数です。このタイプの変数は、SRW_PARAMETERタイプの255個の要素からなる配列です。この要素自体は、2つの属性NAMEおよびVALUEから構成されます。APIには、パラメータ・リストを操作するための次のプロシージャが用意されています。

Add_Parameter
Remove_Parameter
Clear_Parameter_List

21.1.2.1 Add_Parameter

パラメータ・リストを初めて使用するときは、そのパラメータ・リストを初期化してからパラメータを追加する必要があります。例:

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を使用します。

21.1.2.2 Remove_Parameter

REMOVE_PARAMETERは、パラメータ・リストからパラメータを削除するために使用します。このプロシージャを呼び出し、対象となるパラメータ・リストとともに削除するパラメータの名前を渡します。

例:

DECLARE

myPlist SRW_PARAMLIST;

BEGIN

myPlist := SRW_PARAMLIST(SRW_PARAMETER('',''));
srw.add_parameter(myPlist,'myParameter','myValue');
srw.remove_parameter(myPlist,'myParameter');

END;

21.1.2.3 Clear_Parameter_List

リストからすべてのパラメータを削除するには、CLEAR_PARAMETER_LISTを使用します。例:

DECLARE

myPlist SRW_PARAMLIST;

BEGIN

myPlist := SRW_PARAMLIST(SRW_PARAMETER('',''));
srw.add_parameter(myPlist,'myParameter','myValue');
srw.clear_parameter_list(myPlist);

END;

これによって、リストからすべてのパラメータが削除されます。

21.1.3 パラメータの名前と値での非ASCII文字の使用

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が使用されます。

21.1.4 ジョブの送信

パラメータ・リストには、ジョブの送信に不可欠なすべてのパラメータが含まれている必要があります。ジョブ・タイプによって、リストに必要なパラメータが決まり、Reports Serverでリクエストを処理できるようになります。

リスト内のパラメータは、ブラウザからOracle Reports Servlet (rwservlet)にジョブを送信する際に指定するパラメータと同じです。この場合、ジョブがレポートであるときは、少なくとも次のパラメータが必要です(それ以上指定してもかまいません)。

GATEWAYにより、リクエストの処理に使用するOracle Reports Servlet (rwservlet)へのURLを渡します。
SERVERにより、Oracle Reports Servlet (rwservlet)とともに使用されるReports Serverを特定します。
REPORTは、実行するレポート・ファイルを特定します。
USERIDは、レポートを実行するユーザーの名前とIDを特定します。
AUTHIDは、セキュリティで保護されたサーバーにアクセスする場合の認証情報を提供します。

各リクエストからは、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.GatewayURL
MyIdent.ServerName
MyIdent.JobID
MyIdent.AuthID

これらのパラメータは、SRW.REPORT_STATUSファンクションが、送信されたジョブのステータス情報を取得するために必要となります。

21.1.5 ステータスの確認

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;

返されたステータス・レコードを使用して、ジョブのステータスに関する情報をフェッチできます。

21.1.6 サーバーのステータス・レコードの使用

ステータス・レコードには、ジョブに関する処理情報が含まれています。これには、サーバー・キュー内の情報(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レコードをそのプロシージャに渡します。このプロシージャでは、オプションのパラメータ・リストによって、必要な追加のパラメータを渡すことができます。