2018.10.25



Paul Tuohy著

メッセージを取得する、パート1

著者まえがき: この記事の元の記事は2009年10月に掲載されたものです。 それ以降、私は数多くのクライアントの数多くのモダナイゼーション プロジェクトに携わってきましたが、どのプロジェクトでも、今回(および次回)の記事に記した内容を何らかの形で使用してきました。記事の内容は、フリーフォームRPG用に、また、元記事の掲載以降にRPGに導入された、いくつかのコーディングの機能強化に合わせるべく、アップデートを行っています。

アプリケーションをモダナイズ(または新たなアプリケーションを作成)しようとするときに検討すべき基本原則の1つは、アプリケーション、ビジネス ロジック、およびデータベース処理を階層化(すなわちインターフェースを分離)させることです。考え方としては、どのコンポーネントも、他のコンポーネントに影響を及ぼすことなく変更できるようにすることであり、より重要なことに、同じビジネス ロジックおよびデータベース ルーチンを複数のインターフェースで利用できるようにすることです。

それはそれで結構なことですが、対処が必要と思われる、ちょっとした問題点が2つあります。すなわち、ビジネス ロジックまたはデータベース ルーチンがエラーを起こしたらどうなるでしょうか。エラーの発生をどうやってインターフェースに通知するのでしょうか。

言い換えれば、お互いについて何も分からないのに、異なるコンポーネント間でどのようにしてメッセージを送信し合うのでしょうか。

従来のグリーン スクリーンの世界では、メッセージングは、プロセス ロジックとスクリーンの間できっちりと統合されていました。DDSでERRMSGまたはERRMSGIDキーワードを使用していたかもしれませんし、あるいは、プログラム メッセージ キューおよびメッセージ サブファイルを利用していたかもしれません。しかし、プログラム メッセージ キューの手法は、WebリクエストやSQLサブプロシージャーで使えるでしょうか。

今回の記事(および次回の記事)では、インターフェースを問わずにメッセージを処理することを可能にする手法について見て行きます。これらの記事で使用されているコードが含まれているライブラリーは、 http://www.systemideveloper.com/downloads/messagesV2.zipでダウンロードできます。

はじめに

私はこれまでずっと、メッセージ ファイルの大ファンでしたので、この「新たな」データ構造でもそれらを使い続けようと思っています。私がメッセージ ファイルで非常に気に入っている点は、2次レベル メッセージ テキスト、重大度コード、および変数パラメーターを定義できるところです。

けれども、私がメッセージ ファイルについて気に入らないと思うのは、メッセージIDがRPGプログラム内にハード コーディングされるのを目にする時です。もちろん、プログラムでメッセージIDを使用する必要はありますが、メッセージIDを名前付き定数として定義し、それらをすべてのプログラムに含められるコピー メンバーに置きたいと私は思うのです。そうすれば、どのプログラムも、利用可能なすべてのメッセージIDのリストを持つことになります。以下のコード片は、これらのメッセージIDのいくつかの例を示したものです。ここでは、定数名はすべて大文字という表記規則(ほとんどのプログラミング言語で一般的なもの)を使用しています。

dcl-C ERR_NOTFOUND   'ALL9001';
dcl-C ERR_CHANGED    'ALL9002';
dcl-C ERR_DUPLICATE  'ALL9003';
dcl-C ERR_CONSTRAINT 'ALL9004';
dcl-C ERR_TRIGGER    'ALL9005';
dcl-C ERR_UNKNOWN    'ALL9006';
dcl-C ERR_NOT_NUMBER 'ALL9007';
dcl-C ERR_NOT_DATE   ‘ALL9008';

メッセージを格納する

アプリケーションの各コンポーネントが、他のコンポーネントについて何も知ることができないとすると、コンポーネント間でメッセージを送信し合うことは不可能ということになります。

そうする代わりに、メッセージを格納しておき、現在、何件のメッセージが格納されているかを知らせるサブプロシージャーや、メッセージを取得するためのサブプロシージャーを使用する方式を採るということです。

では、メッセージをどのようにして格納するのでしょうか。最初に思い浮かぶのはメッセージ キューまたはデータベースかもしれませんが、どちらも必要ありません。メッセージはデータ構造配列に簡単に格納できます。すべてのメッセージ サブプロシージャーが、1つのモジュール内でコーディングされ、メッセージ フォーマット データ構造配列は同じモジュールに保持されます。

以下に、メッセージ データ構造のフォーマットを示します。このデータ構造はコピー メンバーで定義され、すべてのプログラムに含められます。

 // Format in which error messages are stored.            
