SQL 送信アダプタの使用法
この章では、Ensemble SQL 送信アダプタ (EnsLib.SQL.OutboundAdapterOpens in a new tab) のデフォルトの動作、およびプロダクションでのこのアダプタの使用法について説明します。以下のトピックについて説明します。
デフォルトの動作
プロダクション内で、送信アダプタは、ユーザが作成および構成するビジネス・オペレーションに関連付けられます。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。
SQL 送信アダプタ (EnsLib.SQL.OutboundAdapterOpens in a new tab) には、接続先となるデータ・ソースとそのデータ・ソースに必要なログイン詳細の指定に使用する設定が用意されています。また、以下のような一般的な SQL アクティビティを実行するメソッドも用意されています。
-
クエリの実行
-
ストアド・プロシージャの実行
-
挿入、更新、および削除の実行
アダプタを使用するビジネス・オペレーションの作成
EnsLib.SQL.OutBoundAdapter を使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、それをプロダクションに追加して、構成します。
存在しなければ、適切なメッセージ・クラスを作成する必要もあります。"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。
ビジネス・オペレーション・クラスの基本要件を以下に列挙します。
-
ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。
-
ADAPTER パラメータは EnsLib.SQL.OutboundAdapterOpens in a new tab である必要があります。
-
INVOCATION パラメータは、使用する呼び出しスタイルを指定する必要があります。以下のいずれかを使用します。
-
Queue は、メッセージが 1 つのバックグラウンド・ジョブ内で作成され、元のジョブが解放された段階でキューに配置されます。その後、メッセージが処理された段階で、別のバックグラウンド・ジョブがそのタスクに割り当てられます。これは最も一般的な設定です。
-
InProc は、メッセージが、作成されたジョブと同じジョブで生成、送信、および配信されることを意味します。このジョブは、メッセージが対象に配信されるまで送信者のプールに解放されません。これは特殊なケースのみに該当します。
-
-
クラスでは、少なくとも 1 つのエントリを含むメッセージ・マップを定義します。メッセージ・マップは、以下の構造を持つ XData ブロック・エントリです。
XData MessageMap { <MapItems> <MapItem MessageType="messageclass"> <Method>methodname</Method> </MapItem> ... </MapItems> }
-
クラスでは、メッセージ・マップ内で名前が付けられたすべてのメソッドを定義します。これらのメソッドは、メッセージ・ハンドラと呼ばれます。通常、これらのメソッドは、ビジネス・オペレーションの Adapter プロパティのプロパティおよびメソッドを参照します。
-
その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・オペレーション・クラスの定義” を参照してください。
以下の例は、必要となる一般的な構造を示しています。
Class ESQL.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.SQL.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method SampleCall(pRequest As Ens.Request, Output pResponse As Ens.Response) As %Status
{
Quit $$$ERROR($$$NotImplemented)
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="Ens.Request">
<Method>SampleCall</Method>
</MapItem>
</MapItems>
}
}
スタジオには、上記のようなスタブの作成に使用できるウィザードが用意されています。このウィザードにアクセスするには、[ファイル] メニューで [新規作成] をクリックし、[プロダクション] タブをクリックします。ビジネス・オペレーションの作成を選択し、関連付ける送信アダプタとして EnsLib.SQL.OutboundAdapterOpens in a new tab を選択します。
SQL オペレーションを実行するメソッドの作成
EnsLib.SQL.OutboundAdapterOpens in a new tab で使用するビジネス・オペレーション・クラスを作成する場合の最大のタスクは、通常、メッセージ・ハンドラ、つまり、各種 SQL オペレーションを実行するメソッドの記述です。通常、これらのメソッドは、ビジネス・オペレーションの Adapter プロパティのプロパティおよびメソッドを参照します。以下に例を示します。
set tSC = ..Adapter.ExecuteUpdate(.numrows,sql)
メソッドは以下のようになります。
/// Insert into NewCustomer table
Method Insert(pReq As ESQL.request, Output pResp As ESQL.response1) As %Status
{
kill pResp
set pResp=$$$NULLOREF
set sql="insert into NewCustomer (Name,SSN,City,SourceID) values (?,?,?,?)"
//perform the Insert
set tSC = ..Adapter.ExecuteUpdate
(.nrows,sql,pReq.Name,pReq.SSN,pReq.City,pReq.CustomerID)
//create the response message
set pResp=##class(ESQL.response1).%New()
set pResp.AffectedRows=nrows
if 'tSC write " failed ",tSC quit tSC
quit 1
}
これらのメソッドを作成するには、EnsLib.SQL.OutboundAdapterOpens in a new tab クラスのメソッドとプロパティに精通している必要があります。これらのツールについては、“SQL のアダプタ・メソッドの作成” の章で詳しく説明します。
1 件のメッセージによる複数の SQL 文の処理
アダプタ構成は、ビジネス・オペレーションで受信したメッセージ 1 件について 1 つの SQL 文を実行する単純なケースを扱うように設計されています。指定した 1 つのメッセージで複数の SQL 文をビジネス・オペレーションで実行するには、OnMessage() メソッドで次のような形式を使用します。
OnMessage(..)
{
Set tStayConn=..Adapter.StayConnected
Set ..Adapter.StayConnected=-1
//... your ..Adapter SQL Operations here...
Set ..Adapter.StayConnected=tStayConn
If 'tStayConn&&..Adapter.Connected Do ..Adapter.Disconnect()
Quit tSC
}
ビジネス・オペレーションの追加と構成
ビジネス・オペレーションを Ensemble プロダクションに追加するには、管理ポータルを使用して以下の操作を行います。
-
カスタム・ビジネス・オペレーション・クラスのインスタンスを Ensemble プロダクションに追加します。
-
ビジネス・オペレーションを有効化します。
-
特定の外部データ・ソースと通信を行うためのアダプタを構成します。具体的には、以下を行います。
-
アダプタの接続先であるデータ・ソースの指定
-
プロダクションのその他の一般的な実行時設定の使用
-
-
プロダクションを実行します。
データ・ソース名の指定
EnsLib.SQL.OutboundAdapterOpens in a new tab には、接続先のデータ・ソースの指定に使用する実行時設定が用意されています。ビジネス・オペレーションを構成する場合は、この設定に適切な初期値を設定する必要があります。
このデータ・ソース名は、接続先である外部データ・ソースを指定します。Ensemble では、定義済みの Caché SQL ゲートウェイ接続、JDBC URL、およびオペレーティング・システムで構成した ODBC DSN の 3 種類の形式を自動的に区別します。
この名前が管理ポータルの システム, 構成, オブジェクト/SQLゲートウェイ設定 ページから構成された JDBC または ODBC 接続名に一致すると、その仕様のパラメータが Ensemble で使用されます。エントリが構成済みの接続名ではなく、そこにコロン (:) が使用されていると、その名前は JDBC URL と見なされます。それ以外の場合は ODBC DSN と見なされます。
このデータ・ソースがパスワードによって保護されている場合は、ユーザ名とパスワードを含む Ensemble 認証情報を作成します。その後、これらの資格情報の ID に一致する Credentials 設定を設定します。詳細は、“その他の実行時設定の指定” を参照してください。
JDBC データ・ソースを使用している場合は、以下の設定も適用されます。
このオペレーションで使用する Java ゲートウェイ・サーバを制御する Java ゲートウェイ・サービスの構成名です。
この設定は、JDBC と接続中の SQL ゲートウェイ接続を使用している場合でも、すべての JDBC データ・ソースで必要です。JDBC 接続が機能するには、タイプが EnsLib.JavaGateway.ServiceOpens in a new tab のビジネス・サービスが存在する必要があります。SQL アダプタに対して、この構成項目の名前を指定する必要があります。その構成済み設定を使用して、このアダプタが管理する JVM に接続します。
JDBC ドライバ・クラス名です。
名前付き SQL ゲートウェイ接続を DSN として使用する場合、この値の指定は任意です。ただし、値を指定すると、名前付き JDBC SQL ゲートウェイ接続のプロパティよりも優先して適用されます。
JDBC ドライバ・クラス名のクラスパスです (Java ゲートウェイ・サービスで構成したクラスパス以外にも必要な場合)。
必要に応じて設定できる一連の SQL 接続属性オプション。ODBC の場合は、これらの形式は次のとおりです。
attr:val,attr:val
例 : AutoCommit:1
JDBC の場合は、これらの形式は次のとおりです。
attr=val;attr=val
例 : TransactionIsolationLevel=TRANSACTION_READ_COMMITTED
名前付き JDBC SQL ゲートウェイ接続を DSN として使用する場合、この値の指定は任意です。ただし、値を指定すると、名前付き JDBC SQL ゲートウェイ接続のプロパティよりも優先して適用されます。
その他の実行時設定の指定
EnsLib.SQL.OutboundAdapterOpens in a new tab には、以下のその他の実行時設定が用意されています。
指定された DSN への接続を承認できる Ensemble 資格情報の ID を識別します。Ensemble 認証情報の作成方法は、"Ensemble プロダクションの構成" を参照してください。
SQL 文の送信や ODBC ドライバ設定の変更などのコマンドを実行している間、接続を開いたままにするかどうかを指定します。
-
この設定が 0 の場合は、コマンドを 1 つ実行終了するたびにアダプタの接続が直ちに切断されます。
-
この値が正の場合、その値はコマンド完了後のアイドル時間 (秒) になります。アダプタは、このアイドル・タイムの経過後に接続を切断します。
-
この設定が -1 の場合、アダプタは起動時に自動接続し、接続したままになります。
このドキュメントの “トランザクションの管理” での説明にあるようにデータベース・トランザクションを管理している場合は、StayConnected を 0 に設定しないでください。
ここに記載されていない設定については、"Ensemble プロダクションの構成" を参照してください。