エラー情報の取得

エラー情報取得機能は，CBLXML-GET-ERRORサービスルーチンによってXMLアクセスルーチンの詳細なエラー情報を取得する機能です。

XMLアクセスルーチンのエラー情報を取得するには，XMLドキュメントを開くXMLアクセスルーチンの前にCBLXML-CREATE-XML-POINTERサービスルーチンを呼び出して作成した空のポインタを用いて，XMLポインタを入力するアクセスモード"E"を指定し，XMLドキュメントを開くXMLアクセスルーチンを呼び出さなければなりません。また，XMLドキュメントを閉じるXMLアクセスルーチンのあとにCBLXML-FREE-XML-POINTERサービスルーチンを呼び出してCBLXML-CREATE-XML-POINTERサービスルーチンで作成したXMLポインタを解放しなければなりません。これらを行い，各XMLアクセスルーチンの直後にCBLXML-GET-ERRORサービスルーチンで呼び出すことでエラー情報を取得できます。

次にXMLドキュメントを開くCBLXML-OP-Interfaceアクセスルーチンのエラー情報の取得例を示します。

（エラー情報の取得）

  :
01 CBLXML-RETURN-CODE PIC 9(9) COMP.
01 FILE-NAME PIC X(255).
01 XML-FILE-NAME USAGE POINTER VALUE NULL.
01 XML-FILE-NAME-LENGTH PIC 9(9) COMP VALUE 0.
01 XML-MODE PIC X(16).
01 XML-POINTER USAGE POINTER VALUE NULL.
01 MESSAGE-BUFFER PIC X(255).
01 MESSAGE-BUFFER-LENGTH PIC 9(9) COMP VALUE 255.
01 MESSAGE-LENGTH PIC 9(9) COMP VALUE 0.
  :
PROCEDURE DIVISION.
START-MAIN.
  :
    CALL 'CBLXML-CREATE-XML-POINTER'
        USING XML-POINTER.
    IF RETURN-CODE NOT = 0 THEN
        EXIT PROGRAM
    END-IF.
*open
    MOVE 'WE' TO XML-MODE.
    MOVE 'output.xml' TO FILE-NAME.
    MOVE 10 TO XML-FILE-NAME-LENGTH.
    COMPUTE XML-FILE-NAME = FUNCTION ADDR(FILE-NAME).
    CALL 'CBLXML-OP-EXAMPLE'
        USING XML-FILE-NAME
              XML-FILE-NAME-LENGTH
              XML-MODE
              XML-POINTER
        RETURNING CBLXML-RETURN-CODE.
 
    IF CBLXML-RETURN-CODE NOT = 0 THEN
        CALL 'CBLXML-GET-ERROR'
            USING XML-POINTER
                  MESSAGE-BUFFER
                  MESSAGE-BUFFER-LENGTH
                  MESSAGE-LENGTH
        DISPLAY 'ERROR = ' MESSAGE-BUFFER
    ELSE
*write
        CALL 'CBLXML-WR-EXAMPLE-BE'
            USING XML-POINTER root
            RETURNING CBLXML-RETURN-CODE
*close
        CALL 'CBLXML-CL-EXAMPLE'
            USING XML-POINTER
            RETURNING CBLXML-RETURN-CODE
    END-IF.
 
    CALL 'CBLXML-FREE-XML-POINTER'
        USING XML-POINTER.
  :

＜この項の構成＞: (1)　CBLXML-GET-ERRORサービスルーチン; (2)　XMLアクセスルーチンのエラー情報

(1)　CBLXML-GET-ERRORサービスルーチン

直前に実行したXMLアクセスルーチンの詳細なエラー情報を取得します。エラー情報の取得対象となるXMLアクセスルーチンを次に示します。

（エラー情報の取得対象となるXMLアクセスルーチン）

CBLXML-OP-Interface
CBLXML-OB-Interface
CBLXML-RD-Interface-BaseElement
CBLXML-WR-Interface-BaseElement
CBLXML-CL-Interface
CBLXML-CN-Interface

形式: CALL 'CBLXML-GET-ERROR' USING XML-POINTER MESSAGE-BUFFER MESSAGE-BUFFER-LENGTH MESSAGE-LENGTH.

引数

引数のデータ型	指定	説明
01 XML-POINTER USAGE POINTER.	○	XMLドキュメントのポインタを受け取るポインタ項目を指定する。
01 MESSAGE-BUFFER PIC X(n).	○	エラー情報を受け取る領域を英数字項目で指定する。
01 MESSAGE-BUFFER-LENGTH PIC 9(9) COMP.	○	エラー情報を受け取る領域の長さを4バイトの2進項目で指定する。
01 MESSAGE-LENGTH PIC 9(9) COMP.	△	受け取ったエラー情報の長さが設定される。この項目は4バイトの2進項目で指定する。

（凡例）: ○：サービスルーチンの呼び出し時，値を設定しておく項目; △：サービスルーチンの完了時，値が設定される項目

戻り値

戻り値	内容
1	エラー情報の長さがエラー情報を受け取る領域の長さを超えた。
0	正常終了した。
-1	CBLXML-GET-ERRORサービスルーチンの引数の値が不正である。
-2	操作を続けるためのメモリが不足した。

注: 戻り値は，RETURN-CODE特殊レジスタに設定されます。

規則

