サーバーのコーディング

Oracle Tuxedoシステムには、ATMIサーバーを簡単に開発できるように、ATMIサーバーのロード・モジュール用に定義済の制御プログラムが提供されています。buildserver -Cコマンドを実行すると、制御プログラムが自動的にサーバーの一部として組み込まれます。

定義済の制御プログラムは、アプリケーションへの参加と終了のほかに、サーバーにかわって次の操作を行います。

ハングアップを無視してプロセスを実行します。つまり、SIGHUPシグナルを無視します。
標準オペレーティング・システム・ソフトウェアの終了シグナル(SIGTERM)を受信すると、終了処理を開始します。サーバーは停止され、必要な場合は再起動します。
掲示板サービスが参照できるように共用メモリーを割り当てます。
プロセスに対してメッセージ・キューを作成します。
サーバーによって提供される初期サービスを通知します。初期サービスは、定義済の制御プログラムとリンクされたすべてのサービス、またはOracle Tuxedoシステムの管理者が構成ファイルに指定したサブセットです。
コマンド行に入力された2つのダッシュ(--)までの引数を処理します。2つのダッシュは、システムで認識される引数の終わりを示します。
TPSVRINITルーチンを呼び出して、コマンド行で2つのダッシュ(--)の後に入力された引数を処理したり、リソース・マネージャをオープンします(オプション)。このようなコマンド行の引数は、アプリケーション固有の初期化に使用されます。
中止がリクエストされるまで、リクエスト・キューにサービス・リクエスト・メッセージがあるかどうかを確認します。
サービス・リクエスト・メッセージがリクエスト・キューに到着すると、中止がリクエストされるまで、main()は次の処理を行います。

-rオプションが指定されている場合、サービス・リクエストの開始時間を記録します。
掲示板を更新して、サーバーがBUSYであることを示します。
サービスをディスパッチします。つまり、サービス・サブルーチンを呼び出します。

サービスが入力に対する処理を終了して制御が戻ると、中止が要求されるまで、main()は次の処理を行います。

-rオプションが指定されている場合、サービス・リクエストの終了時間を記録します。
統計を更新します。
掲示板を更新して、サーバーがIDLE状態であること、つまりサーバーの準備ができたことを示します。
キューに次のサービス・リクエストがあるかどうかを確認します。

サーバーの中止が要求されると、TPSVRDONEを呼び出して必要な停止操作を行います。

以上からわかるように、main()ルーチンは、アプリケーションへの参加と終了、レコードやトランザクションの管理、および通信に関する詳細を扱っています。

システムで提供されるサーバーおよびサービス

制御プログラムは、システムで提供される1つのATMIサーバーAUTHSVR、および2つのサブルーチンTPSVRINITとTPSVRDONEを提供します。次の項で説明するこれらの3つのデフォルト・バージョンについては、ご使用のアプリケーションに合せて変更できます。

システムで提供されるサーバー: AUTHSVR( )

AUTHSVR(5)サーバーを使用すると、アプリケーションで各クライアントの認証を行うことができます。このサーバーは、アプリケーションのセキュリティ・レベルがTPAPPAUTH、USER_AUTH、ACL、またはMANDATORY_ACLに設定されている場合に、TPINITIALIZEルーチンによって呼び出されます。

AUTHSVRのサービスは、USER-DATA-RECレコードでユーザー・パスワードを確認します。このユーザー・パスワードは、TPINFDEF-RECレコードのPASSWDフィールドにあるアプリケーション・パスワードとは異なります。デフォルトでは、システムによってdataから文字列が取得され、それと合致する文字列が/etc/passwdファイルで検索されます。

TPINITIALIZEがネイティブ・サイトのクライアントから呼び出された場合、受信したUSER-DATA-RECレコードはそのまま転送されます。そのため、アプリケーションでパスワードの暗号化が必要な場合、それに応じてクライアント・プログラムをコーディングする必要があります。

TPINITIALIZEがワークステーション・クライアントから呼び出された場合、データは暗号化されてからネットワークに送信されます。

システムで提供されるサービス: TPSVRINITルーチン

サーバーの起動時に、Oracle Tuxedoシステムの制御プログラムはその初期化時、つまりサービス・リクエストの処理を開始する前に、TPSVRINIT(3cbl)を呼び出します。

アプリケーションがこのルーチンのカスタム・バージョンをサーバーに提供していない場合は、制御プログラムで提供されるデフォルトのルーチンが使用され、このルーチンは、リソース・マネージャをオープンし、エントリを中央イベント・ログに記録してサーバーの起動が成功したことを示します。中央ユーザー・ログは自動的に生成されるファイルで、USERLOG (3cbl)ルーチンを呼び出して、プロセスがこのファイルにメッセージを書き込めるようにします。中央イベント・ログの詳細は、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「エラーの管理」を参照してください。

TPSVRINITルーチンを使用すると、アプリケーションで要求される次のような初期化プロセスを行うことができます。

以降の項では、TPSVRINITを呼び出すことによって、これらの初期化プロセスがどのように行われるのかをサンプル・コードで示します。次のサンプル・コードでは示していませんが、このルーチン内ではメッセージ交換を行うこともできます。ただし、非同期応答が未処理のままでTPSVRINITルーチンが制御を戻すと、このルーチンは失敗します。その場合、Oracle Tuxedoシステムでは応答は無視されて、サーバーが正常に終了します。

