ExitCode Spec

JVLinkToSQLite — 終了コード（Exit Codes）

概要

本書は JVLinkToSQLite のコマンドライン/実行フローで返される終了コード（プロセス終了コード）の意味をまとめた草稿です。終了コードは以下の層に分かれます：

• 0: 正常終了（ReturnCodeRanges.Success / ReturnCodes.Success）
• JV-Link ネイティブの戻り値（JVLink の各 API が返す値。多くは負の値）
• 本プロジェクト固有の例外用コード（ReturnCodeRanges.UnkownException 等）
• コマンドライン／プログラム共通の制御用コード（ReturnCodes 列挙）

以下、詳細を示します。ソースの該当箇所は主に ReturnCodeRanges.cs、ReturnCodes.cs、JVLinkWrappers\JVOpenResult.cs、JVLinkWrappers\JVReadResult.cs、Operators\JVLinkServiceOperationResult.cs、JVLinkToSQLite\MainOptionsHandler.cs、OptionsHandler<T>.cs です。

---

数値と意味（要点）

1) プログラム共通の終了コード（ReturnCodes）

JVLinkToSQLite\ReturnCodes.cs に定義される CLI レベルのコード（数値はソースから計算）：

• Success = 0
  • 正常終了。OptionsHandler<T>.Main / 多くの成功ルートで返されます。
• OptionNotParsed = -3001
  • コマンドラインが未解析（-m none 等でヘルプ表示）した場合に返されます。(MainOptionsHandler.TryProcessByUninvocableOption)
• Warning = -3002
  • 警告。たとえば CreateDefaultSetting で上書き確認で拒否した場合に返す実装があります。
• Error = -3003
  • 汎用エラー。OptionsHandler<T>.Main の catch ブロック等で使用されます。

数値の由来：ReturnCodeRanges にてレンジを分けており、上記は UrasandesuJVLinkToSQLiteEnd よりさらに下位の値として定義されています（詳細は次節）。

---

2) レンジ概要（ReturnCodeRanges）

Urasandesu.JVLinkToSQLite\ReturnCodeRanges.cs により終了コードのレンジが決められています。

• ReturnCodeRanges.Success = 0
• JVLinkEnd = -1000
  • 以降（0 より下、-1 .. -999）は主に JV-Link ライブラリが返す値（JVOpen / JVRead 等）。
• UrasandesuJVLinkToSQLiteStart = -2000
  • ラッパー側（当プロジェクト）で使う範囲の上限。
• UnkownException = -2001
  • ラッパーがキャッチした未知の例外を示す値（JVLinkServiceOperationResult.Exception が使用）。
• UrasandesuJVLinkToSQLiteEnd = -3000
  • プロジェクト固有レンジの下限（さらに下に CLI 固有コードが続く）。

---

3) JV-Link（ライブラリ）由来の戻り値（例）

JVOpenResult / JVReadResult に記載されている代表的なコードと意味（抜粋）：

• JVOpen 関連（JVOpenResult.SetReturnCodeCore）
  • 0 : 正常
  • -1 : 該当データ無し（取得対象なし）
  • -2 : セットアップダイアログでキャンセル
  • -111 ～ -116 : パラメータ不正（dataspec, fromtime, key, option 等）
  • -201 : JVInit が行われていない
  • -202 : 前回の Open が閉じられていない（オープン中）
  • -301 ～ -305 : 認証／利用キー関連エラー
  • -401, -411 ～ -413, -421, -431 : サーバー／内部エラー
  • -501, -504 : スタートキット無効やメンテナンス等
  • （その他、SetUnknownReturnCode を呼んで「不明な戻り値」と扱う場合あり）
• JVRead 関連（JVReadResult.SetReturnCodeCore）
  • > 0 : バッファにセットしたデータサイズ（成功）
  • 0 : 全ファイル読み込み終了（EOF）
  • -1 : ファイル切り替わり（EOF ではない、バッファにデータは返らない）
  • -3 : ファイルダウンロード中（少し待つべき）
  • -201, -202, -203 : JVInit/JVOpen 未実行やオープン状態等
  • -402, -403 : ダウンロードしたファイルが異常（サイズ/内容）
  • -502, -503 : ダウンロード失敗 / ファイルが見つからない

（注）上記は JVOpenResult.cs / JVReadResult.cs 内の SetReturnCodeCore 実装から抜粋しています。各コードに対して DebugMessage と DebugCauseAndTreatment が設定されます。

---

どの状況でどの終了コードがそのままプロセス終了値になるか

• CLI の実行メイン（OptionsHandler<T>.Main → MainOptionsHandler）では、各モード実行後に int を返し、その値がプロセス終了コードになります。
• MainOptionsHandler.ExecuteCore / WatchEventCore：
  • 各 settingDetail の処理結果集合（oprAgg.OperateAll()）で AreAllSucceeded が false の場合、retCode = rsltAgg.FirstReturnCode として最初の失敗コードを採用します。
  • したがって、JV-Link の戻り値（例：-502 等）やラッパーが生成する UnkownException（-2001）がそのまま返る可能性があります。
• 例外ハンドル：
  • OptionsHandler<T>.Main の try/catch で捕まった例外は (int)ReturnCodes.Error（-3003）を返します。
  • JVLinkServiceOperationResult.Exception は ReturnCodeRanges.UnkownException（-2001）を返す用途で使われます（内部処理で Exception が発生したケースの集約結果）。
• オプション未解析やヘルプ表示：
  • MainOptionsHandler.TryProcessByUninvocableOption でヘルプ表示した場合は OptionNotParsed（-3001）を返します。
• ユーザー操作（上書き確認で拒否）：
  • CreateDefaultSetting の上書き確認でユーザーが「y」以外を入力した場合は Warning（-3002）を返します。

---

推奨されるドキュメント構成（README への小節案）

• 概要：終了コードの階層（成功 / JV-Link / ラッパー / CLI）
• 数値一覧（表形式で 値 / 定数名 / 意味 / 発生箇所 を列挙）
• よくあるケース（例: データ無し = -1、ダウンロード失敗 = -502、オプション未解析 = -3001）
• トラブルシューティング（DebugMessage / DebugCauseAndTreatment を参照する方法）
• 参考：主要ソースの参照箇所（ファイル名と関数）

---

追加メモ（実装参照箇所）

• Urasandesu.JVLinkToSQLite\ReturnCodeRanges.cs
• JVLinkToSQLite\ReturnCodes.cs
• Urasandesu.JVLinkToSQLite\JVLinkWrappers\JVOpenResult.cs
• Urasandesu.JVLinkToSQLite\JVLinkWrappers\JVReadResult.cs
• Urasandesu.JVLinkToSQLite\Operators\JVLinkServiceOperationResult.cs
• JVLinkToSQLite\MainOptionsHandler.cs
• JVLinkToSQLite\OptionsHandler\ (generic)

---

必要なら上記をそのまま docs/EXIT_CODES.md（あるいは README の節）として整形します。
どの程度の詳細（全コードを網羅した表、あるいは代表的なコードだけ）で仕上げたいか指示をください。