Oracle TMA TCP for IMSのプログラミング

Oracle Tuxedo Mainframe Adapter for TCP (IMS)(以後TMA TCP for IMSと呼ぶ)では、リモート・システムから受信されたリクエスト(サーバー・リクエスト)に対するサービスの提供と、リモート・システムが提供するサービスに対するリクエスト(クライアント・リクエスト)の開始を行うIMSアプリケーション・トランザクションをユーザーが作成できます。

次のトピックでプログラミングに関する留意事項について説明します。

•	アプリケーションのプログラミング

•	プログラミング・インタフェース

•

レスポンスの送信

•	IMSクライアント・リクエスト

•

エラー処理

•	Oracle TMA TCP Gatewayによるデータ変換の仕組み

アプリケーションのプログラミング

IMSクライアントとサーバーのトランザクションは通常のIMSメッセージ処理プログラム(MPP)であり、OTMAと連携するときには、サーバー・トランザクションはFastPathプログラムにもなります。これらのプログラムは、IMSでサポートされている任意のプログラミング言語で記述できます。COBOLはこの目的で使用されている従来からの言語であるため、このドキュメントの例はCOBOLで記載します。しかし、各例は、Cなどサポートされている他の言語に容易に移行できます。

プログラミング・インタフェース

TMA TCP for IMS製品とユーザー作成のIMSクライアントおよびサーバー・トランザクションは、標準のIMSメッセージを(IMSメッセージ・キューを直接使用するか、OTMAを介して)交換することによって通信します。

IMSサーバー・リクエスト

IMSサーバー・トランザクションは、リモート・システムからのリクエストに対してサービスを提供するトランザクションです。リクエスト・メッセージは、1つのセグメントとして、IMSメッセージ・キューに直接挿入されるか、またはOTMAを介して間接的に挿入されます。IMSサーバー・トランザクションは、必要に応じて、IMSメッセージ・キューからリクエスト・メッセージを取得し、リクエストを処理します。

メッセージ・フォーマット

TMA TCP GatewayをOTMAクライアントとして実行する場合、リクエストまたはレスポンスのメッセージは標準のIMSメッセージ・フォーマットになります。次のメッセージは、OTMAを使用する場合のサンプルです。

リスト6-1 OTMAを使用する場合のメッセージのサンプル

01 BEA-SERVER-REQUEST-RESPONSE-MESSAGE.
05 BEA-SERVER-HEADER
10 LL PIC 9(4) COMP VALUE 0.
10 ZZ PIC 9(4) COMP VALUE 0.
10 TRAN-CODE PIC X(8) VALUE SPACES.
REQUEST-DATA.

 

フィールドの説明

リクエスト・メッセージ内のフィールドは次のとおりです。

 

フィールド	説明
LL	リクエストまたはレスポンス・メッセージ全体の長さ(このフィールドを含む)。
ZZ	IMSによって使用されるために予約されています。通常はゼロです。
TRAN-CODE	リクエスト・メッセージの場合は、IMSサーバーのトランザクション・コード。レスポンス・メッセージの場合は、TMA TCP for IMSゲートウェイのトランザクション・コード。
FILL-CHAR	メッセージを満たす文字(空白文字)。

ヘッダー・ファイルとコピーブック

INCLUDE配布ライブラリには、IMSサーバー・トランザクションで使用することを目的とした次のヘッダー・ファイルとコピーブックが収録されています。

 

メンバー名	説明
BEATCPI	Cヘッダー・ファイル
SERVER	COBOLコピーブック

レスポンスの送信

レスポンスが要求されている場合は、サーバー・トランザクションがクライアント・レスポンス・メッセージをフォーマットします。

OTMAクライアント・ゲートウェイ

サーバー・トランザクションに渡されるリクエスト・メッセージには、I/O PCBのLTERMフィールド内にあるトランザクション・パイプ(tpipe)の名前が格納されます。セキュリティ機能を使用している場合は、I/O PCBのUSERIDフィールドとGROUPIDフィールドにも、それに関連するデータが格納されます。

レスポンスが要求されている場合は、レスポンス・メッセージがIMSメッセージ・キューに挿入され、OTMAからゲートウェイに戻されます。レスポンス・メッセージは1つのセグメントまたは複数のセグメントとして挿入されます。TMA TCP for IMSゲートウェイはどちらのフォーマットでも処理できます。

