サービスルーチンの説明

HTMLの先頭部分を出力するサービスルーチンです。CBLHTMLBEGINサービスルーチンが出力する内容を，次に示します。

 
<HTML>
<HEAD>
<TITLE> 引数1 </TITLE>
</HEAD>
<BODY>

形式

CALL 'CBLHTMLBEGIN' USING 引数1

引数: 引数1には，Webブラウザのタイトルバーに表示する文字列を，128バイトの英数字項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（標準出力に出力できない場合）

規則

HTMLテンプレートを使用する場合，CBLFILLTEMPLATEサービスルーチンやHTMLトランスレータによってHTMLの先頭部分が自動生成されるので，CBLHTMLBEGINサービスルーチンは使用しないでください。
Webブラウザのタイトルバーに表示される文字数は，使用するWebブラウザの種類によって異なります。また，Webブラウザによっては，タイトルバーに表示する文字列の中に連続した空白がある場合，一つの空白に置き換えて出力するものもあります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 TITLE-NAME PIC X(128).
       PROCEDURE DIVISION.
           MOVE 'This my test title' TO TITLE-NAME.
           CALL 'CBLHTMLBEGIN' USING TITLE-NAME.
           CALL 'CBLHTMLEND'.

(2)　CBLHTMLEND

(3)　CBLDISPLAYTEXT

引数に指定された文字列を出力するサービスルーチンです。

形式

CALL 'CBLDISPLAYTEXT' USING 引数1

引数

引数1には，次に示すインタフェース領域の名前を指定します。

表27-5　CBLDISPLAYTEXTサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	出力する文字列の長さを4バイトの2進項目で指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	出力する文字列を可変長英数字項目で指定する。最大1,024バイトまで指定できる。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（標準出力に出力できない場合）

規則: CBLDISPLAYTEXTサービスルーチンが出力する文字列の終端には，改行文字("\n")が追加されません。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMEX.
         02 NAME-LEN PIC S9(9) USAGE COMP.
         02 NAME-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON NAME-LEN.
       PROCEDURE DIVISION.
           COMPUTE NAME-LEN = FUNCTION LENGTH('COBOL').
           MOVE 'COBOL' TO NAME-STRING.
           CALL 'CBLDISPLAYTEXT' USING NAMEX.

(4)　CBLCONVERTTEXT

引数に指定した文字列を，実体参照の形式に変換して出力するサービスルーチンです。

実体参照とは，HTML言語で予約されているため表示できない文字を，別の文字列を使って表す記法です。例えば，HTML言語では「＜」「＞」の文字が予約されているため，実体参照ではこれを「<」「>」と表します。

形式

CALL 'CBLCONVERTTEXT' USING 引数1

引数

引数1には，次に示すインタフェース領域の名前を指定します。

表27-6　CBLCONVERTTEXTサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	変換して出力する文字列の長さを4バイトの2進項目で指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	変換して出力する文字列を可変長英数字項目で指定する。最大1,024バイトまで指定できる。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（標準出力に出力できない場合）

規則: 日本語などの多バイト文字は，CBLCONVERTTEXTサービスルーチンで実体参照文字に変換されません。詳細については，以降の注意事項を参照してください。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMEX.
         02 NAME-LEN PIC S9(9) USAGE COMP.
         02 NAME-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON NAME-LEN.
       01 TEXT-STR PIC X(17) VALUE 'SHOW AN <OPTION>.'.
       PROCEDURE DIVISION.
           :
           COMPUTE NAME-LEN = FUNCTION  LENGTH (TEXT-STR).
 
           MOVE TEXT-STR TO NAME-STRING.
           CALL 'CBLCONVERTTEXT' USING NAMEX.

HTMLの出力例

&#83;&#72;&#79;&#87;&#32;&#65;&#78;&#32;&#60;&#79;
&#80;&#84;&#73;&#79;&#78;&#62;&#46;

実体参照での表した文字の一覧: 実体参照での表記の一覧を，次に示します。

