Oracle Tuxedo Mainframe Adapter for TCP (CICS)のプログラミング

次の項では、CICSプログラマがOracle Tuxedo Mainframe Adapter for TCP (CICS)(以後TMA TCP for CICSと呼ぶ)と連携するアプリケーション・プログラムを開発または変更する際に注意する必要がある事項について説明しています。

•	クライアント・アプリケーションに関する注意事項

•	サーバー・アプリケーションに関する注意事項

クライアント・アプリケーションに関する注意事項

次の項から、CICSプログラマがTMA TCP for CICSをクライアントとして相互運用するアプリケーション・プログラムを開発または変更する際に注意する必要がある事項について説明しています。

CICSアプリケーション・プログラムからリモートのOracle Tuxedoドメインにリクエストを送信するには、EXEC CICS LINKコマンドを使用します。リクエスト・データとレスポンス・データの正確なレイアウトについては、後述する項で説明します。

バッファのレイアウトに関する注意事項

構成の整合性と正当性を確保するために、CICSとOracle Tuxedo間で送信されるデータ・バッファのレイアウトについて、CICSアプリケーション・プログラマ、Oracle Tuxedoアプリケーション開発者およびOracle Tuxedo管理者との間の合意が必要です。COBOLやCに備わっているデータ型を使用しているかぎり、CICSプログラマに制限事項は課されません。

CICSクライアント・プログラムからの呼出し

CICSプログラムからリモートのOracle Tuxedoドメインに対してサービス呼出しを実行するには、EXEC CICS LINK呼出しを前処理リクエスタに送信します。アクセス対象にするサービスは、Oracle TMA管理者が構成する必要がありますが、プログラミングに限って言えば、必要な手続きはLINK呼出しのみです。次のCOBOLレコードは、client.cblというCOBOLのコピーブックに収録されています。

リスト5-1 COBOLレコード

01 REQUEST-RECORD.
05 REQUEST-HEADER.
10 DATALEN PIC S9(08) COMP.
10 SVCNAME[16] PIC X(16).
10 REQUESTCD PIC S9(08) COMP.
10 RETURNCD PIC S9(08) COMP.
10 REQRETURNCD PIC S9(08) COMP.
05 REQUEST-DATA.
10 DATA-AREA PIC X(DATALEN).

 

LINK呼出しに渡すCの構造体のレイアウトは、リスト5-2に示すとおりです。次のCの構造体は、clienth.hというインクルード・ファイルに収録されています。

リスト5-2 Cの構造体

typedef struct CLIENTHDR
{
long DataLen; /* THE LEN OF THE DATA FROM AND TO APPL */
char SvcName[16]; /* THE SERVICE NAME */
long RequestCd; /* THE REQUEST COMMAND FROM THE APPL */
long ReturnCd; /* THE RETURN CODE TO THE APPL */
long ReqReturnCd; /* THE RETURN CODE FROM THE PREQ AND REQ */
} CLIENTHDR;

typedef struct CMAREA
{
CLIENTHDR CltHdr; /*HEADER */
char Request_data[MAX_DATA_LENGTH]; /* REQUEST DATA */
} CMAREA;

 

前述のCOBOLとCのサンプルの変数は、次のような定義内容になっています。

DataLen

Request_dataフィールドのデータの長さ。

SvcName

サービス・リクエスト名(名前については管理者に確認してください)。

RequestCd

この呼出しのタイプを示す、あらかじめ定義されている数値。

BEA_REQUEST_NORESPONSE: 値は7です。応答なしのサービス・リクエスト。この場合、サービスを実行するOracle Tuxedoにリクエストが送信されますが、レスポンス・データは返されません。

BEA_REQUEST_RESPONSE: 値は5です。リクエストまたはレスポンス・リクエスト。リクエストはOracle Tuxedoに送信され、レスポンスが返されます。

 

表5-1 リクエストのコード

コード	値
BEA-REQUEST-RESPONSE	+5.
BEA-REQUEST-NORESPONSE	+7.

ReturnCd

このコードは、CICSのリクエスタから戻される戻りコードです。

次の表に、すべての戻りコードを示します。戻りコードが処理またはネットワークの問題を示す場合は、管理者に問い合せてください。

注意:	これらのコードに関する説明については、付録Aの「CICSクライアント・プログラムに戻されるコード」の項を参照してください。

 

表5-2 戻りコード

コード	値
BEA-NORMAL	+0.
BEA-ERR-LENGTH	+1.
BEA-ERR-MISSING-SRV-NAME	+2.
BEA-ERR-REQ-CODE	+3.
BEA-ERR-SRC-NOT-FOUND	+4.
BEA-ERR-READ-UMT	+5.
BEA-ERR-SERVER	+6.
BEA-ERR-POST	+7.
BEA-ERR-CANCEL	+8.
BEA-ERR-WAIT	+9.
BEA-ERR-LMID-NOT-FOUND	+10.
BEA-ERR-START-TRANSID	+11.
BEA-ERR-DISABLE-ACQUIRING	+12.
BEA-ERR-DISABLE-NOT-FND	+13.
BEA-ERR-DISABLE-NOT-RESPOND	+14.
BEA-ERR-DISABLE	+15.
BEA-ERR-ALLOC	+16.
BEA-ERR-TIMEOUT	+17.
BEA-ERR-TSQ	+18.
BEA-ERR-SOCKET-FAILURE	+19.
BEA-ERR-PROTOCOL	+20.
BEA-ERR-QUEUE-OVERFLOW	+21.

