ゲートウェイRPCインタフェース

B ゲートウェイRPCインタフェース

Oracle Database Gateway for APPCを使用してリモート・トランザクション・プログラムを実行するには、リモート・プロシージャ・コール(RPC)を使用して、ゲートウェイ関数を呼び出すPL/SQLプログラムを実行する必要があります。ゲートウェイ機能は、リモート・トランザクション・プログラムとのゲートウェイ対話の開始、データ交換、および終了を処理します。

Oracle Database Gateway for APPCには、COBOLレコード・レイアウトとPGDL (Procedural Gateway Definition Language)の形式で提供する定義に基づいて、自動的にPL/SQLパッケージ(TIP)を生成するツールPGAUが含まれています。

ゲートウェイ関数はすべてリモート・プロシージャ・コール(RPC)によって実行されます。この関数は、次のようにPL/SQLコードから呼び出されます:

function@dblink(parm1,parm2,...,parmn);

「表B-1」がこの構文のパラメータを記述する場所:

表B-1ゲートウェイ機能

項目	説明
`function`	呼び出される関数の名前です。
`dblink`	Windowsシステム上のゲートウェイ・サーバーへの事前定義データベース・リンクの名前です。
`parm1, parm2,parmn`	この付録で後述する関数固有のパラメータです。

関数名に続く@dblink表記でPL/SQLコード内の関数を呼び出すのは、リモート・プロシージャ・コールです。

PGAINITとPGAINIT_SEC

PGAINIT とPGAINIT_SECは、指定されたトランザクション・プログラムとのAPPC会話を開始するリモート・プロシージャ・コールです。この2つの違いは、PGAINIT_SECに、ゲートウェイの会話セキュリティのユーザーIDとパスワードを現在のOracleユーザーIDとパスワード以外の値に設定できるという追加機能が含まれていることです。いずれかの機能が正常に完了すると、会話はリモート・トランザクション・プログラムにデータを送信する準備ができている。

「表B-2」は、両方の手順で共通のPGAINITおよびPGAINIT_SECパラメータを表示します。各パラメータのタイプ、データ型、および説明がリストされています:

表B-2共通のPGAINITおよびPGAINIT_SECパラメータ

パラメータ	タイプ	データ・タイプ	説明
`CONVID`	`OUT`	`RAW(12)`	SNAを使用するゲートウェイの場合: `PGAXFER`および`PGATERM`関数への会話を識別するために使用される`PGAINIT`関数によって返される会話識別子。 `PGAINIT`が呼び出された後、この変数を変更してはいけません。そうでないと結果が予測できなくなります。 TCP/IPを使用するゲートウェイの場合: `PGAXFER`および`PGATERM`関数への会話を識別するために使用される`PGAINIT`関数によって返されるソケット・ファイル記述子。 `PGAINIT`が呼び出された後、この変数を変更してはいけません。そうでないと結果が予測できなくなります。
`TPNAME`	`IN`	`VARCHAR2(64)`	会話を確立するためのリモート・トランザクション・プログラムのトランザクション・プログラム名。ほとんどのOLTPでは、名前はOLTPに定義されたトランザクション名でなければなりません。この名前は、`1`から`64`文字までの長さにすることができます。「注意: TCP/IPのサポート」、最大サイズは8文字です。詳細については、または「Oracle Database Gateway for APPCインストールと構成ガイドfor Microsoft Windows」の付録B、"TCP/IP通信プロトコルのゲートウェイ初期化パラメータ"を参照してください。
`LUNAME`	`IN`	`VARCHAR2(17)`	SNAを使用するゲートウェイの場合:リモート・トランザクション・プログラムが実行されるOLTPのLU名。このパラメータは、完全修飾LU名または別名で、1〜17文字の長さにすることができます。 TCP/IPを使用するゲートウェイの場合: このパラメータは適用されません。
`MODENAME`	`IN`	`VARCHAR2(8)`	SNAを使用するゲートウェイの場合: APPC会話のセッション特性を定義するリモート・ホスト上のログ・モード表項目のログ・モード項目名。この名前の長さは1〜8文字です。 TCP/IPを使用するゲートウェイの場合:このパラメータは適用されません。
`PROFNAME`	`IN`	`VARCHAR2(8)`	会話を定義するSNAサイド情報プロファイルのプロファイル名。この名前の長さは1〜8文字です。 TCP/IPを使用するゲートウェイの場合:この名前は、同様のTCP/IPとIMS Connect属性に類似したIMSトランザクションのグループを表します。
`SYNCLEVEL`	`IN`	`CHAR(1)`	この会話のための`SYNCLEVEL`。この値は'0'または'1'のいずれかでなければなりません。 `SYNCLEVEL 0`は、リモート・トランザクション・プログラムに同期機能がないことを示します。 `SYNCLEVEL 1`は、リモート・トランザクション・プログラムが`CONFIRM`リクエストに応答できることを示し、リモート・トランザクション・プログラムがリモート・ホスト上のデータベースを更新しているときにデータの整合性を保証するために使用されます。