注意事項

シフトJISコードの漢字は，CBLCONVERTTEXTで変換されません。
実体参照での表した文字の一覧に示す文字，およびシフトJISコードの漢字以外の文字列を，CBLCONVERTTEXTで変換しないでください。

(5)　CBLPRINTENV

CGI環境変数の名前と現在の値を，HTML形式で出力するサービスルーチンです。

出力される環境変数の種類については，「27.4　CGI環境変数へのアクセス」を参照してください。

形式

CALL 'CBLPRINTENV'

引数: なし。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（標準出力に出力できない場合）

規則: 環境変数に値が設定されていない場合，「（NULL）」が出力されます。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLPRINTENV'.
           :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

HTMLの出力例

<HTML>
   <BODY>
<H3> Environment variable list: </H3>
AUTH_TYPE= (NULL) <BR>
CONTENT_LENGTH= 0 <BR>
CONTENT_TYPE= (NULL) <BR>
GATEWAY_INTERFACE= CGI/1.1 <BR>
 :
 :
   </BODY> 
</HTML>

(6)　CBLGETENV

環境変数の値を取得するサービスルーチンです。

形式

CALL 'CBLGETENV' USING 引数1 引数2

引数

引数1には，環境変数名を28バイトの英数字項目で指定します。

引数2には，次に示すインタフェース領域の名前を指定します。

表27-7　CBLGETENVサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	取得した環境変数の値（文字列）の長さを格納する領域で，4バイトの2進項目で指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	取得した環境変数の値を格納する領域で，最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（該当する環境変数が見つからない場合）; 1：環境変数の値が1,024バイトを超えている場合

規則

環境変数に値が設定されていない場合，引数2のデータ名2には0が，データ名3にはNULL文字が返されます。また，RETURN-CODE特殊レジスタの値は0になります。
指定した環境変数名の末尾が空白文字の場合，環境変数の内容は取得されません。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMEX PIC X(28) VALUE 'REMOTE_HOST'.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLGETENV' USING NAMEX VALUEX.
           IF RETURN-CODE = 0 THEN
             DISPLAY 'THE CLIENT MACHINE IS ' VALUE-STRING
           ELSE
             DISPLAY 'ERROR'
           END-IF.

(7)　CBLCGIINIT

フォーム情報からCGIリストを作成し，リストのアドレスを取得するサービスルーチンです。フォーム情報がPOSTメソッド（標準出力経由），GETメソッド（環境変数経由）のどちらから転送されても，CGIリストを作成できます。

また，-TDInfオプションを指定してコンパイルしたCGIプログラムでCBLCGIINITサービスルーチンが呼び出されると，CGI用環境変数の値をCGI環境ファイル（実行可能ファイル名.env）として，CGIプログラムと同じフォルダに出力します。

形式

CALL 'CBLCGIINIT' USING 引数1

引数: 引数1には，作成したCGIリストのアドレスを格納する領域で，アドレスデータ項目を指定します。

戻り値: 1：環境変数CBLCGIINITSIZEに不当な値を設定した場合; 0：正常終了した場合; -1：エラーが発生した場合; -2：POST，GET以外をメソッドに指定した場合; -3：フォーム情報の文字列長が制限値（デフォルトは64キロバイト），または環境変数CBLCGIINITSIZEで指定した値を超えた場合

変換規則

フォーム情報から引き渡される「値」の長さが1,024バイトを超える場合，1,024バイト（または1,023バイト）で分割した「値」をCGIリストに追加します。「値」の文字列は，シフトJISコードとして1,024バイトがチェックされます。1,024バイト目が2バイトコードの先頭バイトの場合は，1,023バイトで文字列が分割されます。それ以外の場合は，1,024バイトで文字列が分割されます。
名前 = "NAME1"と値="(3,000バイト)"を受け取って，CGIリストに追加する例を示します。

名前値

NAME1 1,024バイト

NAME1 1,024バイト