ReqReturnCd

このコードは、Oracle Tuxedoドメインの戻りコードです。Tuxedoのエラー・コードについては、Oracle Tuxedoのドキュメントを参照してください。

Request_data

この領域は、リクエスト・データと戻されるデータが格納される領域です。その長さは、個々のサービスの構成内容に応じて変わります。サービスごとに管理者に確認してください。最大値は32000です。

例

次の例は、COBOLのCICSクライアント・プログラムのサンプルです。

リスト5-3 COBOLのCICSクライアント・プログラムの例

IDENTIFICATION DIVISION

PROGRAM-ID. TESTCLN.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-3090.
OBJECT-COMPUTER. IBM-3090.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FILLER PIC X(32) VALUE 'SAMPLE COBOL CICS CLIENT PROGRAM'.
01 MSG-AREA.
05 M-DATA PIC X(42) VALUE SPACES.
05 M-RCDE PIC Z(05) VALUE ZEROS.
01 WS-COMMAREA.
05 WC-DATALEN PIC S9(9) COMP-4.
05 WC-SVCNAME PIC X(16).
05 WC-REQUESTCD PIC S9(9) COMP-4.
05 WC-RETURNCD PIC S9(9) COMP-4.
05 WC-REQRETURNCD PIC S9(9) COMP-4.
05 WC-REQDATA PIC X(14).
LINKAGE SECTION.
01 DFHCOMMAREA PIC X(14).
PROCEDURE DIVISION.
A100-ENTRY.
MOVE +14 TO WC-DATALEN.
MOVE 'TOLOWER' TO WC-SVCNAME.
MOVE +5 TO WC-REQUESTCD.
MOVE 'THIS IS A TEST' TO WC-REQDATA.
EXEC CICS LINK PROGRAM('BEAPRERQ')
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC.
IF RETURNCD = 0
MOVE 'SUCCESSFUL CALL, RETURN DATA IS IN WC-DATA'
TO MSG-DATA
ELSE
MOVE 'PROCESS ERROR OCCURRED, RETURN CODE EQUAL '
TO MSG-DATA
MOVE RETURNCD TO M-RCDE
END-IF.
EXEC CICS SEND TEXT FROM(MSG-AREA) LENGTH(47)
ERASE TERMINAL FREEKB CURSOR(0)
END-EXEC.
A200-EXIT.
EXEC CICS RETURN END-EXEC.

 

次の例は、CのCICSクライアント・プログラムのサンプルです。

リスト5-4 CのCICSクライアント・プログラムの例

long resp, resp2;
unsigned short int lmsg;
struct CMAREA carea;

carea.CltHdr.DataLen = strlen(sendbuf);
memcpy(carea.CltHdr.SvcName, “ECHO”, 4);
carea.CltHdr.RequestCd = BEA_REQUEST_RESPONSE;
memcpy(carea.Request_data, “This is a test”, 14);
lmsg=sizeof(carea);
/* Use the name defined during installation */
EXEC CICS LINK PROGRAM("PREREQ")
COMMAREA(&carea)
LENGTH(lmsg) RESP(resp) RESP2(resp2);

if(carea.CltHdr.ReturnCd || carea.CltHdr.ReqReturnCd)
process error;
else
successful call, returned data is in Request_data;

 

注意:	Cプログラマは、文字列の中にNULL終了文字を含めないようにしてください。前述の例では、strxxx呼出しではなく、memxxx呼出しを使用しています。この例は、CICS環境でC言語を使用する場合の標準パターンです。詳細は、CICS版C言語のドキュメントを参照してください。

エラー処理

TMA TCP for CICSを使用している際に、次の3つのタイプが発生することがあります。

•	ゲートウェイのエラー(通信の問題)

•	MVSまたはCICSのエラー

•	アプリケーション・エラー

次の項から、これらの各種エラーをTMA TCPがどのように処理しているのかについて説明します。

ゲートウェイのエラー

ローカル・ゲートウェイまたはリモート・ゲートウェイで発生したエラーは、リモートのOracle Tuxedoノード上のULOGファイルと、CICSリージョンのBEALOGファイル(インストール時に定義されるTDキュー)に記録されます。関連するサービス・リクエストはすべて失敗しますが、TMAゲートウェイ間で相互の通信が可能であれば、エラー・メッセージがTMAゲートウェイ間でやり取りされます。

MVSまたはCICSのエラー

