Compartilhar via

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 nulaterminada 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 de 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 para o 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 a legenda do usuário ou a descrição do arquivo de log indicada 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 ser 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. Não é possível 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írgula.

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 é ignorado e deve 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 você quiser limitar o tamanho do arquivo ou se dwAccessFlags especifica 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 dos dados coletados. No entanto, especificar um valor de pelo menos um megabyte abrangerá a maioria dos exemplos.

[in] szUserCaption

cadeia de caracteres terminada pornulo que especifica a legenda definida pelo usuário do arquivo de log. Uma legenda de arquivo de log 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.

Valor de retorno

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 .

Observações

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.

Nota

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. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho pdh.h
biblioteca Pdh.lib
de DLL Pdh.dll

Consulte também

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog