プログラムによる SQL ゲートウェイの使用法
このセクションでは、読者が ODBC API 呼び出しの使用経験が豊富であると想定しており、ODBC 関数の詳しい使用方法は説明しません。問題が発生した場合、InterSystems IRIS と ODBC の両方のログを有効化して SQL ゲートウェイを監視できます ("InterSystems ODBC ドライバ の使用法" の “ログと環境変数” の章を参照してください)。
標準 SQL ゲートウェイ・ウィザードで提供されないオプションが必要な場合、%Library.SQLGatewayConnectionOpens in a new tab クラスを使用して ObjectScript から ODBC 関数を呼び出すことができます。ダイナミック・クエリ (結果セットを取得する) を実行することも、低レベルの ODBC プログラミングを実行することもできます。この章で説明する項目は以下のとおりです。
-
FetchSamples の例 — 接続を開き、クエリを実行し、結果セットにアクセスする簡単なプログラムを紹介します。
-
外部データ・セットの作成および使用 — %SQL.StatementOpens in a new tab メソッドを使用してクエリを実行しデータ・セットにアクセスする方法について説明します。
-
ODBC 関数の直接呼出し — %SQL.StatementOpens in a new tab を使用せずに ODBC クエリ関数を直接呼び出す方法について説明します。
-
%SQLGatewayConnection のクイック・リファレンス — サポートされるメソッドおよびプロパティの詳細を示します。
この章の残りの部分では、%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()
{
#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
}
外部データ・セットの作成および使用
外部データベースをクエリするデータ・セットを作成および使用するには、以下の操作を実行します。
-
%New() メソッドを使用して、%SQLGatewayConnectionOpens in a new tab のインスタンスを作成します。
-
作成したインスタンスの Connect() メソッドを呼び出し、ODBC データ・ソース名を指定する引数、および必要に応じて、ソースへのログインに必要なユーザ名とパスワードを渡します。
Connect() メソッドには、以下のシグニチャがあります。
method Connect(dsn, usr, pwd, timeout) as %Status
ここで dsn は、データ・ソースの DSN です。usr は、データ・ソースにログインできるユーザです。pwd は対応するパスワードです。timeout は、接続を待機する長さを指定します。
-
%New() メソッドを使用して %ResultSetOpens in a new tab のインスタンスを作成し、文字列引数 "%DynamicQueryGW:SQLGW" を指定します。
Note:これは、通常のダイナミック・クエリ ("%DynamicQuery:SQL") で使用する引数とは若干異なります。
-
結果セットの Prepare() メソッドを呼び出します。最初の引数は SQL クエリを構成する文字列、2 番目の引数は省略、3 番目の引数は %SQLGatewayConnectionOpens in a new tab のインスタンスである必要があります。
-
オプションとして、クエリで必要とする順序で引数を指定することにより、結果セットの 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 プログラミングを実行できます。全手順は、以下のとおりです。
-
%New() メソッドを使用して、%SQLGatewayConnectionOpens in a new tab のインスタンスを作成します。
-
作成したインスタンスの Connect() メソッドを呼び出し、ODBC データ・ソース名を指定する引数、および必要に応じて、ソースへのログインに必要なユーザ名とパスワードを渡します。
-
AllocateStatement() メソッドを呼び出して、文ハンドルを (参照により) 受け取ります。
-
この文ハンドルを引数として使用して、SQL ゲートウェイ・インスタンスの他のメソッドを呼び出します。これらのメソッドのほとんどが、ODBC 関数を呼び出します。
以下の簡単な例は、この手順を示しています。これは、前のセクションの例に似ていますが、%SQL.StatementOpens in a new tab メソッドを使用するのではなく、%SQLGatewayConnectionOpens in a new tab バージョンの Prepare() および Execute() を使用して、ODBC クエリ関数 SQLPrepare() および SQLExecute() を直接呼び出します。
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()
}
この章で説明するメソッドを使用する場合、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() — 以前に結合したパラメータの値を設定します。
%SQLGatewayConnection のメソッドおよびプロパティ
以下に、選定されたメソッドおよびプロパティのアルファベット順のリストを示します。ここにリストされていないメソッドは、“サポートされる ODBC 関数呼び出し” を参照してください。
ODBC 関数 SQLAllocHandle() を呼び出して、対応する構造を SQL ゲートウェイに作成します。
method AllocateStatement(ByRef hstmt) as %Status
DSN への接続を確立します。
method Connect(dsn, usr, pwd, timeout) as %Status
ユーザ名とパスワードが両方とも空のとき、このメソッドは ODBC 関数 SQLDriverConnect() を呼び出します。その呼び出しが成功しないとき、またはユーザ名とパスワードを指定したとき、このメソッドは ODBC関数 SQLConnect() を呼び出します。
timeout パラメータが 0 以外の場合、まず、SQLSetConnectAttr() が呼び出されて、SQL_ATTR_LOGIN_TIMEOUT が設定されます。
ODBC 準拠データ・ソースに現在の接続ハンドルを提供する %BinaryOpens in a new tab プロパティ。
接続を切断します。
method Disconnect() as %Status
現在使用されている共有ライブラリのハンドルを提供する %BinaryOpens in a new tab プロパティ。これは、接続時に設定されます。
現在使用されている共有ライブラリの名前を提供する %StringOpens in a new tab プロパティ。これは、接続時に設定されます。
接続先の ODBC 準拠データ・ソースのデータ・ソース名を提供する %StringOpens in a new tab プロパティ。
所定の接続ハンドルに指定されている行数を (参照により) 返します。
method FetchRows(hstmt, Output rlist As %List, nrows As %Integer) as %Status
ここでは、hstmt がその接続ハンドルです。これは、(参照により) AllocateStatement(). から返されます。また、rlist は、返される行リストです。これは、InterSystems IRIS の $list の 1 つです。リストの各アイテムには行が 1 つ含まれています。データがない場合 (SQL_CODE = 100)、フェッチは成功したと見なされますが、返されるリストは空です。
基本的に、このメソッドはテストに使用すると便利です。文字フィールドを最大 120 文字に切り捨てるので、1 行に収まるフィールド数が多くなります。切り捨てられていないデータが必要な場合は、代わりに GetData() を使用します。
前回の呼び出しのステータスを提供する %StringOpens in a new tab プロパティ。ステータス値は、以下のいずれかです。
-
0 – 成功
-
-1 - SQL エラー
-
-1000 - 重大なエラー
前回の呼び出しのエラー・コードを返します。
method GatewayStatusGet() as %Integer
この呼び出しはエラー・コードを初期化しないため、複数回呼び出すことができます。前述の GatewayStatus プロパティに関する注記を参照してください。
DSN、ユーザ名、およびパスワードを指定する構成ファイル・エントリを使用して接続を確立します。
method GetConnection(conn, timeout) as %Status
共有ライブラリの現在のバージョンを返します。
method GetGTWVersion() as %Integer
この呼び出しが SQL コードを返さない場合 (SQLGetData() を使用した場合など) は、前回の呼び出しの SQL コードを返します。
method GetLastSQLCode() as %Integer
所定の接続ハンドルの次の行を (参照により) 返します。
method GetOneRow(hstmt, ByRef row) as %Status
ここでは、hstmt がその接続ハンドルです。これは、(参照により) AllocateStatement(). から返されます。また、row は返される行で、InterSystems IRIS の $list の 1 つです。リストの各アイテムにはフィールドが 1 つ含まれています。データがない場合 (SQL_CODE = 100)、フェッチは成功したと見なされますが、返されるリストは空です。
基本的に、このメソッドはテストに使用すると便利です。文字フィールドを最大 120 文字に切り捨てるので、1 行に収まるフィールド数が多くなります。切り捨てられていないデータが必要な場合は、代わりに GetData() を使用します。
指定したパラメータの現在の値を (参照により) 返します。
method GetParameter(hstmt, pnbr, ByRef value) as %Status
ここで、hstmt は AllocateStatement() から (参照により) 返される接続ハンドルで、pnbr はパラメータの順序数です。
共有ライブラリが Unicode として構築されているかどうかを (参照により) 返します。
method GetUV(ByRef infoval) as %Status
このメソッドは常に $$$OK のステータスを返します。
関連付けられているパスワードを提供する %StringOpens in a new tab プロパティ。
ODBC 関数 SQLSetConnectAttr() を呼び出します。
method SetConnectOption(opt, val) as %Status
整数値のみがサポートされます。opt 引数の整数値は、sql.h ヘッダ・ファイルおよび sqlext.h ヘッダ・ファイルから取得することもできます。
以前に結合したパラメータの値を設定します。
method SetParameter(hstmt, pvalue, pnbr) as %Status
ここで、hstmt は AllocateStatement() から (参照により) 返される接続ハンドルで、pvalue は使用する値で、pnbr はパラメータの順序数です。パラメータは、$list 形式で格納されます。割り当てられているバッファが不十分な場合は、新しいバッファが割り当てられます。
前回の呼び出し (ある場合) によって返された SQL コードを提供する %IntegerOpens in a new tab プロパティ。
ODBC SQL ゲートウェイの共有ライブラリをプロセス・メモリからアンロードします。
method UnloadDLL() as %Status
データ・ソースにログインするためのユーザ名を提供する %StringOpens in a new tab プロパティ。
サポートされる ODBC 関数呼び出し
次の表に、対応する %SQLGatewayConnectionOpens in a new tab メソッドで直接サポートされる ODBC 関数と、それらのメソッドのクラス・ドキュメントへのリンクを示します。メソッドを呼び出して ODBC 関数 SQLPrepare と SQLExecute を起動する例については、“ODBC 関数の直接呼出し” を参照してください。
この章は、これらのメソッドの詳細なリファレンスではありません。メソッドの引数、アクション、および戻り値の詳細は、InterSystems クラス・ライブラリのリファレンスで %SQLGatewayConnectionOpens in a new tab を参照してください。