「表B-3」は、プロシージャに固有のPGAINIT_SECパラメータをリストします:

表B-3プロシージャ固有のPGAINIT_SECパラメータ

パラメータ	タイプ	データ型	説明
`USERID`	`IN`	`VARCHAR2(8)`	ターゲットOLTPに渡す会話セキュリティ・ユーザーID。値は1〜8文字の長さでなければなりません。
`PASSWORD`	`IN`	`VARCHAR2(8)`	ターゲットOLTPに渡す会話セキュリティ・パスワード。値は1〜8文字の長さでなければなりません。

SNAプロトコルを使用するゲートウェイの場合:

PROFNAMEとLUNAME/TPNAME/MODENAMEの間には相互関係があります。 PROFNAMEが空白またはヌル値に設定されている場合、LUNAME、TPNAME、およびMODENAMEパラメータはすべて非ブランク値である必要があります。すべてが空白でない値に設定されていない場合は、例外が生成されます。ただし、PROFNAMEが有効なSide情報プロファイル名に設定されている場合、LUNAME、TPNAME、およびMODENAMEパラメータは、サイド情報プロファイルが会話を確立するために必要なすべての情報を指定するため、nullまたは空白にすることができます。この場合、LUNAME、TPNAME、またはMODENAMEに指定された空白でないnull以外の値は、サイド情報profile. PROFNAMEに設定された値をオーバーライドする必要があります。ブランクまたはヌルにすることはできません。

TCP/IPプロトコルを使用するゲートウェイの場合:

PROFNAMEおよびTPNAMEは設定する必要があり、空白またはヌルにすることはできません。

PGAXFER

PGAXFERは、PGAINITで初期化されたゲートウェイの会話でリモート・トランザクション・プログラムとの間でデータを転送するために呼び出されます。この関数は、呼び出しパラメータに基づいてデータ・アイテムを送信および/または受信します。

「表B-4」は、PGAXFERパラメータのタイプ、データ型および説明をリストします:

表B-4 PGAXFERパラメータ