NAME1 952バイト
受け取れるフォーム情報の「名前」と「値」のデコードされていない最大の文字列長は，デフォルトで64キロバイトです。64キロバイトを超える文字列長の場合は，CBLCGIINITサービスルーチンで-3が返され，処理が中断されます。
最大文字列長を変更する場合は，環境変数CBLCGIINITSIZEを使用します。

名前	値
NAME1	1,024バイト
NAME1	1,024バイト
NAME1	952バイト

 
CBLCGIINITSIZE=最大文字列長

1～2,000,000（単位：キロバイト）以外の値を指定した場合は64が仮定されます。この場合，CBLCGIINITサービスルーチンの戻り値は1となります。

フォーム情報の「名前」や「値」に日本語などの多バイト文字が含まれている場合，CGIリストの「名前」「値」に格納されるデータは，CGIクライアントのWebブラウザで入力された文字コードに依存します。

一般規則

CBLCGIINITサービスルーチンは，2回以上呼び出さないでください。
CGIプログラムでは，ほかのサービスルーチンを呼び出す前にCBLCGIINITサービスルーチンを呼び出してください。ただし，CBLCGITRACEサービスルーチンは除きます。
CBLCGIINITサービスルーチンでCGIリストを作成した場合，CGIサブルーチンの処理を終了する時に，CBLDESTROYLISTサービスルーチンを呼び出してCGIリストを削除する必要があります。
CBLCGIINITサービスルーチンでCGIリストを作成した場合，作成した直後のCGIリストのポイント位置は，不定となります。CGIリストのポイント位置は，CBLFINDPAIRサービスルーチンで位置づけてください。
マルチスレッド対応COBOLプログラムでCBLCGIINITサービスルーチンを呼び出した場合，CGI環境ファイルの出力内容は保証しません。
CBLCGIINITサービスルーチンが呼び出されたとき，CGIプログラムの実行を支援するサービスルーチンですでにCGIヘッダが出力されていなければ，"Content-type: text/HTML\n\n"が出力されます。
CGI環境ファイルは，REMOTE_ADDR，REMOTE_HOST環境変数の値がある場合，またはCGI環境ファイルがない場合に出力されます。
CGIリストのアドレスがNULL以外の場合，CBLCGIINITサービスルーチンの戻り値は-1となります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
            :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(8)　CBLCREATELIST

新たにCGIリストを作成し，リストのアドレスを取得するサービスルーチンです。

形式

CALL 'CBLCREATELIST' USING 引数1

引数: 引数1は，作成したCGIリストのアドレスを格納する領域で，アドレスデータ項目を指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（領域確保に失敗した場合など）

規則

CBLCREATELISTサービスルーチンでCGIリストを作成した場合，CGIサブルーチンの処理を終了する時に，CBLDESTROYLISTサービスルーチンを呼び出してCGIリストを削除する必要があります。
CBLCREATELISTサービスルーチンでCGIリストを作成した場合，作成した直後のCGIリストのポイント位置は，不定となります。
CGIリストのアドレスがNULL以外の場合，CBLCREATELISTサービスルーチンの戻り値は-1となります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMELIST USAGE ADDRESS VALUE NULL.
       PROCEDURE DIVISION.
           CALL 'CBLCREATELIST' USING NAMELIST.
            :
           CALL 'CBLDESTROYLIST' USING NAMELIST.

(9)　CBLDESTROYLIST

(10)　CBLADDPAIR

指定したCGIリストの最後に，「名前」と「値」の対を追加するサービスルーチンです。

形式

CALL 'CBLADDPAIR' USING 引数1 引数2 引数3

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，CGIリストに追加する「名前」を，28バイトの英数字項目で指定します。

引数3には，次に示すインタフェース領域の名前を指定します。

表27-8　CBLADDPAIRサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	CGIリストに追加する「値」の長さを格納する領域で，4バイトの2進項目で指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	CGIリストに追加する「値」を格納する領域で，最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（追加時，領域確保に失敗した場合など）