IMSクライアント・リクエスト

IMSクライアント・トランザクションは、リモート・システムが提供するサービスに対するリクエストを発行するトランザクションです。IMSクライアント・トランザクションとOTMAクライアント・ゲートウェイを使用する前に、DFSYPRX0およびDFSYDRU0 IMSユーザー・イグジットをインストールする必要があります。これらのユーザー・イグジットに関する詳細は、IBM社のドキュメント『Open Transaction Manager Access Guide』を参照してください。これらのイグジットの基本的なサンプルは、「JCLおよびユーザー・イグジットのサンプル」の項を参照してください。

メッセージ・フォーマット

TMA TCP for IMSのクライアント・リクエストまたはレスポンスのメッセージは、次の連続する3つのセクションで構成されます。

•	BEA仕様のリクエスト/レスポンスのヘッダー

•	ユーザー定義のコンテキスト・データ

•	ユーザー定義のリクエストまたはレスポンスのデータ

TMA TCP for IMSクライアントのリクエストまたはレスポンスのメッセージは次のフォーマットになっています。

リスト6-2 クライアント・リクエスト/レスポンスのメッセージのフォーマット

01 BEA-CLIENT-REQUEST-RESPONSE-MESSAGE.
05 BEA-CLIENT-HEADER.
10 LL PIC 9(04) COMP VALUE 0.
10 ZZ PIC 9(04) COMP VALUE 0.
10 TRAN-CODE PIC X(08) VALUE SPACES.
10 FILL-CHAR PIC X VALUE SPACES.
10 BEA-RESERVED-1 PIC X(03) VALUE LOW-VALUES.
10 HEADER-LENGTH PIC 9(08) COMP VALUE 0. .
10 CONTEXT-LENGTH PIC 9(08) COMP VALUE 0.
10 DATA-LENGTH PIC 9(08) COMP VALUE 0.
10 MAX-RESPONSE-LENGTH PIC 9(08) COMP VALUE 0.
10 REQUEST-TYPE PIC 9(08) COMP VALUE 0.
88 REQUEST-RESPONSE-REQUIRED VALUE 1.
88 REQUEST-NO-RESPONSE VALUE 2.
10 RESPONSE-FORMAT PIC 9(08) COMP VALUE 0.
88 RESPONSE-SINGLE-SEGMENT VALUE 0.
88 RESPONSE-MULTI-SEGMENT VALUE 1.
10 ERROR-CODE PIC S9(08) COMP VALUE +0.
88 ERR_NO_ERROR VALUE +0.
88 ERR_RESPONSE_TRUNCATED VALUE +4.
88 ERR_HOST_NOT_AVAILABLE VALUE +8.
88 ERR_HOST_BUSY VALUE 12.
88 ERR_TIMEOUT VALUE 16.
88 ERR_SERVICE_NAME VALUE 20.
88 ERR_NO_STORAGE VALUE 24.
88 ERR_REQUEST_FORMAT VALUE 28.
88 ERR_HOST_ERROR VALUE 32.
88 ERR_TP_ERROR VALUE 36.
88 ERR_INTERNAL_ERROR VALUE 40.
10 REASON-CODE PIC S9(08) COMP VALUE +0.
88 RSN_NO_REASON VALUE 0.
88 RSN_HEADER_LENGTH VALUE 4.
88 RSN_HEADER_LENGTHS VALUE 8.
88 RSN_REQUEST_TYPE VALUE 12.
88 RSN_NO_RESPONSE_TRAN VALUE 16.
88 RSN_CONTEXT_LENGTH VALUE 20.
88 RSN_DATA_LENGTH VALUE 24.
88 RSN_MAX_DATA_LENGTH VALUE 28.
88 RSN_NO_SERVICE_NAME VALUE 32.
88 RSN_SERVICE_NAME_UNDEFINED VALUE 36.
10 SERVICE-NAME PIC X(16) VALUE SPACES.
10 RESPONSE-TRAN PIC X(08) VALUE SPACES.
10 ORIGIN-TERMINAL PIC X(08) VALUE SPACES.
10 BEA-RESERVED-2 PIC X(16) VALUE LOW-VALUES.
05 USER-CONTEXT-DATA.
10 (user-defined...)|
05 USER-REQUEST-DATA.
10 (user-defined...)
05 USER-RESPONSE-DATA REDEFINES USER-REQUEST-DATA.
10 (user-defined...)

 