Oracle Tuxedoドメインでリクエストを送信するときに、送信先のリモート・システム側の問題で、TMA TCP for CICSが特定タイプの障害を検出できない場合は、TMA TCP Gateway (Oracle Tuxedoドメイン)のブロッキング・タイムアウト・パラメータの値を調整すれば、時間設定に応じた問題の検出が可能になります。この構成パラメータはリモートのTMA TCP Gatewayシステムで設定します。このパラメータを変更する場合は、そのシステムの管理者に問い合せてください。

CICSリージョンから送信されるリクエストで発生した問題も、BEALOGファイルに記録されます。これらのリクエストのタイムアウト時間は、TMA TCP for CICSの管理ツールを使用して調節できます。

ブロッキング・タイムアウト・パラメータの詳細は、Oracle TMA TCP Gatewayユーザーズ・ガイドを参照してください。

アプリケーション・エラー

プログラムが存在しない、プログラムが無効になっているなどのエラーが発生したため、ハンドラが特定のプログラムを実行できない場合は、ハンドラからTMA TCP Gatewayゲートウェイにメッセージが送信されます。その他のタイプのエラーがアプリケーション・プログラムで発生し、ハンドラに問題が通知されない場合は、ハンドラからリモート・ゲートウェイにタイムアウトのメッセージが送信されます。

リクエストの送信元がCICSである場合、Oracle Tuxedoは可能であれば、具体的な問題に関する情報を戻します。ネットワークに問題があってデータの送信が不可能な場合は、リクエストの送信元にタイムアウト・エラーが戻されます。

サーバー・アプリケーションに関する注意事項

次の項で、CICSプログラマがTMA TCP for CICSをサーバーとして相互運用するアプリケーション・プログラムを開発または変更する際に注意する必要がある事項について説明します。

リモートのOracle Tuxedoドメインから送信されるリクエストを処理するCICSアプリケーション・プログラムの記述方法は、 CICS LINKコマンドで起動するCICSアプリケーション・プログラムと似ています。

Oracle Tuxedoのリクエストを適切に処理するCICSプログラムとは、任意の操作を実行したら、情報を呼出し元に戻すプログラムです。Oracle Tuxedoクライアント・プログラムからリクエストされるCICSサービスは、処理するリクエストとレスポンスが必ず1つずつでなければなりません。

Oracle Tuxedoクライアントから呼び出されるCICSサービス・プログラムがEXEC CICS XCTL操作の実行時にその操作を制御しない場合は、注意が必要です。レスポンス・データがクライアントに確実に戻されるように、XCTLの実行中に、データの受け渡しを行うプログラム間で、元のCOMMAREAを渡す必要があり、こうすることで、データ受け渡しの最後のプログラムからTMA TCP for CICSのハンドラにレスポンス・データが戻されるようになります。

レスポンスありのサービスのプログラミング

クライアントにレスポンスを送信するサービス・プログラムは、EXEC CICS LINKコマンドを使用して実行します。COMMAREAオプションにはデータ本体へのポインタが含まれるため、ヘッダーは送信されません。したがって、サービス・プログラムが使用できるデータは、COMMAREA内のリクエスト・データです。

レスポンスなしのサービスのプログラミング

リクエスタに応答を返さないサービス・プログラムは、 EXEC CICS STARTコマンドで開始するトランザクションを使用して実行します。このコマンドのFROMオプションにはデータ本体へのポインタが含まれるため、ヘッダーは送信されません。したがって、このようなサービス・プログラムは、データ本体へのポインタを含むSETオプションを指定してEXEC CICS RETRIEVEコマンドを使用する必要があります。

注意:	応答を送信しないサービスごとに一意のトランザクションを定義し、該当するサービスの着信サービス情報画面のトランザクション名フィールドにトランザクションの名前を入力してください。

応答を送信しないサービスとしては、たとえば、TPNOREPLYフラグを設定したtpacallを使用して、クライアントからサービスをリクエストする場合があります。

返信メッセージの長さの変更

システムがゲートウェイを介して送信する返信メッセージの実際のサイズをリクエスト単位で設定できます。これは単に、着信サービス情報画面の最大メッセージ・フィールドを使用して、特定のサービスのメッセージ・サイズを制限することとは違います。リクエスト単位で返信メッセージのサイズを制限するには、サービス・プログラムが、コピーブックまたは"YOURHLQ".BEATCPC.INCLUDEファイルに収録されているインクルード・ファイルを使用して、TWAのアドレス指定を行う必要があります。

返信メッセージの長さの変更(Cプログラム)

リクエスト単位で返信メッセージの長さを変更するには、TWAINCLファイルに定義されているTWA_CONNECT構造体のrtnMsgSizeフィールドでメッセージの長さを指定します。

返信メッセージの長さの変更(COBOLプログラム)

リクエスト単位で返信メッセージの長さを変更するには、TWACOPYコピーブックのTWA_CONNECTレコード型のRTN-MSG-SIZEフィールドでメッセージの長さを指定します。