規則: 「名前」と「値」を追加した場合，ポイント位置は変更されません。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMELIST USAGE ADDRESS VALUE NULL.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       01 NAMEX       PIC X(28) VALUE 'Hitachi'.
       01 NAMEX-VALUE PIC X(9) VALUE 'COBOL2002'.
       PROCEDURE DIVISION.
           CALL 'CBLCREATELIST' USING NAMELIST.
           COMPUTE VALUE-LEN = FUNCTION LENGTH(NAMEX-VALUE).
           MOVE NAMEX-VALUE TO VALUE-STRING.
           CALL 'CBLADDPAIR' USING NAMELIST NAMEX VALUEX.
           CALL 'CBLDESTROYLIST' USING NAMELIST.

(11)　CBLDELETEPAIR

指定したCGIリストの現在のポイント位置から，「名前」と「値」の対を削除するサービスルーチンです。

形式

CALL 'CBLDELETEPAIR' USING 引数1

引数: 引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; 1：CGIリストが空の場合

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28) VALUE 'COBOL'.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLFINDPAIR' USING INPUTLIST  
                 NAMEX  VALUEX.
           CALL 'CBLDELETEPAIR' USING INPUTLIST.
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

規則: 「名前」と「値」を削除した場合，ポイント位置を次に移動します。それ以外の場合，ポイント位置はNULLになります。

(12)　CBLFINDPAIR

指定したCGIリストの先頭のポイント位置から「名前」を検索し，「名前」に対応する「値」を取得するサービスルーチンです。また，一致した「名前」にポイント位置を移動します。

形式

CALL 'CBLFINDPAIR' USING 引数1 引数2 引数3

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，検索する「名前」を，28バイトの英数字項目で指定します。

引数3には，次に示すインタフェース領域の名前を指定します。

表27-9　CBLFINDPAIRサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	検索した「名前」に対応する「値」の長さが格納される領域。4バイトの2進項目を指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	検索した「名前」に対応する「値」が格納される領域。最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; 1：検索した「名前」が見つからない場合，またはポイント位置が終端の場合

規則

検索した「名前」に対応する「値」がNULLの場合，引数3のデータ名2には0が出力されます。
検索した「名前」が見つからない場合，ポイント位置はNULLになります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28) VALUE 'Hitachi'.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLFINDPAIR' USING INPUTLIST NAMEX VALUEX.
           CALL 'CBLDISPLAYTEXT' USING VALUEX.
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(13)　CBLFINDNEXTPAIR

指定したCGIリストの，次のポイント位置から「名前」を検索し，「名前」に対応する「値」を取得するサービスルーチンです。また，一致した「名前」にポイント位置を移動します。

形式

CALL 'CBLFINDNEXTPAIR' USING 引数1 引数2 引数3

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，検索する「名前」を，28バイトの英数字項目で指定します。

引数3には，次に示すインタフェース領域の名前を指定します。

表27-10　CBLFINDNEXTPAIRサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	検索した「名前」に対応する「値」の長さが格納される領域。4バイトの2進項目を指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	検索した「名前」に対応する「値」が格納される領域。最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; 1：検索した「名前」が見つからない場合，または終端インジケータ（.REPEAT.TERMINATOR,1）が見つかった場合

規則

検索した「名前」に対応する「値」がNULLの場合，引数3のデータ名2には0が出力されます。
検索した「名前」が見つからない場合，ポイント位置はNULLになります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28) VALUE 'Hitachi'.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLFINDPAIR'
                 USING  INPUTLIST NAMEX VALUEX.
           CALL 'CBLDISPLAYTEXT' USING VALUEX.
           CALL 'CBLFINDNEXTPAIR'
                 USING  INPUTLIST NAMEX VALUEX.
           CALL 'CBLDISPLAYTEXT' USING VALUEX.
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(14)　CBLGETPAIR

