Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

スナップショットの使用法

EnsLib.SQL.SnapshotOpens in a new tab クラスは、さまざま方法で作成および設定する静的オブジェクトを表します。このクラスには、データ調査用のメソッドが用意されています。結果セットよりもこの静的オブジェクトの方が、多くのメソッドを利用できます。

この章では、EnsLib.SQL.Shapshot クラスを使用する方法について説明します。以下について説明します。

スナップショットの作成

SQL 受信アダプタを使用する場合は、デフォルトで、スナップショット・オブジェクトをビジネス・サービス内で自動的に受け取ります。クエリの各行について、アダプタは、ビジネス・サービスの ProcessInput() メソッドを呼び出す際にスナップショット・オブジェクトを作成して引数として送信します。以前説明したように、デフォルトでは、このスナップショットには 1 つの行しか含まれていません。

別の方法でも、スナップショットを作成し、設定できます。これらの方法の一部については、前の章で説明されていますが、この章で新たに説明するものもあります。

ライブ接続からのスナップショットの作成

ほとんどの場合、データ・ソースへライブ接続することになります。具体的には、SQL アダプタ (EnsLib.SQL.InboundAdapterOpens in a new tab または EnsLib.SQL.OutboundAdapterOpens in a new tab) から始めます。アダプタ内で、DSN に接続します。次に、以下のいずれかを実行します。

  • アダプタの ExecuteProcedure() メソッドまたは ExecuteProcedureParmArray() メソッドを使用します。これらの各メソッドは、スナップショットとして結果を返します。

    これらのメソッドについては、前の章で説明しています。

  • 結果セットを作成し (前の章を参照)、結果セットの GetSnapshot() メソッドを使用します。このメソッドには、以下のシグニチャがあります。

    method GetSnapshot(ByRef pSnap As EnsLib.SQL.Snapshot,
   pFetchAll As %Boolean = 0) returns %Status

    最初の引数に参照渡しでスナップショット・オブジェクトを返します。既存のスナップショット・オブジェクトをメソッドに渡すと、メソッドはそのオブジェクトの FirstRow および MaxRowsToGet プロパティを使用してスナップショットに配置する行を決定します。スナップショット・オブジェクトを渡さない場合は、メソッドはデフォルト値を使用します。

静的データからのスナップショットの作成

DSN に接続せずに、静的データからスナップショットを作成することもできます。そのためには、以下のいずれかのテクニックを使用します。

  • CreateFromFile()、CreateFromStream() または CreateFromResultSet クラス・メソッドを使用します。

  • スナップショットの新しいインスタンスを (%New() クラス・メソッドを使用して) 作成し、次に ImportFile()、ImportFromStream() メソッドまたは ImportFromResultSet() メソッドを使用します。

以下のリストに、これらのメソッドの詳細を示します。これらのメソッドはすべて、EnsLib.SQL.Shapshot クラスに属しています。

CreateFromFile()
classmethod CreateFromFile(pFilename As %String,
   pRowSeparator As %String,
   pColumnSeparator As %String,
   pColumnWidths As %String,
   pLineComment As %String,
   pStripPadChars As %String,
   pColNamesRow As %Integer,
   pFirstRow As %Integer,
   pMaxRowsToGet As %Integer,
   Output pStatus As %Status) as Snapshot

新しいスナップショット・オブジェクトを作成し、テーブル形式のテキスト・ファイルからのデータと共にロードします。引数は以下のとおりです。

  • pFilename は、インポートするファイルの名前を指定します。これは、唯一の必須引数です。

  • pRowSeparator は、以下のいずれかです。

    • ある行と次の行とを区切る文字。デフォルトは、改行文字です。

    • マイナス記号が頭に付いた数字。文字数単位での行の長さを示します。

  • pColumnSeparator は、以下のいずれかです。

    • ある列と次の列とを区切る文字。デフォルトの文字はありません。

    • 数字 0。これは、列が pColumnWidths 引数で決定されることを意味します。次の引数を参照してください。

    • マイナス記号が頭に付いた数字。各行でスキップする先頭の文字数を示します。この場合は、列は、pColumnWidths 引数で決定されます。次の引数を参照してください。

  • pColumnWidths は、以下のいずれかです。

    • ファイルのフィールドが位置で指定される場合は、列幅 (文字数) のカンマ区切りリスト。

    • ファイルで列区切りを使用している場合は、列数。

  • pLineComment は、その文字列以降の行の残りの部分が無視されることになる文字列を指定します。指定された行でこの文字列が検出されると、スナップショットは、行の残りの部分を解析して列に入れることはしません。

  • pStripPadChars は、フィールドの最初と最後から切り取る文字を意味します。デフォルトは、空白文字です。

  • pColNamesRow は、列名を含む行がある場合に、その行のインデックスを指定します。

  • pFirstRow は、スナップショットに入れる (ファイルからの) 最初の行のインデックスを指定します。

  • pMaxRowsToGet は、スナップショットに入れる最大行数を指定します。

  • pStatus は、スナップショットを作成する際にメソッドが返すステータスです。