フィールドの説明

クライアント・リクエストまたはレスポンスのメッセージのフィールドは次のとおりです。

 

フィールド	説明
LL	リクエストまたはレスポンス・メッセージ全体の長さ(このフィールドを含む)。
ZZ	IMSによって使用されるために予約されています。通常はゼロです。
TRAN-CODE	リクエスト・メッセージの場合は、TMA TCP for IMSゲートウェイのトランザクション・コード。レスポンス・メッセージの場合は、IMSクライアント・レスポンス・トランザクションのトランザクション・コード。
FILL-CHAR	メッセージを満たす文字(空白文字)。
BEA-RESERVED-1	TMA TCP for IMSによる使用のために予約されています。リクエスト・メッセージの場合は、このフィールドをバイナリ・ゼロ(ロー・バリュー)に初期化する必要があります。
HEADER-LENGTH	BEAリクエスト/レスポンスのヘッダーの長さ。
CONTEXT-LENGTH	ユーザーのコンテキスト・データの長さ(ある場合)。コンテキスト・データがない場合、長さはゼロに設定されます。
DATA-LENGTH	ユーザーのリクエストまたはレスポンスのデータの長さ(ある場合)。リクエストまたはレスポンスのデータがない場合、長さはゼロに設定されます。
MAX-RESPONSE-LENGTH	リクエストの場合の受入れ可能なユーザーのレスポンス・データの最大長。レスポンス・データがこの長さを超えた場合は、必要な分だけ切り取られ、該当する戻りコードが設定されます。
REQUEST-TYPE	リクエストの場合の、レスポンスの必要性の有無を示します。 レスポンスの必要がない場合、TMA TCP for IMSは、リクエストがリモート・システムに送信されると同時に、指定のレスポンス・トランザクションを送信するようにスケジュールします。 そうでない場合は、必要なレスポンスをリモート・システムから受信したときにレスポンス・トランザクションを送信するようにスケジュールします。
RESPONSE-FORMAT	リクエストの場合の、要求されているレスポンス・メッセージのフォーマットのタイプを示します。 単一セグメントのオプションが指定されている場合(デフォルト)、TMA TCP for IMSは、レスポンス・メッセージ全体を1つのメッセージ・セグメントとしてIMSメッセージ・キューに挿入します。 マルチセグメント・オプションがリクエストされている場合、レスポンス・メッセージは3つのセグメントに分けられてIMSメッセージ・キューに挿入されます。 1. レスポンスのヘッダー 2. ユーザー・コンテキスト・データ 3. ユーザーのレスポンス・データ
ERROR-CODE	このフィールドは、エラーが発生していることを示すために、レスポンス・メッセージ内に設定されます。このフィールドがゼロの場合、リクエストは正常に処理されています。そうでない場合、エラー・コードは、発生したエラーの性質を示します。 エラー・コードについては、「エラー・コードと理由コード」の項で説明しています。
REASON-CODE	特定タイプのエラーが発生した場合、このフィールドはエラーに関する補足情報を示すように設定されることがあります。このフィールドがゼロの場合、補足情報はありません。 理由コードについては、「エラー・コードと理由コード」の項で説明しています。
SERVICE-NAME	リクエストを処理するサービスの名前(TMA TCP for IMSにローカルに定義されている名前)を示します。ローカル・サービス名はリモート・システムの名前とは異なる場合もあることに注意してください。
RESPONSE-TRAN	リクエストに対するレスポンスを処理するようにスケジュールされているトランザクションの名前(IMSトランザクション・コード)。アプリケーション・レベルのレスポンスを要求しない場合でも、すべてのリクエストにレスポンス・トランザクションを指定する必要があります。
ORIGIN-TERMINAL	このリクエストに関連付けられている端末の名前(IMS LTERM)。たとえば、端末メッセージを処理するトランザクションからリクエストが発行される場合、この名前は、関連付けられている端末の名前になります。
BEA-RESERVED-2	TMA TCP for IMSによる使用のために予約されています。リクエスト・メッセージの場合は、このフィールドをバイナリ・ゼロ(ロー・バリュー)に初期化する必要があります。
USER-CONTEXT-DATA	このユーザー定義のデータ領域は、TMA TCP for IMSから渡され、レスポンス・メッセージで戻されます。このデータは様々な目的で使用できます。たとえば、レスポンス・トランザクションは、レスポンスと元のリクエストの関連付けに、このデータを使用できます。コンテキスト・データがある場合は、途中にバイト(空き領域)を挟まずにBEAリクエスト・ヘッダーの直後からこの領域を続ける必要があります。
USER-REQUEST-DATA	リクエスト・メッセージの場合のリクエストに固有なユーザー定義データ。リクエスト・データがある場合は、途中にバイト(空き領域)を挟まずに、コンテキスト・データ(ある場合)の直後からこの領域を続ける必要があります。
USER-RESPONSE-DATA	レスポンス・メッセージの場合のレスポンスに固有なユーザー定義データ。レスポンス・データがある場合は、途中にバイト(空き領域)を挟まずに、コンテキスト・データ(ある場合)の直後からこの領域を続ける必要があります。