指定したCGIリストの現在のポイント位置から「名前」と「値」の対を取得するサービスルーチンです。ポイント位置は移動しません。

形式

CALL 'CBLGETPAIR' USING 引数1 引数2 引数3

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，「名前」を格納する領域を28バイトの英数字項目で指定します。

引数3には，次に示すインタフェース領域の名前を指定します。

表27-11　CBLGETPAIRサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	「値」の長さが格納される領域。4バイトの2進項目を指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	「値」が格納される領域。最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; 1：現在のポイント位置がCGIリストの終端にあるため，「名前」および「値」が取得できない場合

規則: 「名前」と「値」の取得時にエラーが発生した場合，ポイント位置はNULLになります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28).
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLGETPAIR' USING INPUTLIST NAMEX VALUEX.
           DISPLAY 'NAME = ' NAMEX.
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(15)　CBLGETPAIRNEXT

指定したCGIリストの現在のポイント位置から「名前」と「値」の対を取得するサービスルーチンです。また，ポイント位置を次に移動します。

形式

CALL 'CBLGETPAIRNEXT' USING 引数1 引数2 引数3

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，「名前」を格納する領域を28バイトの英数字項目で指定します。

引数3には，次に示すインタフェース領域の名前を指定します。

表27-12　CBLGETPAIRNEXTサービスルーチンのインタフェース領域

記述形式	内容
01 データ名1.	CALL文のUSINGで指定するインタフェース領域の名前。
02 データ名2 PIC S9(9) USAGE COMP.	「値」の長さが格納される領域。4バイトの2進項目を指定する。
02 データ名3. 03 PIC X OCCURS 1024 DEPENDING ON データ名2.	「値」が格納される領域。最大1,024バイトの可変長集団項目を指定する。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; （現在のポイント位置がCGIリストの終端にあった場合）; 1：現在のポイント位置がCGIリストの終端にあるため，「名前」および「値」が取得できない場合

規則: 「名前」と「値」の取得時にエラーが発生した場合，ポイント位置はNULLになります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28).
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLGETPAIRNEXT'
                 USING INPUTLIST NAMEX VALUEX.
           DISPLAY ' NAME = ' NAMEX.
           CALL 'CBLGETPAIRNEXT'
                 USING INPUTLIST NAMEX VALUEX.
           DISPLAY ' NAME = ' NAMEX.
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(16)　CBLLISTCOUNT

指定したCGIリスト中の「名前」と「値」の対の数を取得するサービスルーチンです。

形式

CALL 'CBLLISTCOUNT' USING 引数1 引数2

引数

引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。
引数2には，CGIリスト中の「名前」と「値」の対の数を格納する領域を，4バイトの2進項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; （不当なCGIアドレスを指定した場合など）

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 LIST-COUNT PIC S9(9) USAGE COMP.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLLISTCOUNT'
                 USING INPUTLIST LIST-COUNT.
           IF RETURN-CODE = 0 THEN
             DISPLAY 'LIST COUNT : ' LIST-COUNT
           END-IF.
            :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(17)　CBLENDREPEAT

CGIリストにHTML拡張言語のREPEATで終端を認識する終端インジケータを追加するサービスルーチンです。終端インジケータは，特殊な名前と値（.REPEAT.TERMINATOR，1）で構成されています。

本サービスルーチンは，CGIリストの途中で%REPEAT%文を打ち切りたい場合などに使用します。

形式

CALL 'CBLENDREPEAT' USING 引数1

引数: 引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; （追加時，メモリの領域確保に失敗した場合など）

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 NAMELIST USAGE ADDRESS VALUE NULL.
        :
       PROCEDURE DIVISION.
           CALL 'CBLCREATELIST' USING NAMELIST.
           MOVE 'CITY' TO NAMEX.
           COMPUTE VALUE-LEN = FUNCTION LENGTH ('TOKYO').
           MOVE 'TOKYO' TO VALUE-STRING.
           CALL 'CBLADDPAIR' USING NAMELIST NAMEX VALUEX.
           CALL 'CBLENDREPEAT' USING NAMELIST.
           COMPUTE VALUE-LEN = FUNCTION LENGTH ('FUKUOKA').
           MOVE 'FUKUOKA' TO VALUE-STRING.
           CALL 'CBLADDPAIR' USING NAMELIST NAMEX VALUEX.
           CALL 'CBLENDREPEAT' USING NAMELIST.
            :
           CALL 'CBLDESTROYLIST' USING NAMELIST.

