API を使用するときにも API のエラーのモニター処理をしていないとそのまま、あたかもエラーが
起こらなかったのかのように処理を進めていくと予測できない結果を生じる。
またエラーの発見が困難になってしまうのでAPI の実行にも、必ずエラー処理を行うようにして
おきたいものである。
API のエラー・コードはシステムAPI 解説書に説明されているが説明が適切でない部分があるため、
ユーザーにとってややわかりにくいものとなっている。
ここでは、その意味と使用方法を解説する。
さて、API のエラー・コードはすべて統一されていて次の形式をしている。
| 開始位置 | 使用 | タイプ | 項目の説明 |
|---|---|---|---|
| 1 | 入力 | BIN(4) | エラー・コード全体の長さ (=116) |
| 5 | 出力 | BIN(4) | API から戻された長さ |
| 9 | 出力 | CHR(7) | エラー・メッセージ ID (MSGID) |
| 16 | 出力 | CHR(1) | 予約済み(未使用) |
| 17 | 出力 | CHR(100) | メッセージ・データ (MSGDTA) |
【 解説 】
エラーがなくAPI が正常に終了した場合には、「API から戻された長さ」は 0 であり、
「API から戻された長さ」が 0 でない場合は、エラーが発生したものと判別することができる。
次にエラーが発生したとすると「エラー・メッセージ ID 」には QCPFMSG のメッセージ識別コード(MSGID) が戻る。
そして「メッセージ・データ」が、このエラー・メッセージに対するメッセージ・データとして戻るのである。
このことが IBM システムAPI 解説書 には明記されていないため、読み手が理解しにくい
状況になっているのと同時に APIエラー処理の例がほとんどない。
以上のことを理解した上で次のサンプルCLソースを参照して頂きたい。
【 サンブルCLP 】
PGM
/*---------------------------------------------------------*/
/* TESTAPI : ＡＰＩエラー処理 */
/*---------------------------------------------------------*/
DCL VAR(&APIERR) TYPE(*CHAR) LEN(116) +
VALUE(X'000074') /* 2 進数 */
DCL VAR(&NULL4) TYPE(*CHAR) LEN(4) +
VALUE(X'00000000')
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(100)
/*( ユーザー・スペースの作成 )*/
CALL PGM(QUSCRTUS) PARM('MYSPACE +
ATEMP ' 'PF ' 1000 ' ' +
'*ALL ' 'INZLIB 用ユーザー空間 ' +
'*YES ' &APIERR)
MONMSG CPF9870
IF COND(%SST(&APIERR 5 4) *NE &NULL4) THEN(DO)
CHGVAR VAR(&MSGID) VALUE(%SST(&APIERR 9 7))
CHGVAR VAR(&MSGDTA) VALUE(%SST(&APIERR 17 100))
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) +
TOMSGQ(*SYSOPR) MSGTYPE(*COMP)
ENDDO
GOTO END
END:
ENDPGM
【 解説 】
この API : QUSCRTUS によるユーザー・スペースの作成はライブラリー名を ATEMP という
名前にして意図的にエラーが発生するようにしている。
API エラー・コードの構造に合わせて MSGID と MSGDTA を取り出して API: QMHRTVM
を使って
メッセージに組み立てて、メッセージ を出力している。