また、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「エラーの管理」に説明されているように、TPSVRINITルーチンを使用して、トランザクションを開始したり終了することもできます。

TPSVRINITルーチンの呼出しには、次のシグネチャを使用します。

コマンド行オプションの取得

サーバーは、起動時に最初の処理として、構成ファイルに指定されているサーバー・オプションを読み取ります。これらのオプションは、引数の個数を格納するARGCと、1つのSPACE文字で区切られた引数を格納するARGVを使用して渡されます。その後、定義済の制御プログラムがTPSVRINITを呼び出します。

次のサンプル・コードは、TPSVRINITルーチンでコマンド行オプションを取得する方法を示しています。

リソース・マネージャのオープン

次のサンプル・コードは、TPSVRINITのもう1つの使用法として、リソース・マネージャをオープンする方法を示しています。Oracle Tuxedoシステムで提供されるルーチンによって、リソース・マネージャ、TPOPEN(3cbl)およびTX OPEN(3cbl)がオープンされます。また、補助的なルーチンTPCLOSE(3c bl)とTXCLOSE(3 cbl)も提供されます。これらのルーチンを使用してリソース・マネージャをオープンしたりクローズするアプリケーションは、その意味では移植性があります。これらは、構成ファイルに設定されたリソース・マネージャのインスタンス固有の情報にアクセスすることによって動作します。

これらのルーチン呼出しは省略可能です。また、リソース・マネージャがデータベースの場合、リソース・マネージャ固有の呼出しがデータ操作言語(DML)の一部であるときは、その呼出しの代わりに使用できます。USERLOG(3cbl)ルーチンを使用して、中央イベント・ログに書き込んでいることに注目してください。

  IDENTIFICATION DIVISION.
  PROGRAM-ID. TPSVRINIT.
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  SOURCE-COMPUTER. USL-486.
  OBJECT-COMPUTER. USL-486.
*
  DATA DIVISION.
  WORKING-STORAGE SECTION.
    01 TPSTATUS-REC.
      COPY TPSTATUS.
    01 LOGMSG         PIC X(50).
    01 LOGMSG-LEN    PIC S9(9) COMP-5.
*
  LINKAGE SECTION.
    01 CMD-LINE.
      05 ARGC PIC 9(4) COMP-5.
      05 ARGV.
           10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
    01 SERVER-INIT-STATUS.
     COPY TPSTATUS.
*
  PROCEDURE DIVISION USING CMD-LINE SERVER-INIT-STATUS.
  A-START.
    . . . INSPECT the ARGV line and process arguments
    IF arguments are invalid
               MOVE "Invalid Arguments Passed" TO LOGMSG
               PERFORM EXIT-NOW.
    ELSE arguments are OK continue
 
    CALL "TPOPEN" USING TPSTATUS-REC.
    IF NOT TPOK
          MOVE "TPOPEN Failed" TO LOGMSG
    ELSE IF TPESYSTEM
          MOVE "System /T error has occurred" TO LOGMSG
    ELSE IF TPEOS
          MOVE "An Operating System error has occurred" TO LOGMSG
    ELSE IF TPEPROTO
          MOVE "TPOPEN was called in an improper Context" TO LOGMSG
    ELSE IF TPERMERR
          MOVE "Resource manager Failed to Open" TO LOGMSG
          PERFORM EXIT-NOW.
    SET TPOK IN SERVER-INIT-STATUS TO TRUE.
    EXIT PROGRAM.
 EXIT-NOW.
  SET TPEINVAL IN SERVER-INIT-STATUS TO TRUE
    MOVE 50 LOGMSG-LEN.
    CALL "USERLOG" USING LOGMSG
                  LOGMSG-LEN
                  TPSTATUS-REC.
  EXIT PROGRAM.

初期化時にエラーが発生しないように、サーバーを終了してからサービス・リクエストの処理を開始するようにTPSVRINITをコーディングできます。

システムで提供されるサービス: TPSVRDONEルーチン

TPSVRINITがTPOPENを呼び出してリソース・マネージャをオープンするのと同じように、TPSVRDONEルーチンはTPCLOSEを呼び出してリソース・マネージャをクローズします。

TPSVRDONEルーチンの呼出しには、次のシグネチャを使用します。

次のサンプル・コードは、TPSVRDONEルーチンを使用して、リソース・マネージャをクローズして終了する方法を示しています。

  IDENTIFICATION DIVISION.
  PROGRAM-ID. TPSVRDONE.
  ENVIRONMENT DIVISION.
  CONFIGURATION SECTION.
  SOURCE-COMPUTER. USL-486.
  OBJECT-COMPUTER. USL-486.
*
  DATA DIVISION.
  WORKING-STORAGE SECTION.
   01 TPSTATUS-REC.
      COPY TPSTATUS.
   01 LOGMSG                PIC X(50).
   01 LOGMSG-LEN            PIC S9(9) COMP-5.
   01 SERVER-DONE-STATUS.
      COPY TPSTATUS.
  PROCEDURE DIVISION.
  A-START.
   CALL "TPCLOSE" USING TPSTATUS-REC.
   IF NOT TPOK
          MOVE "TPCLOSE Failed" TO LOGMSG
   ELSE IF TPESYSTEM
          MOVE "System /T error has occurred" TO LOGMSG
   ELSE IF TPEOS
          MOVE "An Operating System error has occurred" TO LOGMSG
   ELSE IF TPEPROTO
          MOVE "TPCLOSE was called in an improper Context" TO LOGMSG
   ELSE IF TPERMERR
          MOVE "Resource manager Failed to Open" TO LOGMSG
          PERFORM EXIT-NOW.
   SET TPOK IN SERVER-DONE-STATUS TO TRUE.
   EXIT PROGRAM.
  EXIT-NOW.
   SET TPEINVAL IN SERVER-DONE-STATUS TO TRUE
   MOVE 50 LOGMSG-LEN.
   CALL "USERLOG" USING LOGMSG
                  LOGMSG-LEN
                  TPSTATUS-REC.
   EXIT PROGRAM.