ヘッダー・ファイルとコピーブック

INCLUDE配布ライブラリには、IMSクライアント・トランザクションで使用することを目的とした次のヘッダー・ファイルとコピーブックが収録されています。

 

メンバー名	説明
BEATCPI	Cヘッダー・ファイル
SERVER	COBOLコピーブック

エラー処理

どのクライアント・リクエストも所定のレスポンス・トランザクションが関連付けられている必要があります(リクエスト自体にはアプリケーション・レベルのレスポンスが要求されていないとしても)。TMA TCP for IMS製品は、エラーが発生してリクエストを処理できない場合に備えて、レスポンス・トランザクションをスケジュールします(たとえば、リクエストが正しくフォーマットされていない可能性がある場合、指定サービスが使用できない可能性がある場合など)。

レスポンス・トランザクションは常にエラー・コードをチェックし、リクエストが正常に処理されたかどうかを確認する必要があります。

エラー・タイプ

TMA TCP for IMS製品は、クライアント・リクエストの正常な処理を阻害する可能性のある様々なタイプのエラー状態を認識します。これらを大別すると次のようになります。

無効なリクエスト・フォーマット

TMA TCP for IMSゲートウェイは、クライアント・リクエストを処理先のリモート・システムに送信する前に検証します。検証エラーのタイプとしては、無効なサービス名、無効な長さ値などがあります。

リモート・システムを使用できない

必要なリモート・システムがアクセス不可能な状態になっているか、現在別のリクエストを処理していてビジーになっているため、TMA TCP for IMSゲートウェイがリクエストを処理できないことがあります。

リクエスト・タイムアウト

TMA TCP for IMSゲートウェイは、処理先のリモート・システムに送信される各リクエストを監視します。レスポンスが要求されており、規定の時間内に受信されない場合、リクエストはタイムアウトになります。

リモート・システムのエラー

リモート・システムでエラーが発生したため、リクエストが失敗することがあります。たとえば、リクエスト対象のサービスがアプリケーション・レベルのエラー、セキュリティ認証の失敗を検出することもあれば、リモート・ゲートウェイがリクエスト対象のサービスの呼出しに失敗することもあります。

その他のエラー

発生することはごく稀ですが、一時的な記憶域が容量不足になったために、TMA TCP for IMSがリクエストを処理できなくなることもあります。

Oracle TMA TCP Gatewayによるデータ変換の仕組み

リモートのOracle Tuxedoシステム上のクライアント・プログラムが異なるモデルのコンピュータ上のサービス・ルーチンとの間でデータを送受信するときに、データは必要に応じてTMA TCP Gatewayによって自動的に変換されます。変換の処理内容は、次に示すような属性を変更して、そのデータ型本来の表現をそのまま移し替えることです。

•

ワード長

•

バイト・オーダー

Oracle Tuxedoのバッファ・タイプ

次の表にバッファ・タイプの定義を示します。

 

用語	定義
STRING	文字データのバッファであり、バッファ内の最初のNULL文字で終了します。送信元と送信先のシステムのタイプが異なる場合は、通常、これらの文字列のバッファは変換の対象になります。
CARRAY	CARRAYは、終端文字を含まない純粋なデータのみのバッファです。配列内のデータは変換の対象にはなりません。したがって、システム間で送信されるデータは変更されません。(CARRAYは、グラフィック関連ファイルの場合によく使用されるバッファのタイプです。)
VIEW	VIEWバッファは1つのエントリとして扱うことが可能なフィールド定義の集まりです。これは、COBOLのレコード型とCの構造体に相当します。
FML	フィールド操作言語(FML)バッファは、可変長で動的な自己記述型のバッファです。バッファ内のフィールドごとにその属性を表す専用のヘッダーが関連付けられます。Oracle Tuxedo製品では、FMLバッファとVIEWバッファは密接な関係にあり、相互に直接変更できます。