パラメータ	タイプ	データ型	説明
`CONVID`	`IN`	`RAW(12)`	SNAを使用するゲートウェイの場合:会話を識別するために使用される`PGAINIT`関数によって返される会話識別子。 TCP/IPを使用するゲートウェイの場合:会話を識別するために使用される`PGAINIT`関数によって返されるソケット・ファイル記述子。
`SENDBUF`	`IN`	`RAW(32763)`	リモート・トランザクション・プログラムに送信されるすべてのデータ・アイテムを含むバッファ。データ・アイテムは変更なしでそのまま送信されます。データ・アイテムは、リモート・トランザクション・プログラムが受け取ることを期待する順序でバッファに表示する必要があります。すべてのデータ・アイテムの合計サイズは、1つのゲートウェイ送信の最大サイズを超えることはできません。これは、マップされたゲートウェイ通信の `32,763`バイトです。
`SENDBUFL`	`IN`	`BINARY_INTEGER`	`SENDBUF`に含まれるデータ・アイテムの合計長。範囲は`0`です-`32,763` bytes. 送信するデータ・アイテムがない場合、'`0`'の値が使用されます。
`SENDLNS`	`IN`	`RAW(1024)`	`256`までの4バイト整数値の配列を含むバッファ。最初の整数値は、送信バッファに含まれるデータ・アイテムの数を指定します(`SENDBUF`)。その後、データ・アイテム数は、データ・アイテムの長さを指定する一連の整数値です。データ・アイテム数とデータ・アイテム長値の数の間には完全な一致がなければなりません。 `255`までのデータ・アイテムをこの配列で記述することができます。すべてのデータ・アイテムの長さの合計は、`SENDBUFL`の合計長を超えることはできません。
`RECVBUF`	`OUT`	`RAW(32763)`	リモート・トランザクション・プログラムから受信したすべてのデータ・アイテムを格納するバッファ。データ・アイテムは、リモート・トランザクション・プログラムがそれらを送信するのと同じ順序でこのバッファに格納されます。すべてのデータ・アイテムの合計サイズは、`32,763` バイトの最大サイズを超えることはできません。
`RECVBUFL`	`IN`	`BINARY_INTEGER`	受信バッファの合計長。範囲は`0`です-`32,763` bytes. 受信するデータ・アイテムがない場合、'`0`'の値が使用されます。
`RECVLNS`	`INOUT`	`RAW(1024)`	`256`までの4バイト整数値の配列を含むバッファ。最初の整数値は、受信バッファに受信するデータ・アイテムの数を指定します(`RECVBUF`)。データ・アイテム数の後には、受信するデータ・アイテムの最大長を指定する一連の整数値があります。出力時には、これらの値は受信したデータ・アイテムの実際の長さに置き換えられます。データ・アイテム数とデータ・アイテム長値の数の間には完全な一致がなければなりません。 `255`までのデータ・アイテムをこの配列で記述することができます。すべてのデータ・アイテムの長さの合計は、受信バッファ(`RECVBUFL`)の合計長を超えることはできません。

PGAXFERが呼び出されると、SENDBUFLとRECVBUFLの一方または両方がゼロでない必要があります。言い換えれば、少なくとも1つのデータ・アイテムをリモート・トランザクション・プログラムと送受信する必要があります。 PGAXFERが送信または受信するデータ・アイテムなしで呼び出された場合、例外が生成されます。

注意:

各PGAXFERコールでは、すべての送信処理が最初に行われ、続いてすべての受信処理が行われます。トランザクションが送受信の複数のセットを必要とするように動作する場合、PGAXFERはトランザクションを受け入れるために複数回呼び出すことができます。 32,763バイト以上のデータを送受信する場合は、PGAXFERへの複数の呼び出しを行う必要があります。

PGATERM

PGATERMは、以前のPGAINITの呼び出しによって開始されたゲートウェイの会話を終了するために呼び出されます。この機能が正常に完了すると、会話の割り当てが解除され、会話に関連するすべてのストレージが解放されます。

「表B-5」は、PGATERMパラメータのタイプ、データ型、および説明を表示します:

表B-5 PGATERMのパラメータ

パラメータタイプデータ型説明

パラメータ	タイプ	データ型	説明
`CONVID`	`IN`	`RAW(12)`	SNAを使用するゲートウェイの場合:会話を識別するために使用される`PGAINIT`関数によって返される会話識別子。使用するゲートウェイの場合 TCP/IP: 会話を識別するために使用される`PGAINIT`関数によって返されるソケット・ファイル記述子。
`TERMTYPE`	`IN`	`CHAR(1)`	実行されるべき終端のタイプ。`0`は正常終了を示し、`1`は異常終了を示し、エラーがある場合にのみリクエストされます。

CONVID

IN

RAW(12)

SNAを使用するゲートウェイの場合:会話を識別するために使用されるPGAINIT関数によって返される会話識別子。

使用するゲートウェイの場合 TCP/IP: 会話を識別するために使用されるPGAINIT関数によって返されるソケット・ファイル記述子。

TERMTYPE

IN

CHAR(1)

実行されるべき終端のタイプ。0は正常終了を示し、1は異常終了を示し、エラーがある場合にのみリクエストされます。

PGATCTL

