# FWATCHの使い方

※ 以下はVer1.8について記述したものです。

## トラブルシューティング

過去にお問い合わせいただいた件で多かったものです。

- 「アプリケーション」が起動しない → OPENアクションでドキュメント名を指定している場合は、それがエクスプローラ上からダブルクリックで開けることを確認してください。
- 「アプリケーション」が起動しない2 → 実行ファイルを指定している場合、そのユーザの環境変数PATHで検索できるか、もしくは絶対パスで指定していることを確認してください。(後者が確実でしょう。)
- 「アプリケーション」が起動しない3 → ファイル名をワイルドカード「*」にしてアクションが実行されるか確認してください。FWatchの実行時のユーザから対象フォルダにアクセス権があることを確認してください。
- 「アプリケーション」がうまく起動しない4 → バッチファイルやVBScriptなどを指定している場合、それが想定しているカレントディレクトリに合わせてあるか確認してください。
- その他 → ログレベルを10ぐらいにあげてFWatchがファイル変更を認識しているか確認してください。ログを見れば、だいたい状況が分ると思います。

まず、FWatchを最初に設定するときにはログレベルを5以上にして動作確認されることを推奨いたします。

ログは「日 時 (ログレベル) [Win32スレッドID] メッセージ」の形式で記録されます。

既定ではログファイルは日付が変ると*.bakファイルに移動(上書き)され、ログファイルはサイズが0に戻ります。

また、*.bakファイルは一世代しか作成されません。

したがって、連続運用する場合でもログファイルがあふれるということはありません。

(FWatchではなく何らかのログツールでログを採取・待避する場合は、設定ファイルでfwatchがログをローテートしないように、またログファイルを常に閉じるように調整してください。)

たとえば、監視ディレクトリが存在しない場合は以下のようなエラーが記録されます。

    *2011/02/02 22:52:08.280 (0) [1904] ファイル監視ハンドルの作成に失敗しました。
    ERROR CODE=2 指定されたファイルが見つかりません。

    *2011/02/02 22:52:08.296 (0) [1904] ディレクトリの最初のファイルの取得に失敗しました。
    dir=D:\Media\Desktop\fwatchtest\testdir\
    ERROR CODE=3 指定されたパスが見つかりません。

たとえば、アプリケーションが見つからない場合は以下のようなエラーが記録されます。

    *2011/02/02 22:52:50.826 (2) [1904] アプリケーションを起動します。
    Verb=OPEN
    AppName=D:\Media\Desktop\fwatchtest\testcmd.cmd
    Parameter="D:\Media\Desktop\fwatchtest\testdir\"  ".\新しいテキスト ドキュメント.txt"  "."  0  1  0  0  0
    CurrentDir=D:\Media\Desktop\fwatchtest\testdir\
    *2011/02/02 22:52:50.842 (0) [1904] アプリケーションの起動に失敗しました。
    ERROR CODE=2 指定されたファイルが見つかりません。

※ 上記のERROR CODE=???は、通常はWin32のエラーコードです。MSDNでエラー理由を調べることができます。

## FWatchの仕組みとパラメーターの調整方法

FWatchはファイルが更新されたことを検知して何らかのアクションを起こすものですが、ファイルを操作しているアプリケーションと直接連携しているわけではありません。

アプリケーションによってファイルを一括して書き込むものもあれば、複数回にわけて追記的に作成するもの、あるいは一旦削除したのちにワークファイルを作成してから結合するもの、など様々です。

しかし、FWatchは、あくまでも、ファイルの状態だけをみて、更新を判断しています。(そのため、ファイルを作成するアプリケーションであれば、アプリケーションの種類は問いません。)

これらのファイルの作成方法の違いを吸収できるようにFWatchには監視方法に、いくつかの調整項目を持たせています。

これらのパラメーターを調整するためには、FWatchが、内部的に、どのような処理をしているのか理解する必要があります。

FWatchの仕組みとして以下の点が重要となります。