(18)　CBLFILLTEMPLATE

CBLFILLTEMPLATEサービスルーチンは，HTMLテンプレートをインタプリットするサービスルーチンです。また，HTMLテンプレートからあらかじめ生成したDLLファイルを，実行時に呼び出せます。ただし，DLLファイルはstdcall属性で作成しておかなければなりません。HTMLテンプレートについては，「27.6　HTMLテンプレート機能」を参照してください。

形式

CALL 'CBLFILLTEMPLATE' USING 引数1 引数2

引数

引数1には，HTMLテンプレート名を，256バイトの英数字項目で指定します。
引数2には，HTMLテンプレートで使用するCGIリストのアドレスを，アドレスデータ項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合（標準出力に出力できない場合）

規則

引数1に指定するファイル名のパス指定には，次の3種類があります。

絶対パス名
（例：c:\netservice\CGIbin\filename）
環境変数PATH_TRANSLATEDの相対パス名
（例：\CGIbin\filename）
CGIプログラムのあるフォルダからの相対パス名
ファイル名だけ，またはファイルインジケータ（..）を使ったファイル名が，相対パス名として指定できます。（例：..\filename）
ただし，エイリアス指定の仮想フォルダにあるファイルは，絶対パス名で指定してください。

引数1には，DLLファイル（.dll），HTMLファイル（.htm，または.html）^※，または拡張子なしのファイル名が指定できます。拡張子なしのファイル名を指定した場合，次の順序でファイルが検索されます。
1.　DLLファイル（拡張子.dll）
2.　HTMLファイル（拡張子.htm）
3.　HTMLファイル（拡張子.html）

注※: HTMLファイルの拡張子は，大文字と小文字は等価とみなされます。

引数1に指定したHTMLテンプレート名やDLL名の末尾に空白文字があった場合，その空白はファイル名に含まれません。
呼び出すDLLプログラムの名称は，DLLファイル名と同じになります。引数1に指定するDLLファイル名に次のような文字列が含まれる場合，COBOLのプログラム名の変換規則に注意する必要があります。
　ハイフン(－)，#，\，@，英小文字
変換規則の詳細は，マニュアル「COBOL2002　言語　標準仕様編　7.8.2 構文規則」を参照してください。
HTMLテンプレートをインタプリット中にHTML拡張言語でエラーが発生した場合，エラーメッセージの行情報がずれて出力されることがあります。
CBLFILLTEMPLATEサービスルーチンが呼び出されたとき，CGIプログラムの実行を支援するサービスルーチンですでにCGIヘッダが出力されていなければ，"Content-type: text/HTML"が出力されます。
HTMLテンプレートのインタプリット時には，コンパイラオプションの指定は無効になります。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 TMPLT-NAME PIC X(256) VALUE 'HITACHI.htm'.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLFILLTEMPLATE' USING TMPLT-NAME
                 INPUTLIST.
            :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

(19)　CBLPRINTLIST

指定したCGIリストの内容を，HTML形式で出力するサービスルーチンです。

形式

CALL 'CBLPRINTLIST' USING 引数1

引数: 引数1には，CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを，アドレスデータ項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; （標準出力に出力できない場合）

規則: CGIリストに「名前」と「値」が格納されていない場合，「名前」と「値」は出力されません。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       PROCEDURE DIVISION.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLPRINTLIST' USING INPUTLIST.
            :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

HTMLの出力例

<HTML>
   <BODY>
