133. API エラー報告
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エラー処理の例がほとんどない。
以上のことを理解した上で次のサンプルRPGソースを参照して頂きたい。
【 サンブルRPG 】
H DFTNAME(TESTAPI) DATEDIT(*YMD/)
F********** API エラー報告 ********************************************
F**********************************************************************
D USRSPC DS
D USNAME 1 10
D USLIB 11 20
D APIERR DS
D GETBYT 1 4B 0 INZ(160)
D AVLBYT 5 8B 0 INZ(0)
D MSGID 9 15
D MSGDTA 17 160
D SPCBIN DS
D INZSIZE 1 4B 0 INZ(1000)
D MSGDTALEN 5 8B 0 INZ(100)
D PGMSTKCNT 9 12B 0 INZ(1)
D CPFMSG C CONST('QCPFMSG *LIBL ')
C*( ユーザースペースの作成 )
C MOVEL 'MYSPACE ' USNAME
C MOVEL 'ATEMP ' USLIB
C*----------------------------------------------------+
C CALL 'QUSCRTUS' 99
C PARM USRSPC
C PARM 'PF ' ATTR 10
C PARM INZSIZE
C PARM INZCHR 1
C PARM '*ALL ' PUBAUT 10
C PARM 'MYSPACE' USRTXT 50
C PARM '*YES ' REPLCE 10
C PARM APIERR
C*----------------------------------------------------+
C AVLBYT IFNE *ZEROS
C MOVEL CPFMSG MSGFILLIB
C*----------------------------------------------------+
C CALL 'QMHSNDPM' 99
C PARM MSGID
C PARM MSGFILLIB 20
C PARM MSGDTA
C PARM MSGDTALEN
C PARM '*COMP ' MSGTYPE 10
C PARM '*PGMBDY ' PGMQUE 10
C PARM PGMSTKCNT
C PARM MSGKEY 4
C PARM APIERR
C*----------------------------------------------------+
C END
C SETON LR
【 解説 】
この API : QUSCRTUS によるユーザー・スペースの作成はライブラリー名を ATEMP という
名前にして意図的にエラーが発生するようにしている。
API エラー・コードの構造に合わせて MSGID と MSGDTA を取り出して API: QMHRTVM
を使ってメッセージに組み立てて、メッセージ を出力している。