dcl-Ds def_MsgFormat qualified template;
  msgId    char(7);
  msgText  char(80);
  severity int(10);
  help     char(500);
  forField char(25);
end-Ds;              

このメッセージ データ構造は、メッセージID、1次レベル メッセージ テキスト、メッセージの重大度、2次レベル メッセージ テキスト、およびメッセージが格納されるフィールドの名前を格納します。

メッセージ モジュール

ここでは、グローバル定義と、それぞれのメッセージ サブプロシージャーについて見てみましょう。

メッセージ モジュール(以下参照)のグーバル定義は、次のものから成ります。

  • メッセージ フォーマットと、現在格納されているメッセージの件数の配列。メッセージの件数は200件あれば十分と思われますが、必要に応じて件数を増やすこともできます。
  • メッセージを格納するメッセージ ファイルの名前を識別するデータ構造。
  • Retrieve Message from Message File(QMHRTVM)およびReceive Message from Message Queue(QMHRCVPM)APIのプロトタイプ。
**free                                      
/include QCpySrc,StdHSpec
ctl-Opt NoMain;

   // To create the required service program...
   //    Current library set to MESSAGES
   //    CRTRPGMOD MODULE(UTILMSGS)
   //    CRTSRVPGM SRVPGM(UTILITY) MODULE(UTIL*)
   //              SRCFILE(UTILITY) TEXT('Utility Procedures')

/include utility,putilMsgs

dcl-Ds messages LikeDS(Def_MsgFormat) dim(200) inz;

dcl-S  msgCount int(10);

 // Message File used for retrieving message
dcl-Ds msgF;
  msgFile    char(10) Inz('APPMSGF');
  msgFileLib char(10) Inz('MESSAGES');
end-Ds;

// Prototype for QMHRTVM API
dcl-Pr retrieve_MessageFromMsgF extPgm('QMHRTVM');
  msgInfo           char(3000) options(*varSize);
  msgInfoLen        int(10) const;
  formatName        char(8) const;
  msgId             char(7) const;
  msgF              char(20) const;
  replacement       char(500) const;
  replacementLength int(10) const;
  replaceSubValues  char(10) const;
  returnFCC         char(10) const;
  usec              char(256);
end-Pr;

// Prototype for QMHRCVPM API
dcl-Pr receive_Msg extPgm('QMHRCVPM');
  msgInfo      char(3000) options(*VarSize);
  msgInfoLen   int(10)    const;
  formatName   char(8)    const;
  callStack    char(10)   const;
  callStackCtr int(10)    const;
  msgType      char(10)   const;
  msgKey       char(4)    const;
  waitTime     int(10)    const;
  msgAction    char(10)   const;
  errorForAPI  like(APIError);
end-Pr; 

メッセージを消去する

u_clear_Messages()サブプロシージャーは、名前が示す通りの処理を行うだけです。すなわち、メッセージ フォーマット データ構造配列を消去し、メッセージ カウントを0にセットします。

 //--------------------------------------------------
 // Clear messages
dcl-Proc u_clear_Messages export;
  dcl-Pi *n end-Pi;

  msgCount = 0;
  clear messages;

end-Proc;  

メッセージを追加する

u_add_Message()サブプロシージャーは、メッセージ フォーマット データ構造配列に、必要なメッセージを追加し、メッセージ カウントを増やします。

 //--------------------------------------------------
 // Add Message - Add a pre-defined message to the message list
 //             - Field Name is optional and may be omitted
 //             - Message data is optional