サーバーのコーディングのためのガイドライン

通信の詳細はOracle Tuxedoシステムの制御プログラムによって処理されるので、プログラマは通信の実装よりもアプリケーション・サービスのロジックに集中できます。ただし、システムで提供される制御プログラムと互換性を保つために、アプリケーション・サービスが特定の規約に従っている必要があります。これらの規則は、サービス・ルーチンをコーディングするためのサービス・テンプレートとも呼ばれます。次に、これらの規則についてまとめます。

リクエスト/レスポンス・サービスが一度に受信できるリクエストの数は1つだけであり、送信できる応答も1つだけです。
リクエスト/レスポンス・サービスが一度に処理するリクエストは1つだけです。別のリクエストを受け取ることができるのは、リクエスタに応答を送信した後、または別の処理を行うために別のサービスにリクエストを転送した後だけです。
サービス・ルーチンを終了するには、TPRETURNまたはTPFORWARルーチンのいずれかを呼び出す必要があります。
TPACALLを使用して別のサーバーと通信する場合は、サービスの開始元は未処理の応答がすべて処理されるまで待機するか、またはTPCANCELを使用して未処理の応答をすべて無効にしてから、TPRETURNまたはTPFORWARを呼び出す必要があります。

サービスの定義

サービス・ルーチンをコーディングする場合、最初にTPSVCSTART(3cbl)ルーチンを呼び出す必要があります。このルーチンは、サービスのパラメータとデータを取得します。TPSVCSTARTルーチンの呼出しには、次のシグネチャを使用します。

サービス情報のデータ構造体は、COBOLのCOPYファイルにTPSVCDEFとして定義されます。このデータ構造体のメンバーは、次のとおりです。

次の表は、TPSVCDEFデータ構造体のメンバーを示しています。

表5-1 TPSVCDEFデータ構造体
フィールド	説明
`COMM-HANDLE`	リクエスト元プロセスがサービスの呼出しに使用した通信ハンドル。この通信ハンドルは、サービス・ルーチンに対して指定されます。
`SETTINGS`(`TPBLOCK-FLAG TPTRAN-FLAG`など)	サーバーの特性を制御するその他の設定。設定値の詳細は、『Oracle Tuxedo ATMI COBOL関数リファレンス』を参照してください。
`APPKEY`	アプリケーションで使用するために予約された値。アプリケーション固有の認証が設計に含まれている場合、認証サーバーによって認証の成功または失敗を示す値、およびクライアント認証キーが返される必要があります。認証サーバーは、クライアントがアプリケーションに参加するときに呼び出されます。Oracle Tuxedoシステムは、`APPKEY`をクライアントのために保持し、このフィールドに格納して以降のサービス・リクエストに渡します。`APPKEY`がサービスに渡されたときは、クライアントの認証は終了しています。ただし、サービス内で`APPKEY`フィールドを使用して、サービスを呼び出したユーザー、またはそのユーザーに関するそのほかのパラメータを識別できます。
`CLIENTID`	リクエスト元クライアントの識別子。
`SERVICE-NAME`	リクエスト元プロセスがサービスの呼出しに使用したサービス・ルーチンの名前。

DATA-RECに格納されるリクエスト・データにサービスがアクセスする場合は、構成ファイルでそのサービスに定義されているレコード・タイプにデータが格納されるようにコーディングする必要があります。制御が正常に戻った場合、DATA-RECには受け取ったデータが格納され、LENには移動した実際のバイト数が格納されます。

次のサンプル・コードは、一般的なサービス定義を示しています。

    IDENTIFICATION DIVISION.
    PROGRAM-ID. BUYSR.
    AUTHOR. TUXEDO DEVELOPMENT.
    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER. USL-486.
    OBJECT-COMPUTER. USL-486.
*
    INPUT-OUTPUT SECTION.
    . . .
******************************************************
* Tuxedo definitions
******************************************************
    01 TPSVCRET-REC.
    COPY TPSVCRET.
*
    01 TPTYPE-REC.
    COPY TPTYPE.
*
    01 TPSTATUS-REC.
    COPY TPSTATUS.
*
    01 TPSVCDEF-REC.
    COPY TPSVCDEF.
******************************************************
* Log message definitions
******************************************************
    01 LOGMSG.
            05 LOGMSG-TEXT        PIC X(50).
*
    01 LOGMSG-LEN                 PIC S9(9) COMP-5.
******************************************************
* User defined data records
******************************************************
    01 CUST-REC.
    COPY CUST.
*
    LINKAGE SECTION.
*
    PROCEDURE DIVISION.
