SQL 受信アダプタの使用法

永続値の初期化

EnsLib.SQL.InboundAdapterOpens in a new tab には、ビジネス・サービスの再起動と再起動間に保存される永続値を初期化する以下のメソッドが用意されています。

ClassMethod InitializePersistentValue
            (pConfigName As %String,
             pPersistentValueName As %String = "%LastKey",
             pNewValue As %String)
             As %String

このメソッドを使用して、アダプタに関連付けられている名前と値のペアを初期化し、その名前をクエリのパラメータに使用します。このメソッドでは、指定された永続的な名前と値のペアの現在の値を調べます。値が現時点で NULL の場合は、それを pNewValue と等しくなるように設定します。

デフォルトでは、名前を省略すると、メソッドにより、永続的な名前と値のペア &%LastKey が初期化されます。%LastKey には、アダプタによって最後に処理された行の IDKey 値が含まれています。

場合によっては、代わりに InitializeLastKeyValue() が必要な場合があります。このメソッドは、アダプタの一時プロパティ %LastKey を初期化します。このプロパティは、ビジネス・サービスが起動するたびにリセットされます。関連する SetPersistentValue() メソッドおよび GetPersistentValue() メソッドについては、EnsLib.SQL.InboundAdapterOpens in a new tab のクラスに関するドキュメントも参照してください。

例

&%LastKey 永続値を初期化するには、ビジネス・サービスの OnInit() メソッドをカスタマイズして以下を含めます。

Method OnInit() As %Status
{
   #; initialize persistent last key value
   Do ..Adapter.InitializePersistentValue(..%ConfigName,,0)
   Quit $$$OK
}

&TopSales 永続値を初期化するには、ビジネス・サービスの OnInit() メソッドをカスタマイズして以下を含めます。

Method OnInit() As %Status
{
   #; must initialize so the query can do a numeric comparison
   Do ..Adapter.InitializePersistentValue(..%ConfigName,"TopSales",0)
   Quit $$$OK
}

クエリの指定

受信 SQL アダプタで使用される基本のクエリを指定するには、Query 設定を使用します。この設定では、基本のクエリ文字列を指定します。置き換え可能なパラメータの表現には、標準の SQL ? を使用できます。これは、個別の設定で指定します (次の項目を参照)。以下の例を検討します。

SELECT * FROM Customer

SELECT p1,p2,p3 FROM Customer WHERE updatetimestamp > ?

SELECT * FROM Sample.Person WHERE ID > ?

SELECT * FROM Sample.Person WHERE Age > ?, PostalCode = ?

パラメータの指定

Parameters 設定では、クエリ文字列内の置き換え可能なパラメータを指定します。この設定は、以下のような、パラメータ値指定子のカンマ区切りリストになります。

value,value,value,...

指定する値ごとに、10 や Gotham City などの定数リテラル値を使用したり、以下のいずれかを参照したりできます。

• アダプタのプロパティを使用できます。Parameters 設定でアダプタのプロパティを参照するには、プロパティの名前を使って参照するだけです。

• 関連するビジネス・サービスのプロパティを参照できます。構文 $property_name を使用します。

  Parameters 設定でパラメータ名がドル記号 ($) で始まる場合は、その名前はサービス・クラスのプロパティであると見なされます。

  例えば、タイムスタンプを入れるために、LastTS という名前のプロパティをビジネス・サービス・クラスに追加できます。Parameters 設定では、プロパティの値を $LastTS として参照します。

• &%LastKey などの特別な永続値を参照できます。この値には、アダプタによって最後に処理された行の IDKey 値が含まれています。

  Parameters 設定でパラメータ名がアンパサンド (&) で始まる場合は、その名前は特別な永続値であると見なされます。

  Note:

  これらの値の初期化については、“アダプタの初期化” を参照してください。

利用可能なツール

EnsLib.SQL.InboundAdapterOpens in a new tab には、処理済みの行を追跡するための以下のツールが用意されています。

