DBMS_HS_PASSTHROUGH

86 DBMS_HS_PASSTHROUGH

DBMS_HS_PASSTHROUGH PL/SQLパッケージを使用すると、Oracleサーバーによる解釈がなくてもOracle以外のシステムに文を直接送信できます。この機能は、Oracle以外のシステムで使用できる文と同等の文がOracleにない場合に役立ちます。

この章では、以下のトピックについて説明します。

DBMS_HS_PASSTHROUGHの概要
DBMS_HS_PASSTHROUGHの操作上のノート
DBMS_HS_PASSTHROUGHサブプログラムの要約

参照:

このパッケージの詳細は、『Oracle Database Heterogeneous Connectivityユーザーズ・ガイド』を参照してください。

86.1 DBMS_HS_PASSTHROUGHの概要

PL/SQLパッケージDBMS_HS_PASSTHROUGHを使用すると、パススルーSQL文をOracle以外のシステムで直接実行できます。このパッケージで実行される文は、標準のSQL文と同じトランザクションで実行されます。

参照:

このパッケージの詳細は、『Oracle Database Heterogeneous Connectivityユーザーズ・ガイド』を参照してください。

86.2 DBMS_HS_PASSTHROUGHの操作上のノート

DBMS_HS_PASSTHROUGHパッケージは仮想パッケージです。概念上は、Oracle以外のシステムに常駐します。ただし、実際には、このパッケージのコールは異機種間サービスにより仲介され、1つ以上の異機種間サービス・コールにマップされます。次に、これらの異機種間サービス・コールは、ドライバによりOracle以外のシステムのAPIにマップされます。クライアント・アプリケーションは、Oracle以外のシステムのストアド・プロシージャをコールする場合と同じ方法で、データベース・リンクを介してパッケージ内のプロシージャをコールする必要があります。異機種間サービスにより実行される特殊処理は、ユーザーに対して透過的です。

86.3 DBMS_HS_PASSTHROUGHサブプログラムの要約

この表は、DBMS_HS_PASSTHROUGHサブプログラムを示し、簡単に説明しています。

表86-1 DBMS_HS_PASSTHROUGHパッケージのサブプログラム

サブプログラム	説明
BIND_INOUT_VARIABLEプロシージャ	`IN` `OUT`バインド変数をバインドします。
BIND_INOUT_VARIABLE_RAWプロシージャ	データ・タイプ`RAW`の`IN` `OUT`バインド変数をバインドします。
BIND_OUT_VARIABLEプロシージャ	`OUT`変数をPL/SQLプログラム変数にバインドします。
BIND_OUT_VARIABLE_RAWプロシージャ	データ・タイプ`RAW`の`OUT`変数をPL/SQLプログラム変数にバインドします。
BIND_VARIABLEプロシージャ	位置を基準にして`IN`変数をPL/SQLプログラム変数にバインドします。
BIND_VARIABLE_RAWプロシージャ	`RAW`タイプの`IN`変数をバインドします。
CLOSE_CURSORプロシージャ	SQL文がOracle以外のシステムで実行された後は、カーソルをクローズして、関連メモリーを解放します。
EXECUTE_IMMEDIATEプロシージャ	バインド変数を使用せずに、(`SELECT`以外の)SQL文を即時実行します。
EXECUTE_NON_QUERYファンクション	(`SELECT`以外の)SQL文を実行します。
FETCH_ROWファンクション	問合せから行をフェッチします。
GET_VALUEプロシージャ	`SELECT`文から列値を取り出すか、または`OUT`バインド・パラメータを取り出します。
GET_VALUE_RAWプロシージャ	`GET_VALUE`と同様ですが、データ・タイプ`RAW`に使用します。
OPEN_CURSORファンクション	Oracle以外のシステムでパススルーSQL文を実行するためのカーソルをオープンします。
PARSEプロシージャ	Oracle以外のシステムでSQL文を解析します。

86.3.1 BIND_INOUT_VARIABLEプロシージャ

このプロシージャは、IN OUTバインド変数をバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_OUT_VARIABLE (
   c      IN  BINARY_INTEGER NOT NULL,
   p      IN  BINARY_INTEGER NULL,
   v      OUT <dty>,
   n      IN  VARCHAR2);