*
 START-BUYSR.
    MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    OPEN files or DATABASE
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE "Server Started" TO LOGMSG-TEXT.
    PERFORM DO-USERLOG.
    MOVE LENGTH OF CUST-REC TO LEN IN TPTYPE-REC.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      CUST-REC
                      TPSTATUS-REC.
    IF TPTRUNCATE
        MOVE "Input data exceeded CUST-REC length" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF NOT TPOK
        MOVE "TPSVCSTART Failed" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF REC-TYPE NOT = "VIEW"
        MOVE "REC-TYPE in not VIEW" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF SUB-TYPE NOT = "cust"
        MOVE "SUB-TYPE in not cust" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
     . . .
     set consistency level of the transaction
     . . .
******************************************************
* Exit
******************************************************
  A-999-EXIT.
     MOVE "Exiting" TO LOGMSG-TEXT.
     PERFORM DO-USERLOG.
     SET TPFAIL TO TRUE.
     COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
     TPTYPE-REC BY TPTYPE-REC
     DATA-REC BY CUST-REC
     TPSTATUS-REC BY TPSTATUS-REC.
******************************************************
* Write to userlog
******************************************************
  DO-USERLOG.
     CALL "USERLOG" USING LOGMSG
              LOGMSG-LEN
              TPSTATUS-REC.

この例では、クライアント側のリクエスト・レコードが最初に送られたときに、REC-TYPEにVIEW、SUB-TYPEにcustが設定されています。BUYSRサービスは、VIEW型レコードを認識するサービスとして構成ファイルに定義されています。BUYSRサービスは、CUST-RECレコードにアクセスしてデータ・レコードを取得します。このレコードが取得された後、データベースへの最初のアクセスを行う前に、トランザクションの整合性レベルが指定されています。トランザクションの整合性レベルの詳細は、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「グローバル・トランザクションのコーディング」を参照してください。

ここで示すサンプル・コードは、PRINTERサービスがTPGPRIOルーチンを使用して、受信したばかりのリクエストの優先度を確認する方法を示しています。その優先度に基づいて、印刷ジョブが適切なプリンタRNAMEに送られます。

その後、INPUT-RECの内容がプリンタに送られます。アプリケーションはTPSVCDEF-RECに対して問合せを実行し、応答が必要かどうかを判定します。その場合は、宛先プリンタ名をクライアントに返します。TPRETURNルーチンの詳細は、「サービス・ルーチンの終了」を参照してください。

    IDENTIFICATION DIVISION.
    PROGRAM-ID. PRINTSR.
    AUTHOR. TUXEDO DEVELOPMENT.
    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER. USL-486.
    OBJECT-COMPUTER. USL-486.
*
    INPUT-OUTPUT SECTION.
    . . .
******************************************************
* Tuxedo definitions
******************************************************
    01 TPSVCRET-REC.
    COPY TPSVCRET.
*
    01 TPTYPE-REC.
    COPY TPTYPE.
*
    01 TPSTATUS-REC.
    COPY TPSTATUS.
*
    01 TPSVCDEF-REC.
    COPY TPSVCDEF.
*
    01 TPPRIDEF-REC.
    COPY TPPRIDEF.
******************************************************
* Log message definitions
******************************************************
    01 LOGMSG.
            05 FILLER           PIC S9(9) VALUE
                    "TP-STATUS=".
            05 LOG-TP-STATUS    PIC S9(9).
            05 LOGMSG-TEXT      PIC X(50).
*
    01 LOGMSG-LEN  PIC S9(9) COMP-5.
******************************************************
* User defined data records
******************************************************
    01 INPUT-REC           PIC X(1000).
    01 PRNAME              PIC X(20).
*
    LINKAGE SECTION.
*
    PROCEDURE DIVISION.
*
 START-PRINTSR.
    MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    OPEN files or DATABASE
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE ZERO to TP-STATUS.
    MOVE "Server Started" TO LOGMSG-TEXT.
    PERFORM DO-USERLOG.
    MOVE LENGTH OF INPUT-REC TO LEN.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      INPUT-REC
                      TPSTATUS-REC.
    IF NOT TPOK
             MOVE "TPSVCSTART Failed" TO LOGMSG-TEXT
             PERFORM DO-USERLOG
             SET TPFAIL TO TRUE.
             PERFORM A-999-EXIT.
    . . .
    Check other parameters
    CALL "TPGPRIO" USING TPPRIDEF-REC
                   TPSTATUS-REC.
    IF NOT TPOK
             MOVE "TPGPRIO Failed" TO LOGMSG-TEXT
             PERFORM DO-USERLOG
             SET TPFAIL TO TRUE.
             PERFORM A-999-EXIT.
    IF PRIORITY < 20
             MOVE "BIGJOBS" TO RNAME
    ELSE IF PRIORITY < 60
             MOVE "MEDJOBS" TO RNAME
    ELSE
             MOVE "HIGHSPEED" TO RNAME.
    . . .
    Print INPUT-REC on RNAME printer
    . . .
    IF TPNOREPLY
             MOVE SPACES TO REC-TYPE
             MOVE 0 TO LEN
             SET TPSUCCESS TO TRUE
             PERFORM A-999-EXIT
    IF TPREPLY
             MOVE "STRING" TO REC-TYPE
             MOVE LENGTH OF PRNAME TO LEN
             SET TPSUCCESS TO TRUE
             PERFORM A-999-EXIT.
******************************************************
* Exit
******************************************************
 A-999-EXIT.
     MOVE "Exiting" TO LOGMSG-TEXT.
     PERFORM DO-USERLOG.
     SET TPSUCCESS TO TRUE.
     COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
              TPTYPE-REC buTPTYPE-REC
              DATA-REC BY PRNAME
              TPSTATUS-REC BY TPSTATUS-REC.