- FWatchが使用しているWindowsのファイルの追加・変更通知APIは、対象フォルダに対して行われます。実際に「どのファイルが変更されたか」については通知されません。
  - したがって、通知を受けてからフォルダを全スキャンして、前回の全スキャン結果と比較して、どこが変更されたのかFWatchが判断する必要があります。
  - この仕組みのため、通知があるたびに全ファイルの状態をスキャンする必要があり、その原理上、多数のファイルを監視するには適していません。
  - 前回スキャンと今回スキャンの差で判断しますから、スキャンの間に２回以上の同一ファイルの更新があったとしても、1つの更新としてしか関知できません。
    同一ファイルの更新を監視したい場合、原理的に、このようなタイミングで、前の状態の変更を「とりこぼす」ことに注意してください。(最終的な状態を、とりこぼすことはありません。)
  - 監視状態を保存してFWatchを終了後、次回FWatch起動時に監視状態が復元されフォルダの変更を検知した場合でも、もちろん、 FWatchが起動していない間に同一ファイルが何回変更されたかなどは分かりません。終了前と開始時のスキャン結果の差でしかありません。
  - スキャンに時間がかかる場合、その間の変更は次回の再スキャンが予約されます。またスキャンが完了しないかぎりアクションは発生しません。
    したがってスキャンに時間がかかると
    1. アクションの開始タイミングが遅れる。
    2. スキャンばかり何度も繰り返してマシンパワーを消耗する。
    3. １回のスキャンにかかる時間内に２回以上の更新があった場合は、それらは１回の更新と見なされる。
    というような状況になります。
  - → 現在のFWatchは、もともとWindows95/NT4をターゲットに作られたため、これが制約となります。
- FWatchが使用しているWindowsのファイルの追加・変更通知APIはネットワークでの使用に、あまり適していません。
  - ネットワークの監視を行っても通知されない場合があります。(自分または相手がWindows98もしくはLinuxのSMBの場合など。)
  - ネットワークが一時的に切断されるなどの原因で監視が無効となった場合でもエラーが発生せず、その後、通知が来なくなる場合があります。
  - → 対応として、定期フォルダチェックによる強制チェックとフォルダ監視APIの再作成で定期的にエラーを回復させます。(環境と利用方法に応じて調査・調整が必要です。)
  - → ネットワークドライブは、そもそも通知が信用ならないので、定期フォルダチェック一本で認識させる、という考えもあります。
- そもそもファイルの書き込みが完了したかどうか厳密に判断する方法がない。
  - 大きなファイルのコピーや転送、あるいは追記的にファイルが作成される場合など、ファイルが作成されてから完了するまで時間がかかる場合、いつ完了したのかは明確には判断できません。
  - アプリケーションによってはファイルを削除してから、他のプロセスを呼び出して追記して…、とファイルが完成するまで、複数のプロセスにまたがってアクセスしている場合があります。
  - → 対応として、「ファイルサイズが落ち着くまで待機」で、ここで指定した時間ファイルに変化がなければ完了したものと見みなします。
    また、削除してから書き込みを開始するケースでは「ファイル削除検出を保留する時間」で削除を一時的に無視するように設定します。(これらはアプリケーションによって調査・調整が必要です。)
  - (別解として、対象ファイルを直接監視するのではなく、対象ファイルが完了した通知用のファイルを別に作ってもらう。自分で出力側を制御できるのならば、これが一番確実です。)
  - ※ このファイルサイズを確認する仕組みの弊害として、アクセス権がないファイルが作成された場合、アクセスできるようになるまで永久に該当ファイルを確認しつづけます。
    (このような場合で、監視対象ファイルが多い場合、チェック処理が休み無く延々とつづくためCPU負荷が上がる場合があります。その場合はFWatch.iniで基本サイクルを調整する必要があります。)
  - ※ 変更通知を受けたあとにネットワークにアクセスできない状態が発生すると、これもアクセス待ちとなり、回復するまで遅延となります。

FWatchは上記のような原理でファイルを監視しているため、マシンへの負荷とファイル更新を正しく判定できる最小値のバランスを調査しながら調整してゆく必要があります。

とはいえ、ローカルマシン上の単一フォルダで1000個程度のファイルの通常の更新チェックをするのであれば、デフォルト値で十分使えるものと思われます。

これらの調査・調整を行う場合には、ある程度詳細なログ出力を行いながら実験を繰り返す必要があります。(ただし、ログ出力も、それなりに時間のかかる処理だということに注意してください。)