• KeyFieldName 設定を指定すると、アダプタがどの行を処理したかを示すデータが Caché グローバルに追加されます。この設定は、時間が経過しても再利用されない値を含むフィールドを参照します。このフィールドは、クエリから返される結果セットに含まれている必要があります。アダプタは、そのフィールドのデータを使用して、行が以前に処理されたことがあるかどうかを評価します。

• アダプタには、永続値、&%LastKey が用意されています。この永続値には、最後に処理された行の Key Field Name の値が含まれています。この特別な永続値は、ビジネス・サービスの再起動時に保存されます。

• アダプタの一時プロパティ %LastKey には、アダプタが最後に処理した行の KeyFieldName の値が格納されます。このアダプタ・プロパティは、関連するビジネス・サービスを再起動するたびに作成されます。

最後とその前の 2 つのオプションが実際に役立つのは、新規行ごとに単調に値が増加するフィールドを KeyFieldName が参照している場合に限られます。“アダプタの初期化” も参照してください。

行を再処理しないための実用的な方法

同じデータを再処理しないようにするための実用的な方法は、以下の 3 つです。

• アダプタの KeyFieldName 設定を使用します。この設定を指定すると、時間が経過しても再利用されない値を含むフィールドが参照されます。このフィールドは、クエリから返される結果セットに含まれている必要があります。KeyFieldName を指定すると、アダプタはこのフィールド内のデータに基づいて、行が既に処理されているかどうかを評価します。SELECT に擬似フィールド %ID を指定し、このフィールドを KeyFieldName として指定する場合は、KeyFieldName を ID として指定する必要があり、% (パーセント記号) は省略する必要があることに注意してください。

  デフォルトは ID です。

  例えば、Query を以下のように指定できます。

  SELECT ID,Name,Done from Sample.Person
  

  

  そして、KeyFieldName を以下のように指定します。

  ID
  

  

  Ensemble では、ポーリング・サイクルごとに多数の行が選択されますが、選択された行のうち新規のものは少ないので、この方法は非効率的です。

• 特別な永続値 &%LastKey (またはアダプタの一時プロパティ %LastKey) を参照するクエリ・パラメータを使用するクエリを使用します。例えば、Query を以下のように指定できます。

  SELECT ID,Name,Done from Sample.Person WHERE ID>?
  

  

  次に、Parameters を以下のように指定できます。

  &%LastKey
  

  

  “アダプタの初期化” も参照してください。

• クエリの実行後、ソース・データを削除または更新し、クエリから同じ行が返されないようにします。そのためには、DeleteQuery 設定を使用します。デフォルトでは、EnsLib.SQL.InboundAdapterOpens in a new tab は、メイン・クエリ (Query 設定) の実行後、メイン・クエリで返された行ごとに 1 回 DeleteQuery を実行します。

  このクエリには、置換可能なパラメータ (疑問符) が厳密に 1 つのみ含まれている必要があります。アダプタはこのパラメータを KeyFieldName が指定する値に置換します。

  このクエリでは、ソース・データを削除または更新し、アダプタのメイン・クエリによって同じ行が選択されないようにすることができます。

  例えば、Query を以下のように指定できます。

  SELECT ID,Name,Done from Sample.Person WHERE Done=0
  

  

  そして、DeleteQuery を以下のように指定します。

  UPDATE Sample.Person SET Done=1 WHERE ID=?
  

  

例 1 ： KeyFieldName の使用

最も単純な例では、Customer テーブルから行を選択します。このテーブルには主キーである CustomerID フィールドがあります。これは、新しいレコードごとに自動的に増加する整数です。重要なのは新規行のみであるため、このフィールドを KeyFieldName として使用します。プロダクションでは、アダプタに以下の設定を使用します。

プロダクションが起動すると、アダプタが Customer テーブルのすべての行を自動的に選択して処理します。1 つの行を処理するたびに、Ensemble イベント・ログにエントリを追加します。このエントリは以下のようなテキストになります。

