Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

プログラムによる SQL ゲートウェイの使用法

Note:

このセクションでは、読者が ODBC API 呼び出しの使用経験が豊富であると想定しており、ODBC 関数の詳しい使用方法は説明しません。問題が発生した場合、InterSystems IRIS と ODBC の両方のログを有効化して SQL ゲートウェイを監視できます ("InterSystems ODBC ドライバ の使用法" の “ログと環境変数” の章を参照してください)。

標準 SQL ゲートウェイ・ウィザードで提供されないオプションが必要な場合、%Library.SQLGatewayConnectionOpens in a new tab クラスを使用して ObjectScript から ODBC 関数を呼び出すことができます。ダイナミック・クエリ (結果セットを取得する) を実行することも、低レベルの ODBC プログラミングを実行することもできます。この章で説明する項目は以下のとおりです。

この章の残りの部分では、%Library.SQLGatewayConnectionOpens in a new tab を、その略名である %SQLGatewayConnectionOpens in a new tab で参照します。

FetchSamples の例

以下に、接続を開いてクエリの準備と実行を行い結果のデータ・セットにアクセスする簡単な例を示します。Connect()Disconnect()ConnectionHandle、および sqlcode の詳細は、“%SQLGatewayConnection のクイック・リファレンス” のエントリを参照してください。サポートされている ODBC 関数およびそれらの関数を呼び出す %SQLGatewayConnectionOpens in a new tab メソッドのリストは、このクイック・リファレンスの “サポートされる ODBC 関数呼び出し” のセクションを参照してください。

