最初のころ、APIにエラーコードはありませんでした。いつのころからか出現したのですが、互換性維持のため、エラーコードが無いころのAPIは、エラーコードは任意指定で、新しくできたAPIは、エラーコードを必須扱いしているようです。
きちんとしたプログラムで、恒常的に使用するAPIプログラムは、やはりエラーコードを指定するのが「お行儀」です。
簡単です。
APIのエラーコードの構造は、
オフセット |
使用 |
タイプ |
フィールド |
10進数 |
16進数 |
0 |
0 |
入力 |
BINARY(4) |
提供されるバイト数 |
4 |
4 |
出力 |
BINARY(4) |
使用可能バイト数 |
8 |
8 |
出力 |
CHAR(7) |
例外 ID |
15 |
F |
出力 |
CHAR(1) |
予約済み |
16 |
10 |
出力 |
CHAR(*) |
例外データ |
となっています。
提供されるバイト数
は、このエラーコード全体の長さを指定するものです。
ここに0をセットする場合は、このエラーコード構造は使用されず、直接APIからエラーが戻されます。プログラムメッセージとなるでしょう。
ここに8をセットすると、エラーコードの8バイトまでが使用され、実質、モニター可能なのは、「使用可能バイト数」のみとなります。最初の4バイトは、「提供されるバイト数」自身のものです。
ここに16を入れた場合は「例外ID」、さらに17以上を入力すると「例外データ」も利用できます。
例えば、例外データを100バイト使いたい場合は、100 + 16 (BIN4 + BIN4 +
CHAR7 + 1 =16) なので、116を「提供されるバイト数」にセットします。
使用可能バイト数
とは、戻されたエラーの長さです。エラーの長さは、上記構造の長さを意味します。ここが0ならば、戻されたエラーは無いことになります。また、0でなければ、「提供されるバイト数」から「例外データ」までのバイト数が戻されます。
例外ID
とは、エラーのメッセージIDが入ります。
例外データ
とは、そのエラーのメッセージIDのメッセージデータです。メッセージIDの&1などに入る情報のことです。
ここで、マニュアルの例を解説します。
1.2.6.1.3
例外データなしでのエラー・コードの受取り例(マニュアルより)
この適用業務例は、ライブラリー QGPL 内のメッセージ・ファイル
USRMSG 内のメッセージ識別コード USR1234
の警報を作成しようとするものです。この適用業務はエラー・コード・パラメーターにエラー状態を受け取りますが、挿入データは受け取りません。これを実行するために、適用業務は、提供されるバイト数、使用可能なバイト数、例外
ID, および予約されているフィールドに対して、16バイトの長さのエラー・コード・パラメーターを割り振ります。エラー・コード・パラメーターの提供されるバイト数フィールドは、16
にセットされます。
適用業務が警報の生成 (QALGENA)
を呼び出した場合には、警報テーブル USRMSGは見つからず、QALGENA
は例外 CPF7B03
を返してきます。エラー・コード・パラメーターには、以下の表に示すデータが入っています。この例では、データに対して
16 バイトが提供されていますが、使用可能なバイト数は 36
です。提供されるバイト数フィールドがもっと大きければ、さらに
20 バイトのデータを返すことが可能です。
フィールド |
入力 |
出力 |
提供されるバイト数 |
16 |
16 |
使用可能バイト数 |
無視 |
36 |
例外 ID |
無視 |
CPF7B03 |
予約済み |
無視 |
0 |
|
解説
このCPF7B03は「警報テーブル &2/&1 が見つからない
」というメッセージです。「使用可能バイト数」が36なので、本来戻されるエラー構造の全体は36バイトということになるのです。それで、提供されるバイト数の指定が16で、36
- 16 = 20なので、本来は、後20バイトデータがあることを意味しています。別に、例外IDだけでよければほっといても、問題ありません。
この20バイトは、下図の&1(10)+&2(10)の合計20バイトのことです。
CPF7B03とは「警報テーブル &2/&1 が見つからない 」のことです。 小数部 構成
FIELD データ・タイプ 桁数 分桁数 桁数 DUMP
&1 *CHAR 10 *NO
&2 *CHAR 10 *NO |
1.2.6.1.4 例外データがあるエラー・コードの受取り例
(マニュアルより) この適用業務例は、ライブラリー QGPL
内のメッセージ・ファイル USRMSG 内のメッセージ識別コード USR1234
の警報を作成しようとするものです。この適用業務はエラー・コード・パラメーターにエラー状態を受け取り、また例外挿入データも受け取ります。これを実行するためには、適用業務は、116
バイトの長さのエラー・コード・パラメーターを割り振ります。このうち
16 バイトは提供されるバイト数、使用可能なバイト数、例外 ID、および予約されているフィールド用で、100バイトは例外についての挿入データ用です。(場合によっては、挿入データは可変長のディレクトリーまたはファイルの名前のことがあり、100
バイトでは全データを保留することができない可能性があります。この場合には、エラー・コード・パラメーター内に収まるだけのデータが返されます。)最終的に、提供されるバイト数フィールドは
116 にセットされます。
適用業務が警報の生成 API (QALGENA)
を呼び出した場合には、警報テーブルUSRMSG は見つからず、QALGENA
は例外 CPF7B03
を返してきます。エラー・コード・パラメーターには以下のものが入っています。
フィールド |
入力 |
出力 |
提供されるバイト数 |
116 |
116 |
使用可能バイト数 |
無視 |
36 |
例外 ID |
無視 |
CPF7B03 |
予約済み |
無視 |
0 |
例外データ |
無視 |
USRMSG QGPL |
|
解説
ここでは、「提供されるバイト数」を116にしていますよね。つまり、例外データを100バイトにしているわけです。そして、先ほどの36-16の20バイトは、この中に含まれました。
の&1と&2の合計20バイトが「例外データ」として、取り込まれたわけです。
自分は、エラーコード必須の場合、「提供されるバイト数」を116にして、エラー構造はすべて定義しています。最後の例外データの長さは、100バイトです。
|