******************************************************
* Write to userlog
******************************************************
 DO-USERLOG.
     MOVE TP-STATUS TO LOG-TP-STATUS.
     CALL "USERLOG" USING LOGMSG
               LOGMSG-LEN
               TPSTATUS-REC.

サービス・ルーチンの終了

TPRETURN(3cbl)、TPCANCEL(3cbl)、およびTPFORWAR(3cbl)ルーチンは、サービス・ルーチンが完了したことをそれぞれ次の方法で通知します。

応答の送信

TPRETURN(3cbl)呼出しは、サービス・ルーチンの終了を示すEXIT文を含んだCOBOLのcopyファイルで、TPFORWAR(3cbl)呼出しは、メッセージをリクエスタに送信したり、リクエストを別のサービスに転送するCOBOLのcopyファイルです。TPRETURNルーチンの呼出しには、次のシグネチャを使用します。

次のコードは、TPSVCRET-RECレコードのシグネチャを示しています。

表5-2は、TPSVCRET-RECデータ構造体のメンバーを示しています。

表5-2 TPSVCRET-RECデータ構造体のメンバー
メンバー	説明
`TP-RETURN-VAL`	サービスが正常に終了したかどうかをアプリケーション・レベルで示す値。この値は、シンボリック名で表される整数値です。有効な設定は、次のとおりです。 `TPSUCCESS` - ルーチンの呼出しが成功したことを示します。ルーチンは、応答メッセージを呼出し側のレコードに格納します。応答メッセージがある場合は、呼出し側のレコード内にあります。 `TPFAIL`(デフォルト) - サービスが失敗したことを示します。ルーチンは、応答を待つクライアント・プロセスにエラー・メッセージを通知します。その場合、クライアントが呼び出した`TPCALL`または`TPGETRPLY`ルーチンが失敗し、変数`TP-STATUS`にアプリケーション定義の失敗を示す`TPESVCFAIL`が設定されます。応答メッセージが要求されている場合は、呼出し側のレコードから取得できます。 `TPEXIT` - サービスが失敗したことを示します。ルーチンは、応答を待つクライアント・プロセスにエラー・メッセージを通知して終了します。この引数の値がグローバル・トランザクションに与える影響の詳細は、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「グローバル・トランザクションのコーディング」を参照してください。
`APPLC-CODE`	アプリケーション定義の戻りコードを呼出し側に返します。クライアントは、`APPL-RETURN-CODE IN TPSTATUS-REC`に対して問合せを実行して、`APPLC-CODE`に返された値にアクセスできます。成功または失敗に関係なく、このコードはルーチンから返されます。

サービス・ルーチンの主なタスクは、リクエストを処理してクライアント・プロセスに応答を返すことです。ただし、要求されたタスクを行うために必要なすべての処理を1つのサービスで行う必要はありません。サービスはリクエスタとして動作し、クライアントが元のリクエストを行ったときと同じように、TPCALLまたはTPACALLを呼び出して、リクエスト呼出しを別のサービスに渡すことができます。

TPRETURNが呼び出された場合、常に制御プログラムに制御が戻ります。非同期応答でサービスがリクエストを送信している場合、制御プログラムに制御を戻す前にすべての応答を受信するか、またはTPCANCELを使用してすでに送信したリクエストを無効にする必要があります。それ以外の場合、未処理の応答はOracle Tuxedoシステムの制御プログラムで受信されると自動的に破棄され、呼出し側にエラーが返されます。

クライアントがTPCALLを使用してサービスを呼び出した場合、TPRETURNの呼出しが成功すると、O-DATA-RECレコードから応答メッセージを取得できます。TPACALLを使用してリクエストを送信し、TPRETURNから正常に制御が戻されると、TPGETRPLYのDATA-RECレコードに応答メッセージが格納されます。

応答が必要な場合に、TPRETURNの引数の処理時にエラーが発生すると、呼出し側プロセスに失敗を示すメッセージが送信されます。呼出し側は、TP-STATUSに格納されている値を調べてエラーを検出します。失敗を示すメッセージが送信された場合、TP-STATUSにTPESVCERRが設定されます。この値は、APPL-RETURN-CODE IN TPSTATUS-RECの値よりも優先されます。このようなエラーが発生した場合、応答データは戻されず、呼出し側の出力レコードの内容と長さは変更されません。

TPRETURNが不明なタイプのレコードにメッセージを返すか、または呼出し側で使用できないレコードにメッセージを返した場合、つまりTPNOCHANGEが設定されて呼出しが行われた場合、TP-STATUSにTPEOTYPEが返されます。その場合、アプリケーションの成功また失敗は判定されず、呼出し側の出力レコードの内容と長さは変更されません。

TPRETURNルーチンが呼び出され、呼出し側が応答を待っている間にタイムアウトが発生した場合、APPL-RETURN-CODE IN TPSTATUS-RECに戻される値は意味を持ちません。この状況は、TP-STATUSに値が戻されるどの状況よりも優先します。その場合、TP-STATUSにTPETIMEが設定され、応答データは送信されず、呼出し側の応答レコードの内容と長さは変更されません。Oracle Tuxedoシステムには、ブロッキング・タイムアウトとトランザクション・タイムアウトの2種類のタイムアウトがあります(詳細は、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「グローバル・トランザクションのコーディング」を参照)。