受け取るエラー情報がない場合，MESSAGE-LENGTHに0が返されます。
MESSAGE-BUFFER-LENGTHに指定した長さより，受け取るエラー情報の長さが長い場合は，MESSAGE-BUFFER-LENGTHに指定した長さでエラー情報を切り捨てます。ただし，切り捨て位置が多バイト文字の途中の場合は，MESSAGE-BUFFER-LENGTHに指定した長さより1バイト短くなってMESSAGE-LENGTHに設定されます。MESSAGE-BUFFERの多バイト文字で切り捨てられる領域には半角空白文字が設定されます。
各アクセスルーチンのエラー情報を取得する場合，CBLXML-OP-InterfaceアクセスルーチンとCBLXML-OB-Interfaceアクセスルーチンでアクセスモード"E"を指定しなければなりません。アクセスモード"E"を指定しない場合，CBLXML-OP-InterfaceアクセスルーチンとCBLXML-OB-Interfaceアクセスルーチンのステータスが0で正常終了してもCBLXML-GET-ERRORサービスルーチンでエラー情報を取得できません。
Unicode機能を設定した場合，引数2で受け取るXMLパーサのエラーメッセージは，文字コードがUTF-8の文字列が返ります。引数3に指定した長さ（1バイト1文字）より，エラー情報の文字列が長い場合，引数3に指定した長さで文字列を切り捨てます。切る位置が文字を構成する多バイト列の途中の場合，該当する文字以降を文字単位に切り捨てます。

(2)　XMLアクセスルーチンのエラー情報

CBL-GET-ERRORサービスルーチンによって得られるエラー情報を表 9-4に示します。また，エラー情報の***番号***は，表 9-5に示す埋め字情報に従って埋め字に置き換わります。

表9-4　エラー情報

ステータス	エラー情報	埋め字情報
0	（ステータス0はエラー情報を出力しない）	－
1	[1]△要素"*1*"を出力できない。	* 1 *: DTD
3	[3]△"*1*"を出力できない。	* 1 *: DTD
4	[4]△BaseElement要素に対応する要素を見つけられない。	－
5	[5]△BaseElement要素"*1*"を飛ばして，次のBaseElement要素を入力できない。	* 1 *: DTD
6	[6]△要素"*2"の選択要素に対して，1*個選択したために出力を決定できない。	*1:選択要素で出力しようとした個数 2*:選択要素の直下にある要素名
7	[7]△出力の＋付き要素の繰り返し回数に0が設定されている。	－
8	[8]△"*1*"に不当な文字がある。	* 1 *: Document
9	[9]△出力時のファイルまたはバッファを開けない。	－
10	[10]△"*1*"に入力した値がデータ項目の長さを超えた。	* 1 *: Document
11	[11]△"*1*"に不当な文字が設定されている。	* 1 *: DTD
12	[12]△XMLドキュメントを1回も更新していない。	－
13	[13]△更新の対象を指定しないでXMLドキュメントを更新した。	－
15	[15]△直前に同じBaseElement要素単位の入力を呼び出していない。	－
101	[101]△メモリを確保できない。	－
103	[103]△XMLドキュメントを開けない。	－
104	[104]△XMLドキュメントを閉じることができない。	－
105^※1	[105]△アクセスモードに不当な値が設定された。	－
106	[106]△ファイルに出力できない。	－
109	[109]△再帰的に定義された要素は出力できない。	－
110	[110]△XMLドキュメントの解析でエラーが発生した。;*1*	* 1 *: XMLパーサのメッセージ
111	[111]△BaseElement要素に対応した要素が見つからない。	－
114	[114]△引数に無効なパラメタが指定された。	－
115	[115]△要素の出力中に指定したバッファ領域の長さに達した。	－
117	[117]△出力でファイルI／Oエラーが発生した。	－
118	[118]△ドキュメントを閉じることができない。	－
119	[119]△一つのXMLポインタに対して複数のXMLドキュメントを開こうとした。	－
121	[121]△内部エラーが発生した。	－
122^※2	[122]△-unisrcオプションの指定と環境変数CBLLANGの設定に矛盾がある。	－
123^※3	[123]△-unisrcオプションの指定と環境変数LANGの設定に矛盾がある。	－
124^※4	[124]△互換性がない古いXMLアクセスルーチンを使用している。	－

（凡例）: △：半角空白文字; －：埋め字情報はありません。

注※1: アクセスモード"E"を指定した場合だけ取得できます。

注※2: PC，HP-UX(IPF)，AIX，Linux(x86)，Linux(x64)の場合だけ出力されます。

注※3: HP-UX(IPF)，AIX，Linux(x86)，Linux(x64)の場合だけ出力されます。

注※4

PC(x64)，UNIX64の場合だけ出力されます。

表9-5　埋め字情報

埋め字の種類	埋め字に出力する情報
DTD	埋め字に示される要素は「/」文字を区切り文字として，階層でルート要素から「ルート要素/要素/要素」を出力する。属性は「@」文字を区切り文字として「要素@属性」で出力する。
Document	埋め字に示される要素は「/」文字を区切り文字として，階層でルート要素から「ルート要素/要素/要素」を出力する。要素が繰り返しである場合，繰り返し順序を示す"[番号]"を要素に付ける。DTDで"*"または"+"によって繰り返しがあることが指定されている要素でも，XMLドキュメント中に1回しか現れない要素については，繰り返し順序を示す"[番号]"は付け加えられない。番号は1から開始し，取得できる要素の繰り返しの番号は，2,147,483,647までである。それを超えた場合は，保証しない。属性は"@"文字を区切り文字として"要素@属性"で出力する。
XMLパーサのメッセージ	XMLパーサが返すメッセージを出力する。

9.3.2 エラー情報の取得

(1) CBLXML-GET-ERRORサービスルーチン

(2) XMLアクセスルーチンのエラー情報

9.3.2　エラー情報の取得

(1)　CBLXML-GET-ERRORサービスルーチン

(2)　XMLアクセスルーチンのエラー情報