<dty>はDATE、NUMBERまたはVARCHAR2のいずれかです。

参照:

RAWデータ・タイプのOUT変数のバインド方法については、「BIND_OUT_VARIABLE_RAWプロシージャ」を参照してください。

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-2 BIND_INOUT_VARIABLEプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	この値は次の2つの目的で使用されます。 - SQL文が実行される前にINの値を設定します。 - OUT値のサイズを判別します。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-3 BIND_INOUT_VARIABLEプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.2 BIND_INOUT_VARIABLE_RAWプロシージャ

このプロシージャは、データ・タイプRAWのIN OUTバインド変数をバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_INOUT_VARIABLE_RAW (
   c      IN     BINARY_INTEGER NOT NULL,
   p      IN     BINARY_INTEGER NOT NULL,
   v      IN OUT RAW,
   n      IN     VARCHAR2);

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-4 BIND_INOUT_VARIABLE_RAWプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	この値は次の2つの目的で使用されます。 - SQL文が実行される前にINの値を設定します。 - OUT値のサイズを判別します。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-5 BIND_INOUT_VARIABLE_RAWプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.3 BIND_OUT_VARIABLEプロシージャ

このプロシージャは、OUT変数をPL/SQLプログラム変数にバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_OUT_VARIABLE (
   c      IN  BINARY_INTEGER NOT NULL,
   p      IN  BINARY_INTEGER NULL,
   v      OUT <dty>,
   n      IN  VARCHAR2);

<dty>はDATE、NUMBERまたはVARCHAR2のいずれかです。

参照:

RAWデータ・タイプのOUT変数のバインド方法については、「BIND_OUT_VARIABLE_RAWプロシージャ」を参照してください。

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-6 BIND_OUT_VARIABLEプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	`OUT`バインド変数がその値を格納する変数。パッケージは、変数のサイズのみ記憶しています。SQL文が実行された後、`GET_VALUE`を使用して`OUT`パラメータの値を取り出せます。取り出される値のサイズが、`BIND_OUT_VARIABLE`を使用して渡されたパラメータのサイズを超えないようにしてください。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-7 BIND_OUT_VARIABLEプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.4 BIND_OUT_VARIABLE_RAWプロシージャ

このプロシージャは、データ・タイプRAWのOUT変数をPL/SQLプログラム変数にバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_OUT_VARIABLE_RAW (
   c     IN  BINARY_INTEGER NOT NULL,
   p     IN  BINARY_INTEGER NOT NULL,
   v     OUT RAW,
   n     IN  VARCHAR2);

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-8 BIND_OUT_VARIABLE_RAWプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	`OUT`バインド変数がその値を格納する変数。パッケージは、変数のサイズのみ記憶しています。SQL文が実行された後、`GET_VALUE`を使用して`OUT`パラメータの値を取り出せます。取り出される値のサイズが、`BIND_OUT_VARIABLE_RAW`を使用して渡されたパラメータのサイズを超えないようにしてください。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-9 BIND_OUT_VARIABLE_RAWプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.5 BIND_VARIABLEプロシージャ

このプロシージャは、位置を基準にしてIN変数をPL/SQLプログラム変数にバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_VARIABLE (
   c      IN BINARY_INTEGER NOT NULL,
   p      IN BINARY_INTEGER NOT NULL,
   v      IN <dty>,
   n      IN VARCHAR2);

<dty>はDATE、NUMBERまたはVARCHAR2のいずれかです。

参照:

RAW変数をバインドするには、BIND_VARIABLE_RAWプロシージャを使用してください。

プラグマ

Purity level defined: WNDS, RNDS

パラメータ

表86-10 BIND_VARIABLEプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	バインド変数名に渡す必要がある値。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-11 BIND_VARIABLEプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.6 BIND_VARIABLE_RAWプロシージャ

このプロシージャは、RAWタイプのIN変数をバインドします。

構文