ここで示すサンプル・コードは、XFERサーバーの一部であるTRANSFERサービスを示しています。基本的に、TRANSFERサービスはWITHDRAWALおよびDEPOSITサービスへの同期呼出しを行います。このサービスでは、WITHDRAWALとDEPOSITの両サービスの呼出しに同じリクエスト・レコードを使用する必要があるので、応答メッセージ用に別のレコードが割り当てられます。WITHDRAWALの呼出しが失敗した場合、フォーム上のステータス行に「cannot withdraw」というメッセージが出力され、TPRETURNルーチンのTP-RETURN-VAL IN TPSVCRET-RECにTPFAILが設定されます。呼出しが成功した場合、振替元口座の残高が応答レコードから取得されます。

DEPOSITサービスへの呼出しは、同様のシナリオに従います。呼出しが成功すると、このサービスによってTP-RETURN-VAL IN TPSVCRET-RECにTPSUCCESSが設定されて、適切な残高情報がステータス行に返されます。

   IDENTIFICATION DIVISION.
   PROGRAM-ID. TRANSFER.
   AUTHOR. TUXEDO DEVELOPMENT.
   ENVIRONMENT DIVISION.
   CONFIGURATION SECTION.
   SOURCE-COMPUTER. USL-486.
   OBJECT-COMPUTER. USL-486.
*
   INPUT-OUTPUT SECTION.
   . . .
******************************************************
* Tuxedo definitions
******************************************************
   01  TPSVCRET-REC.
   COPY TPSVCRET.
*
   01  TPTYPE-REC.
   COPY TPTYPE.
*
   01 TPSTATUS-REC.
   COPY TPSTATUS.
*
   01  TPSVCDEF-REC.
   COPY TPSVCDEF.
******************************************************
* User defined data records
******************************************************
   01 TRANS-REC.
      COPY TRANS-AMOUNT.
*
   LINKAGE SECTION.
*
   PROCEDURE DIVISION.
*
   START-TRANSFER.
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE LENGTH OF TRANS-REC TO LEN.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      TRANS-REC
                      TPSTATUS-REC.
    IF NOT TPOK
             MOVE "Transaction Encountered An Error" TO STATUS-LINE
             SET TPFAIL TO TRUE.
             COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
                      TPTYPE-REC BY TPTYPE-REC
                      DATA-REC BY TRANS-REC
                      TPSTATUS-REC BY TPSTATUS-REC.
    ELSE
             . . . Check other parameters
******************************************************
* must have a valid debit and credit account number
******************************************************
    CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-DEBIT-ACCOUNT IN  TRANS-REC.

    IF TRANS-DEBIT-ACCOUNT is not valid
             MOVE "Invalid Debit Account Number"
                      TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                      DATA-REC BY TRANS-REC.

    CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-CREDIT-ACCOUNT IN TRANS-REC.
  
    IF TRANS-CREDIT-ACCOUNT is not valid
             MOVE "Invalid Credit Account Number"
             TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                      DATA-REC BY TRANS-REC.
******************************************************
*  Check amount to transfer
******************************************************
    IF TRANS-AMOUNT IN TRANS-REC < 0
             MOVE "Invalid Transfer Amount Requested"
                      TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                      DATA-REC BY TRANS-REC.
******************************************************
*  Make Withdrawal using another service
******************************************************
    MOVE "WITHDRAWAL" TO SERVICE-NAME.
    . . . set other TPCALL parameters
    CALL "TPCALL" USING . . .
    IF NOT TPOK
             MOVE "Cannot withdraw from debit account"
                   TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                   DATA-REC BY TRANS-REC.
******************************************************
*  Make Deposit using another service
******************************************************
    MOVE "DEPOSIT" TO SERVICE-NAME.
    . . . set other TPCALL parameters
    CALL "TPCALL" USING . . .
    IF NOT TPOK
            MOVE "Cannot Deposit into credit account"
                   TO STATUS-LINE IN TRANS-REC
            SET TPFAIL TO TRUE
            COPY TPRETURN REPLACING
                   DATA-REC BY TRANS-REC.
    . . .
    MOVE "Transfer completed" TO STATUS-LINE IN TRANS-REC
    . . . MOVE all the data into TRANS-REC needed by the client
    SET TPSUCCESS TO TRUE
    COPY TPRETURN REPLACING
                   DATA-REC BY TRANS-REC.

記述子の無効化

TPGETRPLYを呼び出したサービス(『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「クライアントおよびサーバーへのリクエスト/レスポンスのコーディング」を参照)がTPETIMEで失敗してリクエストを取り消す場合、TPCANCEL(3cbl)を呼び出して記述子を無効にできます。以降、応答が届いても自動的に破棄されます。

TPCANCELはトランザクション応答、つまりTPNOTRANフラグが設定されていない状態で呼び出されたリクエストへの応答には使用できません。トランザクション内では、TPABORT(3cbl)がトランザクションの呼出し記述子を無効にします。

リスト5-7は、タイムアウト後の応答を無効にする方法を示しています。

リクエストの転送

TPFORWAR(3cbl)ルーチンを使用すると、サービス・リクエストを他のサービスに転送して、別の処理を行うことができます。

TPFORWARルーチンの呼出しには、次のシグネチャを使用します。

TPSVCDEF-RECおよびTPTYPE-RECレコードについては、「サービスの定義」を参照してください。

