25.7.2 サービスルーチンの説明
- 〈この項の構成〉
-
(1) CBLHTMLBEGIN
HTMLの先頭部分を出力するサービスルーチンです。CBLHTMLBEGINサービスルーチンが出力する内容を,次に示します。
<HTML> <HEAD> <TITLE> 引数1 </TITLE> </HEAD> <BODY>
- 形式
CALL 'CBLHTMLBEGIN' USING 引数1
- 引数
- 戻り値
-
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
HTMLの終端部分を出力するサービスルーチンです。CBLHTMLENDサービスルーチンが出力する内容を,次に示します。
</BODY> </HTML>
- 形式
CALL 'CBLHTMLEND'
- 引数
-
なし。
- 戻り値
-
0:正常終了した場合
-1:エラーが発生した場合(標準出力に出力できない場合)
- 規則
-
HTMLテンプレートを使用する場合,CBLFILLTEMPLATEサービスルーチンやHTMLトランスレータによってHTMLの先頭部分が自動生成されるので,CBLHTMLENDサービスルーチンは使用しないでください。
- 使用例
-
「(1) CBLHTMLBEGIN」の使用例を参照してください。
(3) CBLDISPLAYTEXT
引数に指定された文字列を出力するサービスルーチンです。
- 形式
CALL 'CBLDISPLAYTEXT' USING 引数1
- 引数
-
引数1には,次に示すインタフェース領域の名前を指定します。
表25‒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には,次に示すインタフェース領域の名前を指定します。
表25‒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の出力例
SHOW AN <O PTION>.
- 実体参照での表した文字の一覧
-
- 注意事項
-
-
日本語などの多バイト文字は,CBLCONVERTTEXTで変換されません。また,環境変数LANGに指定した値によって次の表のようになります。
環境変数LANGの設定値によって有効となる
文字コード※
変換しない文字
シフトJISコード
シフトJISコードは変換しない。
日本語EUCコード
日本語EUCコードは変換しない。
上記以外
「実体参照での表記の一覧」に記載されている文字以外は無視する。
- 注※
-
環境変数LANGの設定値と文字コードについては,「付録A COBOLで使用する文字集合」を参照してください。
「実体参照での表記の一覧」に記載されている文字,および環境変数LANGの指定によって変換されない文字以外の文字を使用できません。
-
(5) CBLPRINTENV
CGI環境変数の名前と現在の値を,HTML形式で出力するサービスルーチンです。
出力される環境変数の種類については,「25.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には,次に示すインタフェース領域の名前を指定します。
表25‒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リストに追加します。
環境変数LANGの設定値によって有効となる
文字コード※
「値」が分割される位置
シフトJISコード
「値」の文字列は,シフトJISコードとして1,024バイトをチェックします。1,024バイトが2バイトコードの先頭バイトの場合は,1,023バイトで文字列が分割されます。それ以外の場合は,1,024バイトに文字列が分割されます。
日本語EUCコード
「値」の文字列は,日本語EUCコードとして1,024バイトをチェックします。1,024バイトが2バイトコードの先頭バイトの場合は,1,023バイトで文字列が分割されます。それ以外の場合は1,024バイトに文字列が分割されます。
上記以外
無条件に「値」を1,024バイトで分割してCGIリストに追加します。
- 注※
-
環境変数LANGの設定値と文字コードについては,「付録A COBOLで使用する文字集合」を参照してください。
名前 = "NAME1"と値="(3,000バイト)"を受け取って,CGIリストに追加する例を示します。
名前
値
NAME1
1,024バイト
NAME1
1,024バイト
NAME1
952バイト
-
受け取れるフォーム情報の「名前」と「値」のデコードされていない最大の文字列長は,デフォルトで64キロバイトです。64キロバイトを超える文字列長の場合は,CBLCGIINITサービスルーチンで-3が返され,処理が中断されます。
最大文字列長を変更する場合は,環境変数CBLCGIINITSIZEを使用します。
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
CGIリストを削除して,領域を解放するサービスルーチンです。
- 形式
CALL 'CBLDESTROYLIST' USING 引数1
- 引数
-
引数1には,削除するCGIリストのアドレスを,アドレスデータ項目で指定します。
- 戻り値
-
0:正常終了した場合
-1:エラーが発生した場合(領域の解放に失敗した場合など)
- 規則
-
CGIリストを削除したあとの,CGIリストのポインタの内容は保証しません。
- 使用例
-
「(7) CBLCGIINIT」の使用例を参照してください。
(10) CBLADDPAIR
指定したCGIリストの最後に,「名前」と「値」の対を追加するサービスルーチンです。
- 形式
CALL 'CBLADDPAIR' USING 引数1 引数2 引数3
- 引数
-
-
引数1には,CBLCGIINITやCBLCREATELISTで作成したCGIリストのアドレスを,アドレスデータ項目で指定します。
-
引数2には,CGIリストに追加する「名前」を,28バイトの英数字項目で指定します。
-
引数3には,次に示すインタフェース領域の名前を指定します。
表25‒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には,次に示すインタフェース領域の名前を指定します。
表25‒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には,次に示すインタフェース領域の名前を指定します。
表25‒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には,次に示すインタフェース領域の名前を指定します。
表25‒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には,次に示すインタフェース領域の名前を指定します。
表25‒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テンプレートからあらかじめ生成した共用ライブラリファイルを,実行時に呼び出せます。HTMLテンプレートについては,「25.6 HTMLテンプレート機能」を参照してください。
- 形式
CALL 'CBLFILLTEMPLATE' USING 引数1 引数2
- 引数
-
-
引数1には,HTMLテンプレート名を,256バイトの英数字項目で指定します。
-
引数2には,HTMLテンプレートで使用するCGIリストのアドレスを,アドレスデータ項目で指定します。
-
- 戻り値
-
0:正常終了した場合
-1:エラーが発生した場合(標準出力に出力できない場合)
- 規則
-
-
引数1に指定するファイル名のパス指定には,次の3種類があります。
-
絶対パス名
(例:/usr/local/httpd/cgi-bin/filename)
-
環境変数PATH_TRANSLATEDの相対パス名
(例:/cgi-bin/filename)
-
CGIプログラムのあるディレクトリからの相対パス名
ファイル名だけ,またはファイルインジケータ(..)を使ったファイル名が,相対パス名として指定できます。(例:../filename)
ただし,エイリアス指定の仮想ディレクトリにあるファイルは,絶対パス名で指定してください。
-
引数1には,共用ライブラリファイル(.a),HTMLファイル(.htm,または.html)※,または拡張子なしのファイル名が指定できます。拡張子なしのファイル名を指定した場合,次の順序でファイルが検索されます。
1. 共用ライブラリファイル
2. HTMLファイル(拡張子.htm)
3. HTMLファイル(拡張子.html)
- 注※
-
HTMLファイルの拡張子は,大文字と小文字は等価とみなされます。
-
引数1に指定したHTMLテンプレート名や共用ライブラリ名の末尾に空白文字があった場合,その空白はファイル名に含まれません。
-
呼び出す共用ライブラリプログラムの名称は,共用ライブラリファイル名と同じになります。引数1に指定する共用ライブラリファイル名に次のような文字列が含まれる場合,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リストのアドレス" >
- 取得済みCGIリストのアドレスを指定した場合(CGIリストのアドレスがNULL以外の場合)
-
<! CBLCGIINIT(); list = second call (error) >
CBLCREATELIST
- 正常終了した場合
-
<! CBLCREATELIST(); list = " CGIリストのアドレス" >
- 取得済み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(); list = " CGIリストのアドレス" At end >
CBLFINDNEXTPAIR
- 正常終了した場合
-
<! CBLFINDNEXTPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
- 検索した名前が見つからない場合
-
<! CBLFINDNEXTPAIR(); list = " CGIリストのアドレス" At end >
CBLGETPAIR
- 正常終了した場合
-
<! CBLGETPAIR(); list = " CGIリストのアドレス", name = "名前", value = "値" >
- 名前/値を取得できない場合(空のCGIリスト,CGIリストのポインタが終端)
-
<! CBLGETPAIR(); list = " CGIリストのアドレス" At end >
CBLGETPAIRNEXT
- 正常終了した場合
-
<! CBLGETPAIRNEXT(); list = " CGIリストのアドレス", name = "名前", value = "値" >
- 名前/値を取得できない場合(空の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 > :