CreateFromStream()
classmethod CreateFromStream(pIOStream As %IO.I.CharacterStream,
   pRowSeparator As %String,
   pColumnSeparator As %String,
   pColumnWidths As %String,
   pLineComment As %String,
   pStripPadChars As %String,
   pColNamesRow As %Integer,
   pFirstRow As %Integer,
   pMaxRowsToGet As %Integer,
   Output pStatus As %Status) as Snapshot

新しいスナップショット・オブジェクトを作成し、テーブル形式のストリームからのデータと共にロードします。CreateFromFile() に関するコメントを参照してください。

CreateFromResultSet
classmethod CreateFromResultSet(pRS As %ResultSet, 
  pLegacyMode As %Integer = 1, 
  pODBCColumnType As %Boolean = 0, 
  pFirstRow As %Integer, 
  pMaxRowsToGet As %Integer, 
  Output pStatus As %Status) as Snapshot

新しいスナップショット・オブジェクトを作成し、結果セットからのデータと共にロードします。CreateFromFile() および ImportFromResultSet に関するコメントを参照してください。

ImportFile()
 method ImportFile(pFilename As %String,
   pRowSeparator As %String = $C(10),
   pColumnSeparator As %String = $C(9),
   pColumnWidths As %String = "",
   pLineComment As %String = "",
   pStripPadChars As %String = " "_$C(9),
   pColNamesRow As %Integer = 0) as %Status

テーブル形式のテキスト・ファイルからデータをインポートします。CreateFromFile() に関するコメントを参照してください。

ImportFromStream()
method ImportFromStream(pIOStream As %IO.I.CharacterStream,
   pRowSeparator As %String = $C(10),
   pColumnSeparator As %String = $C(9),
   pColumnWidths As %String = "",
   pLineComment As %String = "",
   pStripPadChars As %String = " "_$C(9),
   pColNamesRow As %Integer = 0) as %Status

ここで、pIOStream はインポートするストリームです。CreateFromFile() に関するコメントを参照してください。

ImportFromResultSet()
method ImportFromResultSet(pRS As %ResultSet, 
   pLegacyMode As %Integer = 1, 
   pODBCColumnType As %Boolean = 0) as %Status

結果セットをスナップショット・インスタンスにインポートします。引数は以下のとおりです。

  • pRS は EnsLib.SQL.GatewayResultSetOpens in a new tab、%Library.ResultSetOpens in a new tab、%ResultSet.*、%Library.IResultSetOpens in a new tab のインスタンス、または、%SQL.StatementResultOpens in a new tab や %SQL.ISelectResult (%SQL.IResult) などの、%SQL パッケージ内の結果セットです。

  • pLegacyMode は、メタ・データの検索方法を指定します。この引数が 0 の場合、Ensemble では最初に %GetMetadata の使用が試行されます。これにより、従来の結果セット・クラスに対して別のソースのメタデータが検出されます。デフォルトは 1 です。これは、以前の動作を維持しながら、%SQL.* および %ResultSet.* をサポートします。

  • pODBCColumnType は、ColumnType の設定方法を制御します。pODBCColumnType が 1 の場合、ColumnType テキストは ODBC タイプの列タイプ・テキストに設定され、clientType には設定されません。

例

以下のコンテンツを持つファイルを検討します。

col1,col2,col3
value A1,value A2,value A3
value B1,         value B2           ,value B3

以下のコードは、このファイルを読み取り、これを使用してスナップショットを作成し、簡単なコメントをターミナルに書き込みます。使用される引数がファイル名および列区切りのみであることに注意してください。

 set filename="c:/demo.txt"
 set snap=##class(EnsLib.SQL.Snapshot).%New()
 do snap.ImportFile(filename,,",")
 d show
 quit


show
 w "number of rows in snapshot=",snap.RowCount,!
 while snap.Next()
  {
      w "current row=",snap.%CurrentRow,!
      w "data in first column=",snap.GetData(1),!
      w "data in second column=",snap.GetData(2),!
      w "data in third column=",snap.GetData(3),!
      }
 quit

このルーチンからの出力は、以下のとおりです。