<H3> CGI list: </H3>
<DL>
<DT> name1
<DD> option1
<DT> name2
<DD> option2
</DL>
    </BODY>
</HTML>

(20)　CBLSENDERROR

HTML形式でエラーメッセージを出力するサービスルーチンです。

形式

CALL 'CBLSENDERROR' USING 引数1

引数: 引数1には，出力するエラーメッセージが格納されている領域を，256バイトの英数字項目で指定します。

戻り値: 0：正常終了した場合; -1：エラーが発生した場合; （標準出力に出力できない場合）

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 ERROR-MESSAGE PIC X(256) VALUE 'ERROR STRING.'.
       PROCEDURE DIVISION.
            :
           CALL 'CBLSENDERROR' USING ERROR-MESSAGE.

HTMLの出力例

<HTML>
   <HEAD>
     <TITLE>Error Message </TITLE>
   </HEAD>
   <BODY>
<BR>
<H2>!! Error Message from COBOL CGI program !!</H2>
<H3> ERROR STRING. </H3>
   </BODY> 
 </HTML>

(21)　CBLCGITRACE

CGIプログラムの作成を支援するサービスルーチンの呼び出しをトレースするサービスルーチンです。また，CGI環境変数の値も取得します。トレース情報や環境変数の情報は，トレースファイル（実行可能ファイル名.trc）に出力されます。

トレース情報には，呼び出したサービスルーチンの名称と引数情報が出力されます。例えば，CBLCGIINITでは，CGIリストのアドレスが引数情報になります。

形式

CALL 'CBLCGITRACE'

引数: なし。

戻り値: なし。

規則

CBLCGITRACEサービスルーチンは，CBLCGIINITサービスルーチンよりも先に呼び出してください。
CBLCGITRACEサービスルーチンが呼び出されると，トレースファイルは初期化されます。
CBLCGIINITサービスルーチンが呼び出されると，CGI環境変数の値をトレースファイルに出力します。
マルチスレッド対応COBOLプログラムでCBLCGITRACEサービスルーチンを呼び出した場合，トレースファイルの出力内容は保証しません。
次に示すサービスルーチンは，CBLCGITRACEサービスルーチンでトレースされません。
CBLDISPLAYTEXT
CBLPRINTENV
CBLPRINTLIST
CBLSENDERROR
CBLCGITRACEサービスルーチンが呼び出されたあとにCBLCGIINITサービスルーチンが呼び出されると，CGI環境変数の値がトレースファイルに出力されます。

出力されるトレース情報

各サービスルーチンを呼び出したときに出力されるトレース情報を，次に示します。