TPFORWARは、サービス呼出しとは異なります。つまり、リクエストの転送元サービスでは、応答はリクエストされていません。応答を返すのは、リクエストの転送先サービスです。このサービスを転送されたサービスが、リクエストの発信元プロセスに応答を返します。後者のサービスが、リクエストの発信元プロセスに応答を送信します。転送が連鎖的に行われる場合、最後のサーバーがTPRETURNを呼び出して、リクエストの発信元であるクライアントに応答を返します。

図5-1は、あるサービスから別のサービスにリクエストを転送したときのイベントの流れを示しています。ここでは、クライアントはTPCALLルーチンを使用してリクエストを開始し、連鎖の最後のサービス(SVC_C)がTPRETURNルーチンを使用して応答を戻しています。

サービス・ルーチンはTPSPRIOルーチンを使用して、クライアント・プロセスがリクエストを送るのと同じように、指定された優先度に従ってリクエストを転送できます。

プロセスがTPFORWARを呼び出すと、システムで提供された制御プログラムに制御が戻り、サーバー・プロセスは別のリクエストを処理できるようになります。

TPFORWAR呼出しを使用して、その呼出しを行った時点まで要求の処理が成功していたことを示すことができます。アプリケーション・エラーが検出されなかった場合、TPFORWARを呼び出します。エラーが検出された場合、TP-RETURN-VAL IN TPSVCRET-RECにTPFAILを設定してTPRETURNを呼び出します。

次のサンプル・コードは、TPFORWARを呼び出して、サービスがそのデータ・レコードをDEPOSITサービスに送る方法を示しています。新規口座の追加が成功した場合、支店レコードが更新されてその口座が反映され、データ・レコードがDEPOSITサービスに転送されます。失敗した場合、TP-RETURN-VAL IN TPSVCRET-RECにTPFAILが設定されてTPRETURNが呼び出され、失敗を示すメッセージがフォーム上のステータス行に出力されます。

    . . .
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE LENGTH OF TRANS-REC TO LEN.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      TRANS-REC
                      TPSTATUS-REC.
    IF NOT TPOK
             MOVE "Transaction Encountered An Error" TO STATUS-LINE
             SET TPFAIL TO TRUE.
             COPY TPRETURN REPLACING
                      DATA-REC BY TRANS-REC.
    ELSE
             . . . Check other parameters
******************************************************
* Insert new account record
******************************************************
    CALL "ADD-NEW-ACCOUNT-FUNCTION" USING TRANS-ACCOUNT IN TRANS-REC.
    IF Adding New Account Failed
             MOVE "Account not added" TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                       DATA-REC BY TRANS-REC.
******************************************************
* Forward record to the DEPOSIT service to add initial
* balance into account
******************************************************
    MOVE "DEPOSIT" TO SERVICE-NAME.
    . . . set other TPFORWAR parameters
    COPY TPFORWAR REPLACING
                       DATA-REC BY TRANS-REC.

サービスの通知と通知解除

サーバーは起動時に、構成ファイルのCLOPTパラメータに指定された値に基づいて、提供するサービスを通知します。

デフォルトでは、サーバーに組み込まれたすべてのサービスをそのサーバーが通知します。詳細は、『ファイル形式、データ記述、MIBおよびシステム・プロセス・リファレンス』の「UBBCONFIG(5)」または「servopts(5)」リファレンス・ページを参照してください。

通知されたサービスでは掲示板のサービス表エントリが使用されるので、リソースが消費される場合があります。そのため、サーバーの起動時には、提供されるサービスのサブセットだけを利用できるようにします。アプリケーションで利用できるサービスを制限するには、構成ファイルのSERVERSセクションで該当するエントリにCLOPTパラメータを定義し、-sオプションの後に必要なサービスをカンマで区切って指定します。また、-sオプションを使用すると、サービス要求を処理するために呼び出される通知済のサービスと異なる名前のルーチンを呼び出すこともできます。詳細は、『ファイル形式、データ記述、MIBおよびシステム・プロセス・リファレンス』の「servopts(5)」リファレンス・ページを参照してください。

Oracle Tuxedoアプリケーションの管理者は、tmadmin(1)のadvertiseおよびunadvertiseコマンドを使用して、サーバーで提供されるサービスを管理できます。TPADVERTISEおよびTPUNADVERTISEルーチンを使用すると、リクエスト/レスポンス型サーバーまたは会話型サーバーでのサービスの通知を動的に制御できます。ただし、通知されるサービス、または通知を解除するサービスは、リクエストを行うサービスと同じサーバー内になければなりません。

サービスの通知

TPADVERTISE(3cbl)関数の呼出しには、次のシグネチャを使用します。

表5-3は、TPADVERTISEデータ構造体のメンバーを示しています。

表5-3 TPADVERTISEデータ構造体のメンバー
メンバー	説明
`SERVICE-NAME`	通知するサービスの名前。サービス名は127文字以下の文字列で指定します。127文字を超える名前は切り詰められます。`SPACES`文字列は指定できません。これを指定すると、エラー(`TPEINVAL`)になります。
`PROGRAM-NAME`	サービスを実行するために呼び出されるOracle Tuxedoシステム・ルーチン。通常、この名前とサービス名は同じです。`SPACES`文字列は指定できません。それが指定されると、エラーになります。

サービスの通知解除