dcl-Proc u_add_Message export;
  dcl-Pi *n;
    msgId      char(7)   const;
    forFieldIn char(25)  const
                         options(*Omit:*noPass);
    msgData    char(500) const
                         options(*noPass);
  end-Pi;

   // Format RTVM0300 for data returned from QMHRTVM
  dcl-Ds RTVM0300 qualified;
    bytesreturned int(10);
    bytesAvail    int(10);
    severity      int(10);
    alertIndex    int(10);
    alertOption   char(9);
    logIndicator  char(1);
    messageId     char(7);
    *n            char(3);
    noSubVarFmts  int(10);
    CCSIDIndText  int(10);
    CCSIDIndRep   int(10);
    CCSIDTextRet  int(10);
    dftRpyOffset  int(10);
    dftRpyLenRet  int(10);
    dftRpyLenAvl  int(10);
    messageOffset int(10);
    messageLenRet int(10);
    messageLenAvl int(10);
    helpOffset    int(10);
    helpLenRet    int(10);
    helpLenAvl    int(10);
    SVFOffset     int(10);
    SVFLenRet     int(10);
    SVFLenAvl     int(10);
  end-Ds;
  //** reserved
  //** defaultReply
  //** message
  //** messageHelp

  // Based variable used to retrieve text from RTVM0300
  dcl-S textPtr pointer;
  dcl-S text    char(500) Based(textPtr);

  dcl-S repData  char(500);
  dcl-S forField like(forFieldIn);

  if %parms() > 2;
    repData = msgData;
  endIf;

  if %parms() > 1;
    if %addr(forFieldIn) <> *null;
      forField = forFieldIn;
    endIf;
  endIf;

  retrieve_MessageFromMsgF(RTVM0300
                          :%Len(RTVM0300)+350
                          :'RTVM0300'
                          :MsgId
                          :MsgF
                          :RepData
                          :%Len(%Trim(RepData))
                          :'*YES'
                          :'*YES'
                          :APIError);

  msgCount += 1;
  messages(msgCount).msgId = msgId;
  messages(msgCount).forField = forField;
  if (APIError.bytesAvail = 0);
     messages(msgCount).severity = RTVM0300.severity;
     if (RTVM0300.messageLenRet > 0);
        textPtr = %Addr(RTVM0300) + RTVM0300.messageOffset;
        messages(msgCount).msgText = %SubSt(text: 1:
                                            RTVM0300.messageLenRet);
     endIf;
     if (RTVM0300.helpLenRet > 0);
        textPtr = %Addr(RTVM0300) + RTVM0300.helpOffset;
        messages(msgCount).help = %SubSt(Text: 1:
                                         RTVM0300.helpLenRet);
     endIf;
  else;
     messages(msgCount).severity = 99;
     messages(msgCount).msgText = '*** Expected Message Not Found ***';
  endIf;
end-Proc;  

このサブプロシージャーでは、3つのパラメーターを指定できますが、必須なのは1番目(メッセージID)のみです。2番目のパラメーターは、メッセージが関連付けられるフィールドの名前を識別し、3番目のパラメーターはメッセージに対する変数データを格納します。

このサブプロシージャーは、RTVM0300フォーマットでQMHRTVM APIを使用して、メッセージ ファイル(グローバル定義のmsgFデータ構造で識別される)から指定のメッセージを取得します。addMessage()の呼び出し時にメッセージ データが供給された場合は、取得時にそのメッセージ データが自動的に挿入されます。お分かりのとおり、メッセージ テキストおよび2次レベル テキストを取得するのに多少のポインター操作が必要になります。

もちろん、このルーチンでは、要求されたメッセージが確かに存在していること(存在しないメッセージIDを要求したのではないこと)のチェックを行います。

メッセージ カウントを取得する

u_message_Count()サブプロシージャーは、現在、格納されているメッセージの数を返すだけです。

 //--------------------------------------------------
 // Message Count - returns the number of stored messages

dcl-Proc u_message_Count export;
  dcl-Pi *n int(10) end-Pi;

  return msgCount;
end-Proc; 

格納されているメッセージを取得する

u_get_Message()サブプロシージャーは、1番目のパラメーターで指示されたメッセージを取得します。返されるデータは、メッセージ フォーマット データ構造です。このサブプロシージャーは、有効な格納メッセージが要求されているかどうかをチェックします。

 //--------------------------------------------------
 // Clear messages
 //--------------------------------------------------
 // Get Message - Get the Message identified by the No.

dcl-Proc u_get_Message export;
  dcl-Pi *n;
    forMessage int(10) const;
    msgFormat  likeDs(def_MsgFormat);
  end-Pi;


  if forMessage > 0 and forMessage <= msgCount;
    msgFormat = messages(forMessage);
  else;
    clear msgFormat;
    msgFormat.msgText = '*** Message Not Found ***';
  endIf;
  return;
end-Proc; 

次回の記事に続く

次回の記事では、これらのメッセージ サブプロシージャーがアプリケーションでどのように使用されるかについて見て行きます。また、有用と思われる、他のいくつかのメッセージ サブプロシージャーについても見て行きます。

IBM Championにして『Re-engineering RPG Legacy Applications』の著者であるPaul Tuohy氏は、IBMミッドレンジ界におけるアプリケーションのモダナイゼーションおよび開発テクノロジーの分野で非常に著名なコンサルタント兼トレーナーです。現在は、アイルランドのダブリンのコンサルタント会社、ComCon社のCEOを務める傍ら、「System i Developer」コンソーシアムの運営にもパートナーとして参画しています。Susan Gantner氏およびJon Paris氏とともに、年2回、RPG & DB2 Summit を主催しています。

ページトップ

ボタン