DBMS_HS_PASSTHROUGH.BIND_VARIABLE_RAW (
   c    IN BINARY_INTEGER NOT NULL,
   p    IN BINARY_INTEGER NOT NULL,
   v    IN RAW,  
   n    IN VARCHAR2);

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-12 BIND_VARIABLE_RAWプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数の位置。1から始まります。
`v`	バインド変数に渡す必要がある値。
`n`	(オプション)バインド変数名。たとえば、`SELECT * FROM emp WHERE ename=:ename`では、バインド変数:`ename`の位置は1、名前は:`ename`です。このパラメータは、Oracle以外のシステムで位置によるバインドではなく名前によるバインドがサポートされている場合に使用できます。この場合も位置を渡す必要があります。

例外

表86-13 BIND_VARIABLE_RAWプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.7 CLOSE_CURSORプロシージャ

このファンクションは、SQL文がOracle以外のシステムで実行された後に、カーソルをクローズし、関連メモリーを解放します。カーソルがオープンされていない場合、操作は何も行われません。

構文

DBMS_HS_PASSTHROUGH.CLOSE_CURSOR (
   c IN BINARY_INTEGER NOT NULL);

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-14 CLOSE_CURSORプロシージャのパラメータ

パラメータ	説明
`c`	解放するカーソル

例外

表86-15 CLOSE_CURSORプロシージャの例外

例外	説明
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.8 EXECUTE_IMMEDIATEプロシージャ

このファンクションは、SQL文を即時実行します。有効なSQLコマンド(SELECTを除く)をすぐに実行できます。

文にバインド変数を含めることはできません。文は引数でVARCHAR2として渡されます。SQL文は、内部的には、OPEN_CURSOR、PARSE、EXECUTE_NON_QUERYおよびCLOSE_CURSORのPASSTHROUGH SQLプロトコル・シーケンスを使用して実行されます。

構文

DBMS_HS_PASSTHROUGH.EXECUTE_IMMEDIATE ( 
   s IN VARCHAR2 NOT NULL)  
RETURN BINARY_INTEGER;

パラメータ

表86-16 EXECUTE_IMMEDIATEプロシージャのパラメータ

パラメータ	説明
`s`	即時実行対象の文を含む`VARCHAR2`変数

戻り値

SQL文の実行によって影響を受ける行数。

例外

表86-17 EXECUTE_IMMEDIATEプロシージャの例外

例外	説明
`ORA-28551`	SQL文が正しくありません。
`ORA-28554`	オープンしているカーソルが最大数に達しました。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.9 EXECUTE_NON_QUERYファンクション

このファンクションはSQL文を実行します。SQL文にSELECT文は使用できません。SQL文を実行する前に、カーソルをオープンし、SQL文を解析する必要があります。

構文

DBMS_HS_PASSTHROUGH.EXECUTE_NON_QUERY ( 
   c IN BINARY_INTEGER NOT NULL)
  RETURN BINARY_INTEGER;

パラメータ

表86-18 EXECUTE_NON_QUERYファンクションのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。

戻り値

Oracle以外のシステムでSQL文によって影響を受ける行数。

例外

表86-19 EXECUTE_NON_QUERYファンクションの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.10 FETCH_ROWファンクション

このファンクションは、結果セットから行をフェッチします。

結果セットは、SQL SELECT文で定義されます。それ以上フェッチする行がなくなると、例外NO_DATA_FOUNDが発生します。行をフェッチする前に、カーソルをオープンし、SQL文を解析する必要があります。

構文

DBMS_HS_PASSTHROUGH.FETCH_ROW (
   c   IN BINARY_INTEGER NOT NULL,
   f   IN BOOLEAN)
  RETURN BINARY_INTEGER;

プラグマ

Purity level defined : WNDS

パラメータ

表86-20 FETCH_ROWファンクションのパラメータ

パラメータ説明

c

パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチンOPEN_CURSORを使用してオープンし、PARSEを使用して解析する必要があります。

first

(オプション)SELECT文を再実行します。有効な値は、次のとおりです。

- TRUE: SELECT文を再実行します。

- FALSE: 次の行をフェッチするか、または初めて実行する場合は、実行して行をフェッチします(デフォルト)。

戻り値

フェッチされた行数が戻されます。最終行がすでにフェッチされている場合は、0(ゼロ)が戻されます。

例外

表86-21 FETCH_ROWファンクションの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.11 GET_VALUEプロシージャ

