%HANDLER (handlingProcedure : communicationArea )
%HANDLER は、1 つのイベントまたは一連のイベントを処理するプロシージャーを識別するために使用します。%HANDLER は値を戻しません。また、XML-SAX および XML-INTO の第 1 オペランドとしてのみ指定できます。
第 1 オペランド handlingProcedure は、処理プロシージャーのプロトタイプを指定します。プロトタイプによって指定された、またはプロトタイプが明示的に指定されていない場合にはプロシージャー・インターフェースによって指定された戻り値およびパラメーターは、 処理プロシージャーが必要とするパラメーターと一致している必要があります。 要件は、%HANDLER が指定されている命令によって決まります。 処理プロシージャーの定義に関する特定の要件については、XML-SAX (XML 文書の構文解析)および XML-INTO (XML 文書の変数への構文解析)を参照してください。
第 2 オペランド communicationArea は、処理プロシージャーのすべての呼び出しでパラメーターとして渡される変数を指定します。オペランドは、参照によって渡されるプロトタイプ・パラメーターの検査で使用する規則と同じ規則に従って、 処理プロシージャーの最初のプロトタイプ・パラメーターに完全に一致してい る必要があります。 通信域パラメーターには、配列やデータ構造など、任意のタイプを使用できます。
命令コードが %HANDLER 組み込み関数を使用している場合は、以下の一連のイベントが発生します。
- %HANDLER 組み込み関数を使用する命令が開始します。
- 処理プロシージャーが処理する必要がある命令の最中にイベントが発生した場合は、RPG ランタイムは、%HANDLER の第 1 オペランドとして指定されている処理プロシージャーを呼び出します。 処理プロシージャーに渡される最初のパラメーターは、%HANDLER の第 2 オペランドとして指定された通信域です。 他のパラメーターは、命令および発生したイベントの性質によって異なります。
- 処理プロシージャーは、パラメーターを処理する際に通信域パラメーターを更新することがあります。
- 処理プロシージャーは、正常終了した場合にはゼロを戻し、正常に終了しなかった場合はゼロ以外の値を戻します。
- 戻り値がゼロの場合、RPG ランタイムは、命令が完了するか、他のイベントが発生するまで処理を継続します。 戻り値がゼロではなかった場合、命令は終了します。
- 他のイベントが発生した場合は、処理プロシージャーが再び呼び出されます。 処理プロシージャーを呼び出した直前の呼び出しが通信域を変更した場合、 その変更は後続の呼び出しで確認できます。
- 命令完了時に、制御は %HANDLER 組み込み関数を使用したその命令の次のステートメントに渡されます。 処理プロシージャーが通信域を変更した場合は、その変更は、%HANDLER 組み込み関数を使用したプロシージャーで確認できます。
通信域は、複数の目的で使用できます。
- %HANDLER 組み込み関数をコード化するプロシージャーから処理プロシージャーに情報を通知します。
- 処理プロシージャーから %HANDLER 組み込み関数をコード化するプロシージャーに、情報を通知します。
- 処理プロシージャーの連続的な呼び出しの間で、状況情報を保持します。 状況情報は、処理プロシージャー内の静的変数にも保持できます。 ただし、静的変数が使用されている場合に、処理プロシージャーが、複数の %HANDLER 命令によって使用可能になっている場合、 誤った結果になる場合があります。 処理プロシージャーは、それぞれ独立して使用できるようになります。
図 1. %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 文書の変数への構文解析)を参照してください。