number of rows in snapshot=3
current row=1
data in first column=col1
data in second column=col2
data in third column=col3
current row=2
data in first column=value A1
data in second column=value A2
data in third column=value A3
current row=3
data in first column=value B1
data in second column=value B2
data in third column=value B3

デフォルトでは、改行が行区切りとして使用されます。また、デフォルトで、先頭および末尾の空白が各フィールドから削除されることにも注意してください。

スナップショットの手動作成

以下のように、スナップショットを手動で作成することもできます。

  1. スナップショットの新しいインスタンスを作成します (%New() クラス・メソッドを使用)。

  2. SetColNames() メソッド、SetColSizes() メソッド、および SetColTypes() メソッドを使用して列の名前、サイズ、およびタイプを指定します。

  3. AddRow() メソッドを使用してデータ行を追加します。

以下のリストに、これらのメソッドの詳細を示します。これらのメソッドはすべて、EnsLib.SQL.Shapshot クラスに属しています。

AddRow()
method AddRow(pCol...) returns %Status

指定されたデータを含む行を追加します。引数リストは、フィールド別の行データです。例えば、以下の例では、スナップショットに行を追加します。この場合の列名はそれぞれ、ID、Name、および DOB です。

 set sc=snapshot.SetColNames("1023","Smith,Bob","06-06-1986")
SetColNames()
 method SetColNames(pColName...) returns %Status

引数で指定されている順に、列名を設定します。例えば、以下の例では、列名をそれぞれ、ID、Name、および DOB と設定します。

 set sc=snapshot.SetColNames("ID","Name","DOB")
SetColSizes()
method SetColSizes(pColSize...) returns %Status

引数で指定されている順に、列のサイズ (文字数単位での幅) を設定します。

SetColTypes()
method SetColTypes(pColType...) returns %Status

引数で指定されている順に、列のタイプを設定します。

Note:

SQL タイプ名は、データベースのベンダごとに異なることに注意してください。使用中のデータベースに適したタイプ名を使用します。SetColTypes() メソッドは、タイプ名のチェックは実行しません。

スナップショットの基本情報の取得

スナップショットの以下のプロパティは、基本情報を提供します。

  • %CurrentRow プロパティは、現在行を示す整数です。

  • AtEnd プロパティは、現在行が最終行である場合は真に、最終行でない場合は偽になります。

  • ColCount プロパティは、スナップショットの列数を示します。

  • RowCount プロパティは、スナップショットの行数を示します。このプロパティは、コメント文字列で始まらない行がある場合に、その行のみをカウントします。コメントを含むスナップショットを作成するには、CreateFromFile() メソッドと関連メソッドを使用し、pLineComment 引数に値を指定します。コメント文字列で始まらないものの、後の位置にコメント文字列が含まれる場合に、行がカウントされます。

スナップショットのナビゲート

スナップショットは、データ行で構成されます。行をナビゲートするには、以下のメソッドを使用できます。

Next()
method Next(ByRef pSC As %Status) returns %Integer

カーソルを次の行に進めます。カーソルがスナップショットの末尾にある場合は、0 を返します。

Rewind()
method Rewind() returns %Status

カーソルをスナップショットの先頭行に戻します。

スナップショットの現在行の調査

スナップショットの現在行を調べるには、以下のメソッドを使用します。

Get()
method Get(pName As %String, pRow=..%CurrentRow) returns %String

指定の行 (デフォルトでは現在行) で名前 pName を持つ列の値を返します。

GetData()
method GetData(pColumn As %Integer, pRow=..%CurrentRow) returns %String

指定の行 (デフォルトでは現在行) でpColumn で指定されている位置にある列の値を返します。

GetColumnName()
method GetColumnName(pColumn As %Integer = 0)

pColumn で指定されている位置にある列の名前を返します。

GetColumnId()
method GetColumnId(pName As %String) returns %Integer

名前 pName を持つ列の順序位置を返します。不慣れなテーブルを使用する際に、このメソッドは役に立ちます。

GetColumnSize()
method GetColumnSize(pColumn As %Integer = 0)

pColumn で指定されている位置にあるデータベース・フィールドのサイズ (文字数で表した幅) を返します。

GetColumnType()
method GetColumnType(pColumn As %Integer = 0)

pColumn で指定されている位置にある列のタイプを返します。

Note:

SQL タイプ名は、データベースのベンダごとに異なります。

スナップショットのリセット

既存のスナップショット・オブジェクトがある場合は、そのオブジェクトからデータや定義を消去できます。そのためには、Clean() メソッドを使用します。このメソッドはステータスを返します。これは、スナップショットを破棄し、%New() を使用して新たなスナップショットを作成するよりも、若干効率的です。


Previous section結果セットの使用法
FeedbackOpens in a new tab