TPUNADVERTISE(3cbl)ルーチンは、掲示板のサービス表からサービス名を削除します。サービス名が削除されたサービスは、通知されていない状態になります。

TPUNADVERTISEルーチンの呼出しには、次のシグネチャを使用します。

TPUNADVERTISEデータ構造体のメンバーは、表5-4で説明するメンバーだけです。

例:サービスの動的な公開と通知解除

次のサンプル・コードは、TPADVERTISEルーチンの使用方法を示しています。このコードでは、サーバーTLRが起動時にTLRINITサービスだけを提供するようにコーディングされています。初期化後、TLRINITはDEPOSITとWITHDRAWという2つのサービスを通知します。両サービスともTLRFUNCSルーチンによって実行され、サーバーTLRに組み込まれています。

DEPOSITとWITHDRAWを通知した後、TLRINITは自分自身で通知を解除します。

    . . .
**************************************************
* Advertise DEPOSIT service to be processed by
* routine TLRFUNCS
**************************************************
    MOVE "DEPOSIT" TO SERVICE-NAME.
    MOVE "TLRFUNCS" TO PROGRAM-NAME.
    CALL "TPADVERTISE" USING SERVICE-NAME
                       PROGRAM-REC
                       TPSTATUS-REC.
    IF NOT TPOK
           error processing
**************************************************
* Advertise WITHDRAW service to be processed by
* the same routine TLRFUNCS
**************************************************
    MOVE "WITHDRAW" TO SERVICE-NAME.
    MOVE "TLRFUNCS" TO PROGRAM-NAME.
    CALL "TPADVERTISE" USING SERVICE-NAME
                       PROGRAM-REC
                       TPSTATUS-REC.
    IF NOT TPOK
           error processing
**************************************************
* Unadvertise TLRINIT service  (yourself)
**************************************************
    MOVE "TLRINIT" TO SERVICE-NAME.
    CALL "TPUNADVERTISE" USING SERVICE-NAME
                       TPSTATUS-REC.
    IF NOT TPOK
            error processing

サーバーのビルド

実行可能なATMIサーバーをビルドするには、buildserver(1)コマンドに-Cオプションを使用して、Oracle Tuxedoシステム・サーバー・アダプタなどすべての参照ファイルでアプリケーション・サービス・サブルーチンをコンパイルします。

表5-5 buildserverコマンド行オプション
このオプションは...	次を指定することを可能にします...
`-o` `filename`	実行可能な出力ファイル名。デフォルトは`SERVER`です。
`-f` `filenames`	Oracle Tuxedoシステム・ライブラリより先にリンクされるファイルのリスト。`-f`オプションは複数回指定できます。また、各`-f`オプションに複数のファイル名を指定することもできます。COBOLプログラム・ファイル(`file.cbl`)を指定すると、リンクされる前にコンパイルが行われます。ほかのオブジェクト・ファイル(`file.o`)を個別に、またはアーカイブ・ファイル(`file.a`)にまとめて指定することもできます。
`-l` `filenames`	Tuxedoシステム・ライブラリの後でリンクされるファイルのリスト。`-l`オプションは複数回指定できます。また、各`-l`に複数のファイル名を指定できます。COBOLプログラム・ファイル(`file.cbl`)を指定すると、リンクされる前にコンパイルが行われます。ほかのオブジェクト・ファイル(`file.o`)を個別に、またはアーカイブ・ファイル(`file.a`)にまとめて指定することもできます。
-r `filenames`	実行可能サーバーにリンクされるリソース・マネージャのアクセス・ライブラリのリスト。アプリケーション管理者は、buildtms(1)コマンドを使用して、すべての有効なリソース・マネージャ情報を`$TUXDIR/updataobj/RM`ファイルに事前に定義しておく必要があります。リソース・マネージャは1つしか指定できません。詳細は、『Oracle Tuxedoアプリケーションの設定』を参照してください。
-s [`service`:]`routine`	サーバーに提供されるサービス名、および各サービスを実行するルーチン名。`-s`オプションは複数回指定できます。また、各`-s`に複数のサービスを指定できます。サーバーは指定されたサービス名を使用して、クライアントにサービスを通知します。通常、サービスとそのサービスを実行するルーチンには同じ名前を割り当てます。ただし、別の名前を指定することもできます。名前の割当てには、`service`:`routine`という構文を使用します。

リンクするライブラリ・ファイルの指定順序は重要です。ルーチンを呼び出す順序と、これらのルーチンへの参照を含むライブラリによって、この順序が決定されます。

デフォルトでは、buildserverコマンドはUNIXのcobccコマンドを呼び出し、MicroFocus Net Expressコンパイラが使用されます。Fujitsu NetCOBOLを使用するには、WindowsシステムでもALTCCを設定する必要があります。NetCOBOL用にALTCC=cobcc85を設定する必要があります。環境変数ALTCCを設定して別のコンパイル・コマンドを指定したり、ALTCFLAGSを設定してコンパイル・フェーズやリンク・フェーズに独自のフラグを指定することができます。詳細は、『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「環境変数の設定」を参照してください。

次のコマンドは、acct.oアプリケーション・ファイルを処理して、NEW_ACCTとCLOSE_ACCTという2つのサービスを含むACCTサーバーを作成しています。NEW_ACCTはOPEN_ACCTルーチンを呼び出し、CLOSE_ACCTは同じ名前のルーチンを呼び出します。

COBOLを使用したOracle Tuxedoアプリケーションのプログラミング