ClassMethod FetchSamples
ClassMethod FetchSamples()
{
   #include %occInclude
   //Create new SQL Gateway connection object
   set gc=##class(%SQLGatewayConnection).%New()
   if gc=$$$NULLOREF quit $$$ERROR($$$GeneralError,"Cannot create %SQLGatewayConnection.")

   //Make connection to target DSN
   set pDSN="Cache Samples"
   set usr="_system"
   set pwd="SYS"
   set sc=gc.Connect(pDSN,usr,pwd,0)
   if $$$ISERR(sc) quit sc
   if gc.ConnectionHandle="" quit $$$ERROR($$$GeneralError,"Connection failed")

   set sc=gc.AllocateStatement(.hstmt)
   if $$$ISERR(sc) quit sc

   //Prepare statement for execution
   set pQuery= "select * from Sample.Person"
   set sc=gc.Prepare(hstmt,pQuery)
   if $$$ISERR(sc) quit sc
   //Execute statement
   set sc=gc.Execute(hstmt)
   if $$$ISERR(sc) quit sc
   //Get list of columns returned by query
   set sc=gc.DescribeColumns(hstmt, .columnlist)
   if $$$ISERR(sc) quit sc

   //display column headers delimited by ":"
   set numcols=$listlength(columnlist)-1  //get number of columns
   for colnum=2:1:numcols+1 {
      Write $listget($listget(columnlist,colnum),1),":"
   }
   write !

   //Return first 200 rows
   set sc=gc.Fetch(hstmt)
   if $$$ISERR(sc) quit sc
   set rownum=1
   while((gc.sqlcode'=100) && (rownum<=200)) {
      for ii=1:1:numcols {
         set sc=gc.GetData(hstmt, ii, 1, .val)
         write " "_val
         if $$$ISERR(sc) break
      }
      set rownum=rownum+1
      write !
      set sc=gc.Fetch(hstmt)
      if $$$ISERR(sc) break
   }

   //Close cursor and then disconnect
   set sc=gc.CloseCursor(hstmt)
   if $$$ISERR(sc) quit sc

   set sc=gc.Disconnect()
   quit sc
}

外部データ・セットの作成および使用

外部データベースをクエリするデータ・セットを作成および使用するには、以下の操作を実行します。

  1. %New() メソッドを使用して、%SQLGatewayConnectionOpens in a new tab のインスタンスを作成します。

  2. 作成したインスタンスの Connect() メソッドを呼び出し、ODBC データ・ソース名を指定する引数、および必要に応じて、ソースへのログインに必要なユーザ名とパスワードを渡します。

    Connect() メソッドには、以下のシグニチャがあります。

    method Connect(dsn, usr, pwd, timeout) as %Status
    
    

    ここで dsn は、データ・ソースの DSN です。usr は、データ・ソースにログインできるユーザです。pwd は対応するパスワードです。timeout は、接続を待機する長さを指定します。

  3. %New() メソッドを使用して %ResultSetOpens in a new tab のインスタンスを作成し、文字列引数 "%DynamicQueryGW:SQLGW" を指定します。

    Note:

    これは、通常のダイナミック・クエリ ("%DynamicQuery:SQL") で使用する引数とは若干異なります。

  4. 結果セットの Prepare() メソッドを呼び出します。最初の引数は SQL クエリを構成する文字列、2 番目の引数は省略、3 番目の引数は %SQLGatewayConnectionOpens in a new tab のインスタンスである必要があります。

  5. オプションとして、クエリで必要とする順序で引数を指定することにより、結果セットの Execute() メソッドを呼び出します。このメソッドはステータスを返すので、それを確認する必要があります。

結果セットを使用する場合は、通常、一度に 1 行ずつ検証します。%ResultSetOpens in a new tab のメソッドを使用して、指定した列の値などの情報を取得します。以下の例で示しているように、通常、Next() を使用してすべての行で反復を行います。

ClassMethod SelectAndWrite() as %Status
{
    Set conn=##class(%SQLGatewayConnection).%New()
    Set sc=conn.Connect("AccessPlayground","","")
    If $$$ISERR(sc) do $System.Status.DisplayError(sc) quit

    Set res=##class(%ResultSet).%New("%DynamicQueryGW:SQLGW")
    Set sc=res.Prepare("SELECT * FROM PEOPLE",,conn)
    If $$$ISERR(sc) do $System.Status.DisplayError(sc) quit

    Set sc=res.Execute()
    If $$$ISERR(sc) do $System.Status.DisplayError(sc) quit

    While res.Next()
    { Write !,res.GetData(1)," ",res.GetData(2)," ",res.GetData(3)
    }
    Set sc=conn.Disconnect()
    Quit sc
}

%ResultSetOpens in a new tab の詳細は、"InterSystems SQL の使用法" の “ダイナミック SQL の使用” の章を参照してください。%ResultSetOpens in a new tab のクラス・ドキュメントも参照してください。

ODBC 関数の直接呼出し

%SQL.StatementOpens in a new tab で十分に制御できない場合は、%SQLGatewayConnectionOpens in a new tab クラスを使用して ODBC に直接アクセスすることができます。このクラスは、ODBC 関数に対応する一連のメソッド (“サポートされる ODBC 関数呼び出し” を参照) およびその他のユーティリティ関数を提供します。ODBC 準拠のデータベースに接続して、これを使用できます。その後、低レベルの ODBC プログラミングを実行できます。全手順は、以下のとおりです。

  1. %New() メソッドを使用して、%SQLGatewayConnectionOpens in a new tab のインスタンスを作成します。

  2. 作成したインスタンスの Connect() メソッドを呼び出し、ODBC データ・ソース名を指定する引数、および必要に応じて、ソースへのログインに必要なユーザ名とパスワードを渡します。

  3. AllocateStatement() メソッドを呼び出して、文ハンドルを (参照により) 受け取ります。

  4. この文ハンドルを引数として使用して、SQL ゲートウェイ・インスタンスの他のメソッドを呼び出します。これらのメソッドのほとんどが、ODBC 関数を呼び出します。

以下の簡単な例は、この手順を示しています。これは、前のセクションの例に似ていますが、%SQL.StatementOpens in a new tab メソッドを使用するのではなく、%SQLGatewayConnectionOpens in a new tab バージョンの Prepare() および Execute() を使用して、ODBC クエリ関数 SQLPrepare() および SQLExecute() を直接呼び出します。

%SQLGatewayConnectionOpens in a new tab メソッドを使用したクエリの実行
ClassMethod ExecuteQuery(mTable As %String)
{
   set mDSN="DSNtest"
   set mUsrName="SYSDBA"
   set mUsrPwd="masterkey"

   // Create an instance and connect
   set gateway=##class(%SQLGatewayConnection).%New()
   set status=gateway.Connect(mDSN,mUsrName,mUsrPwd)
   if $$$ISERR(status) do $System.Status.DisplayError(status) quit $$$ERROR()
   set hstmt=""

   // Allocate a statement
  set status=gateway.AllocateStatement(.hstmt)
   if $$$ISERR(status) do $System.Status.DisplayError(status) quit $$$ERROR()

   // Use %SQLGatewayConnection to call ODBC query functions directly
   set status=gateway.Prepare(hstmt,"SELECT * FROM "_mTable)
   if $$$ISERR(status) do $System.Status.DisplayError(status) quit $$$ERROR()
   set status=gateway.Execute(hstmt)

   if $$$ISERR(status) do $System.Status.DisplayError(status) quit $$$ERROR()
   quit gateway.Disconnect()
}
Note:
NULL 値および空の文字列

この章で説明するメソッドを使用する場合、InterSystems IRIS と SQL との間には以下の重要な相違点があることに留意してください。

  • SQL では、"" は空の文字列を表します。

  • InterSystems IRIS では、"" は NULL です。

  • InterSystems IRIS では、$char(0) が空の文字列です。

%SQLGatewayConnection のクイック・リファレンス

SQLGatewayConnection API の概要

%SQLGatewayConnectionOpens in a new tab クラスには、外部データ・ソースへの接続の管理、ステータス情報の確認、および ODBC 共有ライブラリに関する情報の取得に使用できるプロパティとメソッドが用意されています。このリファレンスで取り上げるメソッドとプロパティは、以下に用途別にリストされています (ここにリストされていないメソッドは、“サポートされる ODBC 関数呼び出し” を参照してください)。

接続の管理

%SQLGatewayConnectionOpens in a new tab クラスには、外部データ・ソースへの接続の管理に使用できるプロパティとメソッドが用意されています。

  • DSN — (%String プロパティ) 接続先の ODBC 準拠データ・ソースのデータ・ソース名。

  • User — (%String プロパティ) データ・ソースにログインするためのユーザ名。

  • Password — (%String プロパティ) 関連付けられているパスワード。

  • ConnectionHandle — (%Binary プロパティ) 現在の接続では、ODBC 準拠のデータ・ソースが処理されます。

  • Connect() — DSN への接続を確立します。

  • GetConnection() — DSN、ユーザ名、およびパスワードを指定する構成設定を使用して接続を確立します。

  • SetConnectOption() — ODBC 関数 SQLSetConnectAttr を呼び出します。

  • Disconnect() — 接続を切断します。

スタータスおよびクエリ用のメソッド

%SQLGatewayConnectionOpens in a new tab のメソッドのほとんどはステータスを返すので、それを確認する必要があります。以下のプロパティとメソッドを使用してステータス情報を確認することもできます。

  • sqlcode — (%Integer プロパティ) 前回の呼び出し (ある場合) による SQL コードの戻り値が含まれます。

  • GatewayStatus — (%Integer プロパティ) 前回の呼び出しのステータスを示します。

  • GetLastSQLCode() — この呼び出しが SQL コードを返さない場合は、前回の呼び出しの SQL コードを返します。

  • GatewayStatusGet() — 前回の呼び出しのエラー・コードを返します。

以下のメソッドは、結果セットから行を取得します。

  • FetchRows() — 所定の接続ハンドルに指定されている行数を (参照により) 返します。

  • GetOneRow() — 所定の接続ハンドルの次の行を (参照により) 返します。

以下のメソッドは、結合されたクエリ・パラメータの値を取得および設定します。

  • GetParameter() — 指定したパラメータの現在の値を (参照により) 返します。

  • SetParameter() — 以前に結合したパラメータの値を設定します。

共有ライブラリの使用

%SQLGatewayConnectionOpens in a new tab クラスには、ODBC SQL ゲートウェイで使用する共有ライブラリに関する情報を取得するために呼び出すことが可能なプロパティとメソッドが用意されています。

  • DLLHandle — (%Binary プロパティ) 現在使用されている共有ライブラリのハンドル。これは、接続時に設定されます。

  • DLLName — (%String プロパティ) 現在使用されている共有ライブラリの名前。これは、接続時に設定されます。

  • GetGTWVersion() — 共有ライブラリの現在のバージョンを返します。

  • GetUV() — 共有ライブラリが Unicode として構築されているかどうかを (参照により) 返します。このメソッドは常に $$$OK のステータスを返します。

  • UnloadDLL() — プロセス・メモリから共有ライブラリをアンロードします。

%SQLGatewayConnection のメソッドおよびプロパティ

以下に、選定されたメソッドおよびプロパティのアルファベット順のリストを示します。ここにリストされていないメソッドは、“サポートされる ODBC 関数呼び出し” を参照してください。

AllocateStatement()

ODBC 関数 SQLAllocHandle() を呼び出して、対応する構造を SQL ゲートウェイに作成します。

method AllocateStatement(ByRef hstmt) as %Status
Connect()

DSN への接続を確立します。

method Connect(dsn, usr, pwd, timeout) as %Status

ユーザ名とパスワードが両方とも空のとき、このメソッドは ODBC 関数 SQLDriverConnect() を呼び出します。その呼び出しが成功しないとき、またはユーザ名とパスワードを指定したとき、このメソッドは ODBC関数 SQLConnect() を呼び出します。

timeout パラメータが 0 以外の場合、まず、SQLSetConnectAttr() が呼び出されて、SQL_ATTR_LOGIN_TIMEOUT が設定されます。

ConnectionHandle プロパティ

ODBC 準拠データ・ソースに現在の接続ハンドルを提供する %BinaryOpens in a new tab プロパティ。

Disconnect()

接続を切断します。

method Disconnect() as %Status
DLLHandle プロパティ

現在使用されている共有ライブラリのハンドルを提供する %BinaryOpens in a new tab プロパティ。これは、接続時に設定されます。

DLLName プロパティ

現在使用されている共有ライブラリの名前を提供する %StringOpens in a new tab プロパティ。これは、接続時に設定されます。

DSN プロパティ

接続先の ODBC 準拠データ・ソースのデータ・ソース名を提供する %StringOpens in a new tab プロパティ。

FetchRows()

所定の接続ハンドルに指定されている行数を (参照により) 返します。

method FetchRows(hstmt, Output rlist As %List, nrows As %Integer) as %Status

ここでは、hstmt がその接続ハンドルです。これは、(参照により) AllocateStatement(). から返されます。また、rlist は、返される行リストです。これは、InterSystems IRIS の $list の 1 つです。リストの各アイテムには行が 1 つ含まれています。データがない場合 (SQL_CODE = 100)、フェッチは成功したと見なされますが、返されるリストは空です。

Caution:

基本的に、このメソッドはテストに使用すると便利です。文字フィールドを最大 120 文字に切り捨てるので、1 行に収まるフィールド数が多くなります。切り捨てられていないデータが必要な場合は、代わりに GetData() を使用します。

GatewayStatus プロパティ

前回の呼び出しのステータスを提供する %StringOpens in a new tab プロパティ。ステータス値は、以下のいずれかです。

  • 0 – 成功

  • -1 - SQL エラー

  • -1000 - 重大なエラー

GatewayStatusGet()

前回の呼び出しのエラー・コードを返します。

method GatewayStatusGet() as %Integer

この呼び出しはエラー・コードを初期化しないため、複数回呼び出すことができます。前述の GatewayStatus プロパティに関する注記を参照してください。

GetConnection()

DSN、ユーザ名、およびパスワードを指定する構成ファイル・エントリを使用して接続を確立します。

method GetConnection(conn, timeout) as %Status
GetGTWVersion()

共有ライブラリの現在のバージョンを返します。

method GetGTWVersion() as %Integer
GetLastSQLCode()

この呼び出しが SQL コードを返さない場合 (SQLGetData() を使用した場合など) は、前回の呼び出しの SQL コードを返します。

method GetLastSQLCode() as %Integer

GetOneRow()

所定の接続ハンドルの次の行を (参照により) 返します。

method GetOneRow(hstmt, ByRef row) as %Status

ここでは、hstmt がその接続ハンドルです。これは、(参照により) AllocateStatement(). から返されます。また、row は返される行で、InterSystems IRIS の $list の 1 つです。リストの各アイテムにはフィールドが 1 つ含まれています。データがない場合 (SQL_CODE = 100)、フェッチは成功したと見なされますが、返されるリストは空です。

Caution:

基本的に、このメソッドはテストに使用すると便利です。文字フィールドを最大 120 文字に切り捨てるので、1 行に収まるフィールド数が多くなります。切り捨てられていないデータが必要な場合は、代わりに GetData() を使用します。

GetParameter()

指定したパラメータの現在の値を (参照により) 返します。

method GetParameter(hstmt, pnbr, ByRef value) as %Status

ここで、hstmtAllocateStatement() から (参照により) 返される接続ハンドルで、pnbr はパラメータの順序数です。

GetUV()

共有ライブラリが Unicode として構築されているかどうかを (参照により) 返します。

method GetUV(ByRef infoval) as %Status

このメソッドは常に $$$OK のステータスを返します。

Password プロパティ

関連付けられているパスワードを提供する %StringOpens in a new tab プロパティ。

SetConnectOption()

ODBC 関数 SQLSetConnectAttr() を呼び出します。

method SetConnectOption(opt, val) as %Status

整数値のみがサポートされます。opt 引数の整数値は、sql.h ヘッダ・ファイルおよび sqlext.h ヘッダ・ファイルから取得することもできます。

SetParameter()

以前に結合したパラメータの値を設定します。

method SetParameter(hstmt, pvalue, pnbr) as %Status

ここで、hstmtAllocateStatement() から (参照により) 返される接続ハンドルで、pvalue は使用する値で、pnbr はパラメータの順序数です。パラメータは、$list 形式で格納されます。割り当てられているバッファが不十分な場合は、新しいバッファが割り当てられます。

sqlcode プロパティ

前回の呼び出し (ある場合) によって返された SQL コードを提供する %IntegerOpens in a new tab プロパティ。

UnloadDLL()

ODBC SQL ゲートウェイの共有ライブラリをプロセス・メモリからアンロードします。

method UnloadDLL() as %Status
User プロパティ

データ・ソースにログインするためのユーザ名を提供する %StringOpens in a new tab プロパティ。

サポートされる ODBC 関数呼び出し

次の表に、対応する %SQLGatewayConnectionOpens in a new tab メソッドで直接サポートされる ODBC 関数と、それらのメソッドのクラス・ドキュメントへのリンクを示します。メソッドを呼び出して ODBC 関数 SQLPrepareSQLExecute を起動する例については、“ODBC 関数の直接呼出し” を参照してください。

この章は、これらのメソッドの詳細なリファレンスではありません。メソッドの引数、アクション、および戻り値の詳細は、InterSystems クラス・ライブラリのリファレンスで %SQLGatewayConnectionOpens in a new tab を参照してください。

%SQLGatewayConnection からの ODBC 関数の呼び出し
ODBC 関数 関数を呼び出す ObjectScript メソッド
SQLAllocHandle AllocateStatement()Opens in a new tab
SQLBindParameter BindParameter()Opens in a new tabBindParameters()Opens in a new tab
SQLCloseCursor CloseCursor()Opens in a new tab
SQLColAttribute DescribeColumns()Opens in a new tab
SQLColumnPrivileges ColumnPrivileges()Opens in a new tabColumnPrivilegesW()Opens in a new tab
SQLColumns Columns()Opens in a new tabColumnsW()Opens in a new tab
SQLDescribeCols DescribeColumns()Opens in a new tab
SQLDescribeParam DescribeParameters()Opens in a new tab
SQLDiagRec GetErrorList()Opens in a new tab
SQLEndTran Transact()Opens in a new tab
SQLExecute Execute()Opens in a new tab
SQLFetch Fetch()Opens in a new tab
SQLForeignKeys ForeignKeys()Opens in a new tabForeignKeysW()Opens in a new tab
SQLFreeHandle DropStatement()Opens in a new tab
SQLFreeStmt UnbindParameters()Opens in a new tab
SQLGetData GetData()Opens in a new tabGetDataL()Opens in a new tabGetDataLW()Opens in a new tabGetDataW()Opens in a new tab
SQLGetInfo GetInfo()Opens in a new tab
SQLGetTypeInfo GetTypeInfo()Opens in a new tab
SQLMoreResults MoreResults()Opens in a new tab
SQLNumParams DescribeParameters()Opens in a new tab
SQLParamData ParamData()Opens in a new tab
SQLPrepare Prepare()Opens in a new tabPrepareW()Opens in a new tab
SQLPrimaryKeys PrimaryKeys()Opens in a new tabPrimaryKeysW()Opens in a new tab
SQLProcedureColumns DescribeProcedureColumns()Opens in a new tabDescribeProcedureColumnsW()Opens in a new tab
SQLProcedures DescribeProcedures()Opens in a new tabDescribeProceduresW()Opens in a new tab
SQLPutData PutData()Opens in a new tabPutDataW()Opens in a new tab
SQLRowCount RowCount()Opens in a new tab
SQLSetConnectAttr SetConnectOption()Opens in a new tab
SQLSetStmtAttr SetStmtOption()Opens in a new tab
SQLSpecialColumns SpecialColumns()Opens in a new tabSpecialColumnsW()Opens in a new tab
SQLStatistics Statistics()Opens in a new tabStatisticsW()Opens in a new tab
SQLTablePrivileges TablePrivileges()Opens in a new tabTablePrivilegesW()Opens in a new tab
SQLTables Tables()Opens in a new tabTablesW()Opens in a new tab
FeedbackOpens in a new tab