データ変換のルール

TMA TCP Gatewayは次のデータ変換ルールに従います。

•	CARRAYフィールドは、そのままのバイトの並びで変換されずに渡されます。

•	STRINGおよびCHARフィールドは(必要に応じて)ASCIIからEBCDICに変換されます。

•	SHORTおよびLONGフィールドはそれぞれ、S9(4) COMPとS9(9) COMPに変換されます。

•	FLOATおよびDOUBLEフィールドはそれぞれ、COMP-1とCOMP-2に変換されます。

注意:	Oracle Tuxedo製品には、VIEW内に、10進数値をサポートするdec_t_tという名前のフィールド・タイプがあります。TMA TCP for IMSゲートウェイは、これらのフィールドをマシンに依存しない表現形態であるパック10進数に変換します。たとえば、dec_t(m,n)とすると、S9(2*m-(n+1))V9(n) COMP-3という結果になります。したがって、8,5というサイズの10進数のフィールドはS9(10)V9(5) COMP-3になります。

次の表に、Cのデータ型とIBM/370のデータ型との間の変換ルールをまとめています。

 

リモートのデータ型	説明	VIEWのフィールドの タイプ/長さ
PIC X(n)	英数字	string / n
PIC X	英数字1文字	char
PIC X(n)	ロー・バイト	carray / n
PIC 9	1バイト数値	carray / 1
PIC S9(4) COMP	32ビットの整数	Short
PIC S9(9) COMP	64ビットの整数	long
COMP-1	単精度浮動小数点	float
COMP-2	倍精度浮動小数点	double
PIC S9((m+(n+1))/2)V9(n) COMP-3	パック10進数	dec_t / m,n

 

文字列データと数値データの詳細

この項では、次の情報について説明します。

•	入出力バッファおよびレコードのVIEW定義の開発に役立つ情報

•	TMA TCP Gatewayにおける文字列データと数値データの扱われ方についての説明

NULL文字を含む文字列長の計算

IMSアプリケーションによって使用される入出力バッファのVIEW定義を作成する際に、文字列フィールドで使用されるNULL終端文字を含む余分な部分まで指定しないでください。

たとえば、リモートのIMSアプリケーション・プログラム側では入力レコードの文字数が10文字であることを前提としている場合は、そのフィールドには、10+1 (NULL終端文字も含む長さ)ではなく、10と指定してください。

注意:	TMA TCP Gatewayでは文字列のNULL終端は不要ですが、NULL終端文字があれば文字列の終了と見なされます。したがって、TMA TCP Gatewayは、文字列内にNULL(ゼロ)文字を検出すると、その以降の文字を処理しません。NULL値が埋め込まれた8ビットのデータ全体を渡す場合は、CARRAYタイプのフィールドまたはバッファを使用してください。

TMA TCP Gatewayによって実行される文字セットの変換は、X/Openポータビリティ・ガイドに従って、全面的に各国の言語に対応させることができます。ASCIIとEBCDICとの間の変換は、メッセージ・ファイルから読み込むことができます。TMA TCP Gateway製品のデフォルトの動作で、ほとんどの英語版のアプリケーションの要件を満たすはずです。しかし、表のカスタマイズが必要になることもあります。詳細な手順は、Oracle Tuxedo Mainframe Adapter for TCP Gatewayユーザーズ・ガイドを参照してください。

数値データの変換

中間データの型と変換先の型で表現可能な範囲な中に、表現する必要がある最大値が収まるのであれば、数値データを別のデータ型に簡単に変換できます。

たとえば、double型のFMLフィールドをリモートの送信先システム環境のパック10進数フィールドに変換するには、その処理に適したdec_t type VIEW要素を指定します。

また、数値と文字列との間でも変換が可能です。たとえば、FMLバッファをdec_t型に直接変換することはできませんが、10進数値を文字列フィールドに格納し、そのフィールドをVIEW定義のdec_tフィールドにマップすることができます。