このプロシージャには、2つの目的があります。すなわち、行がフェッチされた後にSELECT文の選択リスト項目を取得すること、およびSQL文が実行された後にOUTバインド値を取得することです。

構文

DBMS_HS_PASSTHROUGH.GET_VALUE (
   c      IN  BINARY_INTEGER NOT NULL,
   p    IN  BINARY_INTEGER NOT NULL,
   v    OUT <dty>);

<dty>はDATE、NUMBERまたはVARCHAR2のいずれかです。

参照:

RAWデータ・タイプの値を取り出す方法については、「GET_VALUE_RAWプロシージャ」を参照してください。

プラグマ

Purity level defined : WNDS

パラメータ

表86-22 GET_VALUEプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数または選択リスト項目の位置。1から始まります。
`v`	`OUT`バインド変数または選択リスト項目がその値を格納する変数。

例外

表86-23 GET_VALUEプロシージャの例外

例外	説明
`ORA-1403`	最終行がフェッチされた後に、`GET_VALUE`を実行すると`NO_DATA_FOUND`例外が戻されます(`FETCH_ROW`によって0(ゼロ)が戻されます)。
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.12 GET_VALUE_RAWプロシージャ

このプロシージャはGET_VALUEと同様ですが、データ・タイプRAWに使用します。

構文

DBMS_HS_PASSTHROUGH.GET_VALUE_RAW (
   c    IN  BINARY_INTEGER NOT NULL,
   p    IN  BINARY_INTEGER NOT NULL,
   v    OUT RAW);

プラグマ

Purity level defined : WNDS

パラメータ

表86-24 GET_VALUE_RAWプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。カーソルは、ルーチン`OPEN_CURSOR`を使用してオープンし、`PARSE`を使用して解析する必要があります。
`p`	SQL文におけるバインド変数または選択リスト項目の位置。1から始まります。
`v`	`OUT`バインド変数または選択リスト項目がその値を格納する変数。

例外

表86-25 GET_VALUE_RAWプロシージャの例外

例外	説明
`ORA-1403`	最終行がフェッチされた後に、`GET_VALUE`を実行すると`NO_DATA_FOUND`例外が戻されます(`FETCH_ROW`によって0(ゼロ)が戻されます)。
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28552`	プロシージャが正しい順序で実行されません。(最初にカーソルをオープンし、SQL文を解析する必要があります)。
`ORA-28553`	バインド変数の位置が有効範囲外です。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。

86.3.13 OPEN_CURSORファンクション

このファンクションは、Oracle以外のシステムでパススルーSQL文を実行するためのカーソルをオープンします。このファンクションは、すべてのタイプのSQL文に対してコールする必要があります。

後続のコールで使用する必要があるカーソルが戻されます。このコールによってメモリーが割り当てられます。関連付けられたメモリーの割当てを解除するには、プロシージャCLOSE_CURSORをコールします。

構文

DBMS_HS_PASSTHROUGH.OPEN_CURSOR 
  RETURN BINARY_INTEGER;

プラグマ

Purity level defined : WNDS, RNDS

戻り値

後続のプロシージャおよびファンクション・コールで使用されるカーソル。

例外

表86-26 OPEN_CURSORファンクションの例外

例外	説明
`ORA-28554`	カーソルの最大オープン数を超えました。異機種間サービスの`OPEN_CURSORS`初期化パラメータの値を増やしてください。

86.3.14 PARSEプロシージャ

このプロシージャは、Oracle以外のシステムでSQL文を解析します。

構文

DBMS_HS_PASSTHROUGH.PARSE (
   c       IN  BINARY_INTEGER NOT NULL,
   stmt    IN  VARCHAR2 NOT NULL);

プラグマ

Purity level defined : WNDS, RNDS

パラメータ

表86-27 PARSEプロシージャのパラメータ

パラメータ	説明
`c`	パススルーSQL文に関連付けられたカーソル。ファンクション`OPEN_CURSOR`を使用してオープンする必要があります。
`stmt`	解析する文。

例外

表86-28 PARSEプロシージャの例外

例外	説明
`ORA-28550`	渡されたカーソルが無効です。
`ORA-28551`	SQL文が正しくありません。
`ORA-28555`	`NOT` `NULL`のパラメータに`NULL`値が渡されました。