i5/OS の API ( = Application Programing Interface ) とは
IBM が i5/OS で実際に使用しているプログラムをユーザーでも使えるようにと
その仕様を公開したものである。
例えばオブジェクトの一覧: QUSLOBJ やユーザー・スペースの作成: QUSCRTUS など
かなりの数の便利プログラムとして公開されている。
API を苦もなく使えるようになればあなたの開発者としての実力は
飛躍的に向上するはずである。

API の内容についてはこちらで紹介しているし
API の使い方の一部もこちらで過去に紹介している。
ここでは API を使うに当たって API のエラー・コードの使い方を解説する。
API のエラー・コードの設定や使い方によって
API の特性をより生かすことができるようになる。
また合わせて IBM マニュアルのあいまいさや間違いについても言及していく。

最初に API のエラー・コードはすべての API で統一された同じ形式である。

【API エラー・コードの構造体】

　 * API エラー・コード
　D APIERR          DS                  QUALIFIED
　D  GETBYT                 1      4B 0 INZ(160)
　D  AVLBYT                 5      8B 0 INZ(0)
　D  MSGID                  9     15
　D  MSGDTA                17    160

【解説】

GETBYT :

API エラー構造体の長さを入れる。ここでは全体の長さ 160 を
定義しておく。
この長さも意味があり GETBYT の長さが 8 バイト以上に設定されていると
API エラーが発生したときは少なくとも MSGID の値を戻す。
これによって開発者はエラーの MSGID を知ることはできる。
しかしエラーのときは MSGDTA も受け取らないとエラーの詳細は
不明となるのでエラーの詳細を受け取りたいのであれば
GETBYT を 160 に設定しておくべきである。

一方、GETBYT を 0 に設定することもできる。
GETBYT が 0 に設定されていると API はエラーを戻すことができないので
そのまま CPF エラー・メッセージが送信される。
この場合は MSGID や MSGDTA を調べる必要がなく、
自動的にエラー・メッセージが送出されるのである意味、便利である。
API の使用がまだ初心者のうちはむしろ GETBYT は 0 に設定しておくことを
お勧めする。
GETBYT が 0 であるということは API エラー・コードがないのと同じである。

AVLBYT :

最初は 0 にセットして API に渡すとエラーが発生したときは
MSGDTA の長さが戻される。
IBM マニュアルには「使用可能なエラー情報の長さ」とあいまいな表現で
解説されているがエラーとして戻したときの MSGDTA の長さのことである。
また注意して欲しいのは IBMマニュアルには
「この値が 0 であれば、それはエラーがなかったことを意味します。」と
あるのは完全な誤りであり、ABLBYT が MSGDTA の長さを示している限り
MSGDTA がない CPF エラーが発生したときはこの値は 0 であるが
結果はエラーであることがある。
多くの場合は AVLBYT が 0 であればエラーは発生せず成功裡に完了したという
確率がかなり高いというに過ぎない。
一般的にはエラーかどうかは、この AVLBYT の値が 0 かどうか
(つまり 0 であれば成功)ということで判断してよいが
ごく稀に 0 であってもエラーである場合がある、ということを
覚えていて欲しい。
IBM のマニュアルの解説はほぼ合格点ではあるが完全な正解とはいえない。

MSGID  :

API がエラーを戻したときの CPF エラー・メッセージ識別コード (MSGID) が
ここに戻される。
メッセージ・ファイルやライブラリーの記述はないが MSGID は
必ず QSYS/QCPFMSG のものが戻されるのでメッセージ・ファイルなどの
定義は行われていない。

MSGDTA :

CPF メッセージとともに与えられるメッセージ・データであり
この長さは AVLBYT に定義されている。
従って MSGID と MSGDTA, ABLBYT を組み合わせれば
API: QMHRTVM (メッセージの検索) を使えばメッセージに組み立てることが
できる。

(1) AVLBYT を 0 に設定したエラー API 報告の受取り

  D APIERR          DS
  D  GETBYT                 1      4B 0 INZ(0)
  D  AVLBYT                 5      8B 0 INZ(0)
  D  ECPERR                 9     15
  D  ECP                   16     16
  :
  C*----------------------------------------------------+
  C                   CALL      'QUSRJOBI'
  C                   PARM                    RCV400
  C                   PARM                    RCVLEN
  C                   PARM      'JOBI0400'    FORMAT            8
  C                   PARM                    JOBINFO
  C                   PARM                    JOBID            16
  C                   PARM                    APIERR
  C*----------------------------------------------------+

(2) AVLBYT を 160 に設定したエラー API 報告の受取り

　D APIERR          DS                  QUALIFIED
　D  GETBYT                 1      4B 0 INZ(160)
　D  AVLBYT                 5      8B 0 INZ(0)
　D  MSGID                  9     15
　D  MSGDTA                17    160

　C*----------------------------------------------------+
　C                   CALL      QMHRTVM
　C                   PARM                    RTVM0300
　C                   PARM                    RCVLEN
　C                   PARM      'RTVM0300'    FORMAT
　C                   PARM                    MSGID
　C                   PARM                    JPNMSGLIB
　C                   PARM                    MSGDTA
　C                   PARM                    MSGDTALEN
　C                   PARM      '*YES      '  REPDTA           10
　C                   PARM      '*YES      '  REPCHR           10
　C                   PARM                    APIERR
　C                   PARM                    OPTION
　C                   PARM                    CCSID_FROM
　C                   PARM                    CCSID_TO
　C*----------------------------------------------------+
　 * CPF2419: EOF
　C                   IF        APIERR.AVLBYT > 0
　:
　C                   ENDIF