PGATCTLは、UNIXベースのシステム上のMicrosoftまたは$ORACLE_HOME/dg4appc/admin/initsid.oraファイルの%ORACLE_HOME%\dg4appc\admin\initsid.oraファイルのTRACE_LEVELパラメータによって呼び出されます。 PGATCTLを使用すると、PL/SQLストアド・プロシージャ内からトレース・レベルを動的に変更できます。この機能は、新しいPL/SQLアプリケーションをデバッグする場合に便利です。

表B-6は、PGATCTLのパラメータの型、データ型、および説明を表示します:

表B-6 PGATCTLのパラメータ

パラメータタイプデータ型説明

パラメータ	タイプ	データ型	説明
`CONVID`	`IN`	`RAW(12)`	SNAを使用するゲートウェイの場合: 会話を識別するために使用される`PGAINIT`関数によって返される会話識別子。使用するゲートウェイの場合 TCP/IP: 会話を識別するために使用される`PGAINIT`関数によって返されるソケット・ファイル記述子。
`TRFUNC`	`IN`	`CHAR(1)`	トレース制御機能を実行します。有効な値は次のとおりです。 ' `S` ' - トレース・フラグを`TRFLAGS`パラメータで指定された正確な値に設定します。 ' `E` ' - 他のフラグを変更することなく、`TRFLAGS`パラメータで指定されたトレース・フラグを使用可能にします。 ' `D` ' - 他のフラグを変更せずに、`TRFLAGS`パラメータで指定されたトレース・フラグを使用不可にします。
`TRFLAGS`	`IN`	`BINARY_INTEGER`	トレース・フラグ。 `TRACE_LEVEL`をオンにします。ご使用のプロトコルがSNAの場合の詳細については、付録A、"SNAプロトコルのゲートウェイ初期化パラメータ" (または「Oracle Database Gateway for APPCインストールと構成ガイドfor Microsoft Windows」)を参照してください。または「Oracle Database Gateway for APPCインストールと構成ガイドfor Microsoft Windows」の付録B、"TCP/IP通信プロトコルのゲートウェイ初期化パラメータ"を参照してください。

CONVID

IN

RAW(12)

SNAを使用するゲートウェイの場合: 会話を識別するために使用されるPGAINIT関数によって返される会話識別子。

使用するゲートウェイの場合 TCP/IP: 会話を識別するために使用されるPGAINIT関数によって返されるソケット・ファイル記述子。

TRFUNC

IN

CHAR(1)

トレース制御機能を実行します。有効な値は次のとおりです。

' S ' - トレース・フラグをTRFLAGSパラメータで指定された正確な値に設定します。

' E ' - 他のフラグを変更することなく、TRFLAGSパラメータで指定されたトレース・フラグを使用可能にします。

' D ' - 他のフラグを変更せずに、TRFLAGSパラメータで指定されたトレース・フラグを使用不可にします。

TRFLAGS

IN

BINARY_INTEGER

トレース・フラグ。

TRACE_LEVELをオンにします。ご使用のプロトコルがSNAの場合の詳細については、付録A、"SNAプロトコルのゲートウェイ初期化パラメータ" (または「Oracle Database Gateway for APPCインストールと構成ガイドfor Microsoft Windows」)を参照してください。

または「Oracle Database Gateway for APPCインストールと構成ガイドfor Microsoft Windows」の付録B、"TCP/IP通信プロトコルのゲートウェイ初期化パラメータ"を参照してください。

PGATRAC

この関数は、ユーザー・データの行をPGAトレース・ファイルに書き込むために呼び出されます。 PGATRACを使用すると、PL/SQLプロシージャ内のフローは、UNIXベースのシステム上のMicrosoft Windowsまたは$ORACLE_HOME/dg4appc/admin/initsid.oraの%ORACLE_HOME%\dg4appc\admin\initsid.oraのTRACE_LEVELに基づいて、トレースされたイベントとともにトレースできます。これは、新しいPL/SQLアプリケーションを開発するときに便利なデバッギング・ツールです。

「表B-7」は、PGATRACパラメータのタイプ、データ型、および説明を表示します:

表B-7 PGATRACパラメータ

パラメータ	タイプ	データ型	説明
`TRDATA`	`IN`	`VARCHAR2(120)`	ゲートウェイ・トレース・ファイルに書き込まれるユーザー・データの行。内容は印刷可能な文字でなければなりません。