Função PdhOpenLogA (pdh.h)

  • Artigo

Abre o arquivo de log especificado para leitura ou gravação.

Sintaxe

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
);

Parâmetros

[in] szLogFileName

Cadeia de caracteres terminada em nulo que especifica o nome do arquivo de log a ser aberto. O nome pode conter um caminho absoluto ou relativo.

Se o parâmetro lpdwLogType for PDH_LOG_TYPE_SQL, especifique o nome do arquivo de log no formulário , SQL:DataSourceName!LogFileName.

[in] dwAccessFlags

Tipo de acesso a ser usado para abrir o arquivo de log. Especifique um dos valores a seguir.

Valor Significado
PDH_LOG_READ_ACCESS
 Abra o arquivo de log para leitura.
PDH_LOG_WRITE_ACCESS
 Abra um novo arquivo de log para gravação.
PDH_LOG_UPDATE_ACCESS
 Abra um arquivo de log existente para gravação.
 

Você pode usar o operador OR inclusivo bit a bit (|) para combinar o tipo de acesso com um ou mais dos sinalizadores de criação a seguir.

Valor Significado
PDH_LOG_CREATE_NEW
 Cria um novo arquivo de log com o nome especificado.
PDH_LOG_CREATE_ALWAYS
 Cria um novo arquivo de log com o nome especificado. Se o arquivo de log já existir, a função removerá o arquivo de log existente antes de criar o novo arquivo.
PDH_LOG_OPEN_EXISTING
 Abre um arquivo de log existente com o nome especificado. Se um arquivo de log com o nome especificado não existir, isso será igual a PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS
 Abre um arquivo de log existente com o nome especificado ou cria um novo arquivo de log com o nome especificado.
PDH_LOG_OPT_CIRCULAR
 Cria um arquivo de log circular com o nome especificado. Quando o arquivo atinge o valor do parâmetro dwMaxSize , os dados são encapsulados no início do arquivo de log. Você só poderá especificar esse sinalizador se o parâmetro lpdwLogType for PDH_LOG_TYPE_BINARY.
PDH_LOG_USER_STRING
 Usado com PDH_LOG_TYPE_TSV para gravar o usuário legenda ou a descrição do arquivo de log indicado pelo parâmetro szUserString de PdhUpdateLog ou PdhOpenLog. A descrição do arquivo de log ou legenda do usuário é gravada como a última coluna na primeira linha do log de texto.

[in] lpdwLogType

Tipo de arquivo de log a ser aberto. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
PDH_LOG_TYPE_UNDEFINED
 Formato de arquivo de log indefinido. Se especificado, o PDH determina o tipo de arquivo de log. Você não poderá especificar esse valor se o parâmetro dwAccessFlags for PDH_LOG_WRITE_ACCESS.
PDH_LOG_TYPE_CSV
 Arquivo de texto que contém cabeçalhos de coluna na primeira linha e registros de dados individuais em cada linha subsequente. Os campos de cada registro de dados são delimitados por vírgulas.

A primeira linha também contém informações sobre o formato do arquivo, a versão PDH usada para criar o arquivo de log e os nomes e caminhos de cada um dos contadores.
PDH_LOG_TYPE_SQL
 A fonte de dados do arquivo de log é um banco de dados SQL.
PDH_LOG_TYPE_TSV
 Arquivo de texto que contém cabeçalhos de coluna na primeira linha e registros de dados individuais em cada linha subsequente. Os campos de cada registro de dados são delimitados por tabulação.

A primeira linha também contém informações sobre o formato do arquivo, a versão PDH usada para criar o arquivo de log e os nomes e caminhos de cada um dos contadores.
PDH_LOG_TYPE_BINARY
 Formato de arquivo de log binário.

[in] hQuery

Especifique um identificador de consulta se você estiver gravando dados de consulta em um arquivo de log. A função PdhOpenQuery retorna esse identificador.

Esse parâmetro será ignorado e deverá ser NULL se você estiver lendo do arquivo de log.

[in] dwMaxSize

Tamanho máximo do arquivo de log, em bytes. Especifique o tamanho máximo se quiser limitar o tamanho do arquivo ou se dwAccessFlagsespecificar PDH_LOG_OPT_CIRCULAR; caso contrário, defina como 0.

Para arquivos de log circulares, você deve especificar um valor grande o suficiente para conter pelo menos um exemplo. O tamanho da amostra depende da coleta de dados. No entanto, especificar um valor de pelo menos um megabyte abrangerá a maioria dos exemplos.

[in] szUserCaption

Cadeia de caracteres terminada em nulo que especifica o legenda definido pelo usuário do arquivo de log. Um arquivo de log legenda geralmente descreve o conteúdo do arquivo de log. Quando um arquivo de log existente é aberto, o valor desse parâmetro é ignorado.

[out] phLog

Manipule para o arquivo de log aberto.

Retornar valor

Se a função for bem-sucedida, ela retornará ERROR_SUCCESS.

Se a função falhar, o valor retornado será um código de erro do sistema ou um código de erro PDH.

Comentários

Para usar essa função para gravar dados de desempenho em um arquivo de log, você deve abrir uma consulta usando PdhOpenQuery e adicionar os contadores desejados a ele, antes de chamar essa função.

Sistemas operacionais mais recentes podem ler arquivos de log que foram gerados em sistemas operacionais mais antigos; no entanto, os arquivos de log criados no Windows Vista e em sistemas operacionais posteriores não podem ser lidos em sistemas operacionais anteriores.

As regras a seguir se aplicam aos arquivos de log

  • READ_ACCESS requer OPEN_EXISTING.

  • UPDATE_ACCESS não pode ser usado com logs baseados em arquivo. Ele só pode ser usado com logs de banco de dados.

  • WRITE_ACCESS requer uma das OPEN_ALWAYS CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING e OPEN_ALWAYS.

Exemplos

Para obter um exemplo, consulte Gravando dados de desempenho em um arquivo de log.

Observação

O cabeçalho pdh.h define PdhOpenLog como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho pdh.h
Biblioteca Pdh.lib
DLL Pdh.dll

Confira também

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog