%HANDLER (handlingProcedure : communicationArea )

%HANDLER は、プロシージャーを識別して、1 つのイベントまたは一連のイベントを処理するために使用します。%HANDLER は値を戻しません。また、XML-SAX および XML-INTO の第 1 オペランドとしてのみ指定できます。

第 1 オペランド handlingProcedure は、処理プロシージャーのプロトタイプを指定します。 戻り値およびプロトタイプによって指定されたパラメーターは、 処理プロシージャーが必要とするパラメーターと一致している必要があります。 要件は、%HANDLER が指定されている命令によって決まります。 処理プロシージャーの定義に関する特定の要件については、XML-SAX (XML 文書の構文解析)および XML-INTO (XML 文書の変数への構文解析)を参照してください。

第 2 オペランド communicationArea は、処理プロシージャーのすべての呼び出しでパラメーターとして渡される変数を指定します。 オペランドは、参照によって渡されるプロトタイプ化されたパラメーターの検査で使用する規則と同じ規則に従って、 処理プロシージャーの最初のプロトタイプ・パラメーターに完全に一致してい る必要があります。 通信域パラメーターには、配列やデータ構造など、任意のタイプを使用できます。

命令コードが %HANDLER 組み込み関数を使用している場合は、以下の一連のイベントが発生します。

  1. %HANDLER 組み込み関数を使用する命令が開始します。
  2. 処理プロシージャーが処理する必要がある命令の最中にイベントが発生した場合は、RPG ランタイムは、%HANDLER の第 1 オペランドとして指定されている処理プロシージャーを呼び出します。 処理プロシージャーに渡される最初のパラメーターは、%HANDLER の第 2 オペランドとして指定された通信域です。 他のパラメーターは、命令および発生したイベントの性質によって異なります。
  3. 処理プロシージャーは、通信域パラメーターを更新する可能性があるパラメーターを処理します。
  4. 処理プロシージャーは、正常終了した場合にはゼロを戻し、正常に終了しなかった場合はゼロ以外の値を戻します。
  5. 戻り値がゼロの場合、RPG ランタイムは、命令が完了するか、他のイベントが発生するまで処理を継続します。 戻り値がゼロではなかった場合、命令は終了します。
  6. 他のイベントが発生した場合は、処理プロシージャーが再び呼び出されます。 処理プロシージャーを呼び出した直前の呼び出しが通信域を変更した場合、 その変更は後続の呼び出しで確認できます。
  7. 命令完了時に、制御は %HANDLER 組み込み関数を使用したその命令の次のステートメントに渡されます。 処理プロシージャーが通信域を変更した場合は、その変更は、%HANDLER 組み込み関数を使用してプロシージャーで確認できます。

通信域は、複数の目的で使用できます。

  1. %HANDLER 組み込み関数をコード化するプロシージャーから処理プロシージャーに情報を通知します。
  2. 処理プロシージャーから %HANDLER 組み込み関数をコード化するプロシージャーに、情報を通知します。
  3. 処理プロシージャーの連続的な呼び出しの間で、状態情報を保持します。 状態情報は、処理プロシージャー内の静的変数にも保持できます。 ただし、静的変数が使用されている場合に、処理プロシージャーが、複数の %HANDLER 命令によって使用可能になっている場合、 誤った結果になる場合があります。 通信域パラメーターを使用することによって、 処理プロシージャーの使用法は、それぞれ独立します。
図 203. %HANDLER を使用した通信域の使用
 * Data structure used as a parameter between
 * the XML-SAX operation and the handling
 *  procedure.
 *   - "attrName" is set by the procedure doing the
 *     XML-SAX operation and used by the handling procedure
 *   - "attrValue" is set by the handling procedure
 *     and used by the procedure doing the XML-SAX
 *     operation
 *   - "haveAttr" is used internally by the handling
 *     procedure
D info            DS
D   attrName                    20A    VARYING
D   haveAttr                      N
D   attrValue                   20A    VARYING

 * Prototype for procedure "myHandler" defining
 * the communication-area parameter as being
 * like data structure "info"
D myHandler       PR            10I 0
D   commArea                           LIKEDS(info)
D   event                       10I 0  VALUE
D   string                        *    VALUE
D   stringLen                   20I 0  VALUE
D   exceptionId                 10I 0  VALUE
 /free
   // The purpose of the following XML-SAX operation
   // is to obtain the value of the first "companyname"
   // attribute found in the XML document.

   // The communication area "info" is initialized with
   // the name of the attribute whose value is
   // to be obtained from the XML document.
   attrName = 'companyname';

   // Start SAX processing.  The procedure "myHandler"
   // will be called for every SAX event; the first
   // parameter will be the data structure "info".
   xml-sax(e) %handler(myHandler : info) %xml(xmldoc);
   // The XML-SAX operation is complete.  The
   // communication area can be checked to get the
   // value of the attribute.
   if not %error() and attrValue <> '';
     dsply (attrName + '=' + attrValue);
     endif;
:
:
 * The SAX handling procedure "myHandler"
P myHandler       B
D                 PI            10I 0
D   comm                               LIKEDS(info)
D   event                       10I 0  VALUE
D   string                        *    VALUE
D   stringLen                   20I 0  VALUE
D   exceptionId                 10I 0  VALUE
D value           S          65535A    VARYING
D                                      BASED(string)
D ucs2value       S          16383C    VARYING
D                                      BASED(string)
D rc              S             10I 0  INZ(0)
/free

     select;

     // When the event is a "start document" event,
     // the handler can initialize any internal
     // subfields in the communication area.
    when event = *XML_START_DOCUMENT;
        comm.haveAttr = *OFF;

     // When the event is an "attribute name" event,
     // and the value of the event is the required
     // name, the internal subfield "haveAttr" is
     // set to *ON.  If the next event is an
     // attribute-value event, the value will be
     // saved in the "attrValue" subfield.
     when event = *XML_ATTR_NAME
     and  %subst(value : 1 : stringLen) = comm.attrName;
        comm.haveAttr = *ON;
        comm.attrValue = '';

     // When "haveAttr" is on, the data from any
     // attribute-value should be saved in the "attrValue"
     // string until the *XML_END_ATTR event occurs
     when comm.haveAttr;
        select;
        when event = *XML_ATTR_CHARS
        or event = *XML_ATTR_PREDEF_REF;
           comm.attrValue +=
               %subst(value : 1 : stringLen);
        when event = *XML_ATTR_UCS2_REF;
           stringLen = stringLen / 2;
           comm.attrValue +=
               %char(%subst(ucs2value : 1 : stringLen));
        when event = *XML_END_ATTR;
           // We have the entire attribute value
           // so no further parsing is necessary.
           // A non-zero return value tells the
           // RPG runtime that the handler does
           // not want to continue the operation
           rc = -1;
    endsl;

    endsl;

   return rc;
 /end-free
P                 E

その他の %HANDLER の例については、XML-SAX (XML 文書の構文解析)および XML-INTO (XML 文書の変数への構文解析)を参照してください。

詳しくは、XML 命令または 組み込み関数を参照してください。