PdhOpenLogA 関数 (pdh.h)

  • [アーティクル]

指定したログ ファイルを読み取りまたは書き込み用に開きます。

構文

PDH_FUNCTION PdhOpenLogA(
  [in]  LPCSTR     szLogFileName,
  [in]  DWORD      dwAccessFlags,
  [in]  LPDWORD    lpdwLogType,
  [in]  PDH_HQUERY hQuery,
  [in]  DWORD      dwMaxSize,
  [in]  LPCSTR     szUserCaption,
  [out] PDH_HLOG   *phLog
);

パラメーター

[in] szLogFileName

開くログ ファイルの名前を指定する Null で終わる文字列。 名前には、絶対パスまたは相対パスを含めることができます。

lpdwLogType パラメーターがPDH_LOG_TYPE_SQL場合は、ログ ファイルの名前を SQL:DataSourceName! という形式で指定します。LogFileName。

[in] dwAccessFlags

ログ ファイルを開くために使用するアクセスの種類。 次のいずれかの値を指定します。

値 意味
PDH_LOG_READ_ACCESS
 ログ ファイルを開いて読み取ります。
PDH_LOG_WRITE_ACCESS
 書き込み用に新しいログ ファイルを開きます。
PDH_LOG_UPDATE_ACCESS
 書き込み用に既存のログ ファイルを開きます。
 

ビットごとの包括 OR 演算子 (|) を使用して、アクセスの種類を次の作成フラグの 1 つ以上と組み合わせることができます。

値 意味
PDH_LOG_CREATE_NEW
 指定した名前の新しいログ ファイルを作成します。
PDH_LOG_CREATE_ALWAYS
 指定した名前の新しいログ ファイルを作成します。 ログ ファイルが既に存在する場合、関数は新しいファイルを作成する前に既存のログ ファイルを削除します。
PDH_LOG_OPEN_EXISTING
 指定した名前の既存のログ ファイルを開きます。 指定した名前のログ ファイルが存在しない場合、これはPDH_LOG_CREATE_NEWと等しくなります。
PDH_LOG_OPEN_ALWAYS
 指定した名前の既存のログ ファイルを開くか、指定した名前の新しいログ ファイルを作成します。
PDH_LOG_OPT_CIRCULAR
 指定した名前の循環ログ ファイルを作成します。 ファイルが dwMaxSize パラメーターの値に達すると、データはログ ファイルの先頭に折り返されます。 このフラグは、 lpdwLogType パラメーターが PDH_LOG_TYPE_BINARYされている場合にのみ指定できます。
PDH_LOG_USER_STRING
 pdhUpdateLog または PdhOpenLog の szUserString パラメーターで示されるユーザー キャプションまたはログ ファイルの説明を書き込むには、PDH_LOG_TYPE_TSVと共に使用されます。 ユーザー キャプションまたはログ ファイルの説明は、テキスト ログの最初の行の最後の列として書き込まれます。

[in] lpdwLogType

開くログ ファイルの種類。 このパラメーターには、次の値のいずれかを指定できます。

値 意味
PDH_LOG_TYPE_UNDEFINED
 未定義のログ ファイル形式。 指定した場合、PDH はログ ファイルの種類を決定します。 dwAccessFlags パラメーターがPDH_LOG_WRITE_ACCESS場合は、この値を指定できません。
PDH_LOG_TYPE_CSV
 最初の行の列ヘッダーと、後続の各行の個々のデータ レコードを含むテキスト ファイル。 各データ レコードのフィールドはコンマ区切りです。

最初の行には、ファイルの形式、ログ ファイルの作成に使用される PDH バージョン、各カウンターの名前とパスに関する情報も含まれています。
PDH_LOG_TYPE_SQL
 ログ ファイルのデータ ソースは SQL データベースです。
PDH_LOG_TYPE_TSV
 最初の行の列ヘッダーと、後続の各行の個々のデータ レコードを含むテキスト ファイル。 各データ レコードのフィールドはタブ区切りになります。

最初の行には、ファイルの形式、ログ ファイルの作成に使用される PDH バージョン、各カウンターの名前とパスに関する情報も含まれています。
PDH_LOG_TYPE_BINARY
 バイナリ ログ ファイルの形式。

[in] hQuery

クエリ データをログ ファイルに書き込む場合は、クエリ ハンドルを指定します。 PdhOpenQuery 関数は、このハンドルを返します。

このパラメーターは無視され、ログ ファイルから読み取る場合は NULL にする必要があります。

[in] dwMaxSize

ログ ファイルの最大サイズ (バイト単位)。 ファイル サイズを制限する場合、または dwAccessFlags で PDH_LOG_OPT_CIRCULARを指定する場合は、最大サイズを指定します。それ以外の場合は、0 に設定します。

循環ログ ファイルの場合は、少なくとも 1 つのサンプルを保持するのに十分な大きさの値を指定する必要があります。 サンプル サイズは、収集されるデータによって異なります。 ただし、1 MB 以上の値を指定すると、ほとんどのサンプルがカバーされます。

[in] szUserCaption

ログ ファイルのユーザー定義のキャプションを指定する Null で終わる文字列。 ログ ファイル キャプションは、通常、ログ ファイルの内容を記述します。 既存のログ ファイルを開くと、このパラメーターの値は無視されます。

[out] phLog

開かれたログ ファイルを処理します。

戻り値

関数が成功すると、ERROR_SUCCESSが返されます。

関数が失敗した場合、戻り値は システム エラー コード または PDH エラー コードです。

注釈

この関数を使用してパフォーマンス データをログ ファイルに書き込むには、 PdhOpenQuery を使用してクエリを開き、この関数を呼び出す前に目的のカウンターを追加する必要があります。

新しいオペレーティング システムでは、古いオペレーティング システムで生成されたログ ファイルを読み取ることができます。ただし、Windows Vista 以降のオペレーティング システムで作成されたログ ファイルは、以前のオペレーティング システムでは読み取ることができません。

ログ ファイルには次の規則が適用されます

  • READ_ACCESSにはOPEN_EXISTINGが必要です。

  • UPDATE_ACCESSファイルベースのログでは使用できません。 データベース ログでのみ使用できます。

  • WRITE_ACCESSには、CREATE_NEW、CREATE_ALWAYS、OPEN_EXISTING、OPEN_ALWAYSのいずれかが必要です。

例

例については、「 ログ ファイルへのパフォーマンス データの書き込み」を参照してください。

注意

pdh.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして PdhOpenLog を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー pdh.h
Library Pdh.lib
[DLL] Pdh.dll

こちらもご覧ください

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog