ファイル情報APIを呼んだら、サイズが0になった。原因は空ファイルでしょうか。それともAPIの失敗でしょうか。戻り値を確認せず結果領域だけ読むと、この区別ができなくなります。
RPGからネイティブAPIを呼ぶときは、呼出しが成立すること、成功を判定すること、結果の領域を正しく解釈することを分けて考えます。ソースがコンパイルできたことだけでは、この契約が合っているとは証明できません。
API名だけで、構造体を流用しない
同じstat系の名前でも、OSや関数の種類により宣言・構造体の型が違う場合があります。インターネット上で見つけたLinuxの定義を、そのままIBM iのRPGへ移さないようにします。
IBMのstat64()資料では、戻すフィールドの型、対象の種類によるst_sizeの意味、エラーが説明されています。IBM:stat64()
確認するのは、サイズのフィールドだけではありません。それより前の項目の幅や配置が違えば、読みたい位置もずれます。
| 契約 | 照合するもの |
|---|---|
| 関数 | IBM i向けの正しい関数名・APIの種類 |
| 引数 | 型、渡し方、文字列の終端・変換、出力領域 |
| 領域 | 構造体全体の並び、各型の幅、配置 |
| 結果 | 戻り値、失敗時に参照できる情報 |
| 利用環境 | 対応リリース、実行者の権限、対象ファイルシステム |
失敗した出力領域を、正常値として読まない
処理の順序は、概念的には次のようになります。実行用のAPI実装ではありません。
1. 呼出し元へ返す状態を「未成功」に初期化する
2. APIを呼ぶ
3. 戻り値を確認する
4. 失敗なら、規定のエラー情報を速やかに取得して返す
5. 成功したときだけ結果領域を解釈する
6. 型・範囲を確認して出力値を返す
errnoを使うAPIなら、そのAPIが失敗した際の規定に沿って取得します。成功時に残っていたerrnoを新しいエラーとみなしたり、別の呼出しの後に取得して元の失敗理由だと断定したりしないようにします。
出力引数は、すべての終了経路を点検する
「戻りコード」という引数があっても、失敗時に設定しなければ呼出し元は判断できません。前回成功した値が残る場合は、今回の失敗が成功に見える危険もあります。
| 終了経路 | 確認内容 |
|---|---|
| 正常 | 成功状態と結果値が対応する |
| 入力不正 | APIを呼ぶ前に決めたエラーを返す |
| API失敗 | 失敗状態と取得できた理由を返す |
| 桁・型の不足 | 丸めや切捨てで正常に見せない |
| 例外処理 | 通常経路と矛盾しない状態で終了する |
省略可能な出力引数なら、初期化の時点でも提供されたかの確認が必要です。省略引数の扱いも合わせて確認します。
戻りコードを変えるときは、同じ数字を一括置換しない
戻り値の変更は、呼出し元の判定、コメント、ログ、試験の期待値へ影響します。返す側だけ変えても、呼出し元が未知の値を成功として扱えば意味がありません。
同じ数字が、戻り値、標識、上限値、データの一部として使われる場合もあります。文字列検索は候補の抽出に使い、代入先と用途を確かめて変更します。変更前後で、意図した戻り値以外が変わっていないことも確認します。
後続判定の前提が得られない場合の扱いは、判定不能と合格の区別も参照してください。
正常値が一つ出たら終わりにしない
既知サイズのファイル、0バイト、存在しないパス、権限不足、空白や日本語を含むパス、大きな値を使うケースを用意します。正常時の値だけでなく、失敗を正しく失敗として返せることが重要です。
対象がQNTCなどの場合は、取得する機能の対応範囲も確認します。アクセスできない理由を構造体だけの問題だと決めつけないことです。
ネイティブAPIの調査では、推測した構造体を何度も書き換える前に、公式の宣言と、呼出し直後の結果を照合します。この記事では、実機で照合していない構造体を完成コードとして掲載していません。
APIの代わりに応答を用意し、失敗判定だけを先に確認する
以下はAPIラッパーの設計例です。実際のstat64呼出しやRPGコンパイルは未実施です。まず自作の模擬応答で状態処理を点検し、その後に承認された検証環境で実APIの宣言・領域・値を照合する二段階に分けます。
模擬応答の仕様
成功時は戻り値0、失敗時は-1というstat系APIの契約を想定します。失敗時の出力領域には、わざと直前の値12345を残す試験を用意します。ここでの12345は架空値であり、実APIが失敗時にその値を返すという意味ではありません。
| 模擬応答 | ラッパーへ期待する返却 | 拾いたい欠陥 |
|---|---|---|
| 戻り値0、サイズ0 | 成功・サイズ0 | 空ファイルを失敗扱いする |
| 戻り値0、サイズ8 | 成功・サイズ8 | 型や受渡しの誤り |
| 戻り値-1、理由は権限不足相当、領域は12345 | 失敗・理由あり。サイズは未確定 | 失敗した領域を正常値として読む |
| 戻り値0、呼出し元が持てない大きな値 | 範囲不足を識別し正常値として返さない | 桁あふれを丸めて隠す |
試験は成功8→失敗→成功0の順にも行います。最終の成功0を失敗と誤認せず、中間の失敗で8や12345を正常サイズにしないことを期待します。errnoは失敗直後の規定に従って取得し、成功時に残る過去のerrnoを今回の失敗としません。
模擬試験では確認できない部分
この試験で確認できるのは、自分で作る状態判定と値の受渡しです。RPG側の型、構造体のオフセット、参照/値渡し、パスの終端、実APIの対応範囲までは証明できません。
実APIの段階では、IBM i向けヘッダー・宣言に対して全フィールドの型と配置を照合し、既知8バイト、0バイト、不在、許可された失敗条件を確認します。最初の成功値が合わないなら、構造体を推測でずらす前に戻り値と使用したAPI・定義を確認します。記録はAPI名、対象種類、戻り値、理由、成功時の値とし、実パスや資格情報を公開ログへ残しません。