サービスルーチン	出力されるトレース情報
CBLHTMLBEGIN	<! CBLHTMLBEGIN(); Title = "文字列" >
CBLHTMLEND	<! CBLHTMLEND(); >
CBLDISPLAYTEXT	出力されない。
CBLCONVERTTEXT	<! CBLCONVERTTEXT(); input string = "文字列" >
CBLPRINTENV	出力されない。
CBLGETENV	<! CBLGETENV(); name = "環境変数名", value = "環境変数の値" >
CBLCGIINIT	CBLCGIINITを初めて呼び出した場合（CGIリストのアドレスがNULLの場合） <! CBLCGIINIT(); list = "CGIリストのアドレス" >
CBLCGIINIT	取得済みCGIリストのアドレスを指定した場合（CGIリストのアドレスがNULL以外の場合） <! CBLCGIINIT(); list = second call (error) >
CBLCREATELIST	正常終了した場合 <! CBLCREATELIST(); list = " CGIリストのアドレス" >
CBLCREATELIST	取得済みCGIリストのアドレスを指定した場合（CGIリストのアドレスがNULL以外の場合） <! CBLCREATELIST(); list = second call (error) >
CBLDESTROYLIST	<! CBLDESTROYLIST(); list = " CGIリストのアドレス" >
CBLADDPAIR	<! CBLADDPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
CBLDELETEPAIR	<! CBLDELETEPAIR(); list = " CGIリストのアドレス" >
CBLFINDPAIR	正常終了した場合 <! CBLFINDPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
CBLFINDPAIR	検索した名前が見つからない場合 <! CBLFINDPAIR(); list = " CGIリストのアドレス" At end >
CBLFINDNEXTPAIR	正常終了した場合 <! CBLFINDNEXTPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
CBLFINDNEXTPAIR	検索した名前が見つからない場合 <! CBLFINDNEXTPAIR(); list = " CGIリストのアドレス" At end >
CBLGETPAIR	正常終了した場合 <! CBLGETPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
CBLGETPAIR	名前／値を取得できない場合（空のCGIリスト，CGIリストのポインタが終端） <! CBLGETPAIR(); list = " CGIリストのアドレス" At end >
CBLGETPAIRNEXT	正常終了した場合 <! CBLGETPAIRNEXT(); list = " CGIリストのアドレス", name = "名前", value = "値" >
CBLGETPAIRNEXT	名前／値を取得できない場合（空のCGIリスト，CGIリストのポインタが終端） <! CBLGETPAIRNEXT(); list = " CGIリストのアドレス" At end >
CBLLISTCOUNT	<! CBLLISTCOUNT(); list = " CGIリストのアドレス", count = "名前／値の数" >
CBLENDREPEAT	<! CBLENDREPEAT(); list = " CGIリストのアドレス" >
CBLFILLTEMPLATE	<! CBLFILLTEMPLATE(); list = " CGIリストのアドレス", filename = 'テンプレート名' >
CBLPRINTLIST	出力されない。
CBLSENDERROR	出力されない。
CBLCGITRACE	<! CBLCGITRACE(); YYYY-MM-DD (HH:MM:SS) > YYYY-MM-DDは年-月-日，HH:MM:SSは時:分:秒を示す。

使用例

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 INPUTLIST USAGE ADDRESS VALUE NULL.
       01 NAMEX PIC X(28) VALUE 'COBOL'.
       01 VALUEX.
         02 VALUE-LEN PIC S9(9) USAGE COMP.
         02 VALUE-STRING.
           03 PIC X OCCURS 1024 DEPENDING ON VALUE-LEN.
       PROCEDURE DIVISION.
           CALL 'CBLCGITRACE'.
           CALL 'CBLCGIINIT' USING INPUTLIST.
           CALL 'CBLPRINTENV'.
           CALL 'CBLFINDPAIR' USING INPUTLIST NAMEX VALUEX.
            :
           CALL 'CBLDESTROYLIST' USING INPUTLIST.

トレースファイルの例

<! CBLCGITRACE();YYYY-MM-DD (HH:MM:SS)>
 
<! **** CGI ENVIRONMENT VARIABLES ***>
AUTH_TYPE= (null)
CONTENT_LENGTH= 0
 :
<! **** END OF CGI ENVIRONMENT VARIABLES ***>
 
<! CBLCGIINIT();list = 0x890980 >
 :

27.7.2　サービスルーチンの説明

(1)　CBLHTMLBEGIN

(2)　CBLHTMLEND

(3)　CBLDISPLAYTEXT

(4)　CBLCONVERTTEXT

(5)　CBLPRINTENV

(6)　CBLGETENV

(7)　CBLCGIINIT

(8)　CBLCREATELIST

(9)　CBLDESTROYLIST

(10)　CBLADDPAIR

(11)　CBLDELETEPAIR

(12)　CBLFINDPAIR

(13)　CBLFINDNEXTPAIR

(14)　CBLGETPAIR

(15)　CBLGETPAIRNEXT

(16)　CBLLISTCOUNT

(17)　CBLENDREPEAT

(18)　CBLFILLTEMPLATE

(19)　CBLPRINTLIST

(20)　CBLSENDERROR

(21)　CBLCGITRACE

27.7.2 サービスルーチンの説明

27.7.2　サービスルーチンの説明