Processing row '216'

ここで、'216' は、処理される行の CustomerID です。

プロダクションの起動後、各ポーリング・サイクル時に、アダプタはすべての行を選択しますが、CustomerID フィールドに新しい値が含まれている行のみを処理します。

例 2 ： &%LastKey または %LastKey の使用

この例は、上記のバリエーションです。この場合は、メイン・クエリが行のサブセットを選択します。すべての行を選択するよりも効率的です。

各ポーリング・サイクル時に、アダプタは &%LastKey の値を決定し、その値を SQL に渡します。

“アダプタの初期化” も参照してください。

Note:

一連の行をアダプタが選択するときには、KeyFieldName で指定された順序で各行が処理されることもあれば、されないこともあります。例えば、あるポーリング・サイクルで、CustomerID が 101、102、103、104、および 105 の行を選択するとします。ただし、顧客 103 を (顧客 105 の代わりに) 最後に処理するとします。このポーリング・サイクル終了後の &%LastKey の値は 103 です。したがって、次のサイクルでは、アダプタは再処理はしないものの、顧客 104 および 105 を再度選択します(この方が、上記例のようにすべての行を再度選択するよりも効率的です)。強制的にアダプタが特定の順序で行を処理するようにするには、以下のように、クエリ内に ORDER BY 節を追加します。

SELECT * FROM Customer WHERE ID>? ORDER BY CustomerID

この場合、&%LastKey の値は常に最大の CustomerID に設定されるので、複数回選択される行はなくなります。

例 3 ： DeleteQuery の使用

この例では、Customer テーブルに Done というフィールドがあります。このフィールドには、アダプタが所定の行を以前に選択したことがあるかどうかを記録できます。

上記の例と同様、この例では、各行が選択されるのは 1 度だけです。

例 4 ： 複合キーの使用

テーブルの複数のフィールドを主キーとしてまとめて処理する必要がある場合が多々あります。例えば、Month フィールドや Year フィールドを含む統計テーブルがあるとします。クエリでは、アダプタの一意のキーとして月と年を一緒に処理する必要があるとします。このような場合は、関連するフィールドを連結し、AS 節を使用して複合フィールドの別名を提供するクエリを使用します。

例えば、SQL*Server の場合、以下のように始まるクエリを使用できます。

SELECT Stats, Year||Month as ID ...

アダプタ内の結果セットに ID というフィールドが含まれるようになります。このフィールドを KeyFieldName に使用できます。

例 5 ： KeyFieldName の指定なし

場合によっては、KeyFieldName を使用したくないこともあります。KeyFieldName が NULL の場合、アダプタは行を区別せず、エラーがある行や既に正常に処理された行をスキップしません。

以下に例を示します。

ビジネス・サービスは以下のとおりです。

Class Test.SQL.TopSalesService Extends Ens.BusinessService
{

Parameter ADAPTER = "EnsLib.SQL.InboundAdapter";

Parameter REQUESTCLASSES As %String = "EnsLib.SQL.Snapshot";

Method OnInit() As %Status
{
   #; must initialize so the query can do a numeric comparison
   Do ..Adapter.InitializePersistentValue(..%ConfigName,"TopSales",0)
   Quit $$$OK
}

Method OnProcessInput(pInput As EnsLib.SQL.Snapshot,
   Output pOutput As Ens.Response) As %Status
{
   Kill pOutput Set pOutput=$$$NULLOREF

   for j=1:1:pInput.ColCount {
   }
   for i=1:1:pInput.RowCount {
      for j=1:1:pInput.ColCount {
      }
   }
   Set tSales=pInput.Get("TicketsSold")
   Set:tSales>$G($$$EnsStaticAppData(
..%ConfigName,"adapter.sqlparam","TopSales")) ^("TopSales")=tSales
   Quit $$$OK
}

}