Compartilhar via

Função JetEnumerateColumns

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetEnumerateColumns

A função JetEnumerateColumns recupera com eficiência um conjunto de colunas e seus valores do registro atual de um cursor ou do buffer de cópia desse cursor. As colunas e valores recuperados podem ser restritos por uma lista de IDs de coluna, números de itagSequence e outras características. Essa API de recuperação de coluna é exclusiva, pois retorna informações na memória alocada dinamicamente obtidas usando um retorno de chamada compatível com realloc fornecido pelo usuário. Essa nova flexibilidade permite a recuperação eficiente de dados de coluna com características específicas (como tamanho e multiplicidade) desconhecidas pelo chamador. Isso elimina a necessidade de usar os modos de descoberta de JetRetrieveColumn para determinar essas características a fim de configurar uma chamada final para JetRetrieveColumn que recuperará com êxito os dados desejados.

Windows XP: JetEnumerateColumns é introduzido no Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

cEnumColumnId

Uma matriz de IDs de coluna, cada uma com uma matriz opcional de números itagSequence para enumerar.

Se cEnumColumnId for 0 (zero), rgEnumColumnId será ignorado e todos os valores de coluna serão enumerados e retornados ao chamador. Se um elemento da matriz de ID de coluna se referir a uma ID de coluna de 0 (zero), a enumeração dessa coluna será ignorada e um slot correspondente na saída será gerado com uma coluna status de JET_wrnColumnSkipped.

Se ctagSequence for 0 (zero) para um determinado elemento da matriz de ID de coluna, rgtagSequence será ignorado e todos os valores de coluna para essa ID de coluna serão enumerados e retornados ao chamador. Se um elemento de uma matriz de número itagSequence se referir a um número itagSequence de 0 (zero), a enumeração desse número itagSequence será ignorada e um slot correspondente na saída será gerado com um valor de coluna status de JET_wrnColumnSkipped.

rgEnumColumnId

Consulte cEnumColumnId.

pcEnumColumn

Retorna a matriz enumerada de colunas e seus valores na memória alocados por meio do retorno de chamada compatível com itagSequence fornecido.

Se uma matriz de IDs de coluna for solicitada na entrada, a ordem e o tamanho da matriz de saída refletirão a ordem e o tamanho da matriz de entrada. Da mesma forma, se uma matriz de números itagSequence for solicitada para uma ID de coluna específica na entrada, a ordem e o tamanho da matriz de saída de valores de coluna para essa coluna refletirão a ordem e o tamanho da matriz de entrada.

Os parâmetros de saída são definidos como 0 (zero) e NULL em qualquer erro, exceto para JET_errBadColumnId e JET_errColumnNotFound. Quando esses erros são retornados, os dados de saída são válidos e concluídos para todas, exceto as IDs de coluna afetadas. O código status para cada uma das IDs de coluna afetadas é definido como um desses erros para que o chamador possa determinar quais IDs de coluna foram ruins e potencialmente tomar medidas corretivas.

prgEnumColumn

Consulte pcEnumColumn.

pfnRealloc

Identifica um retorno de chamada compatível com realloc e um ponteiro de contexto opcional usado para alocar memória para a matriz de saída de colunas e seus valores.

pvReallocContext

Consulte pfnRealloc.

cbDataMost

Define um limite na quantidade de dados a serem retornados de um texto longo ou coluna binária longa.

Esse parâmetro pode ser usado para impedir a enumeração de um valor de coluna extremamente grande. Normalmente, essa enumeração pode falhar na chamada à API com JET_errOutOfMemory. Se um valor de coluna grande for truncado dessa maneira, o status do valor da coluna será JET_wrnColumnTruncated.

grbit

Um grupo de bits que especifica zero ou mais das opções a seguir.

Valor

Significado

JET_bitEnumerateCompressOutput

Ao enumerar valores de coluna, todas as colunas para as quais estamos recuperando todos os valores e que têm apenas um valor de coluna não NULL podem ser retornadas em um formato compactado. O status dessas colunas será definido como JET_wrnColumnSingleValue e o tamanho do valor da coluna e a memória que contém o valor da coluna serão retornados diretamente na estrutura JET_ENUMCOLUMN. Não é garantido que todas as colunas qualificadas sejam compactadas dessa maneira. Confira JET_ENUMCOLUMN para obter mais informações.

JET_bitEnumerateCopy

Essa opção indica que os valores de coluna modificados do registro devem ser enumerados em vez dos valores de coluna originais. Se um valor de coluna não tiver sido modificado, o valor da coluna original será enumerado. Dessa forma, um valor de coluna que ainda não foi inserido ou atualizado pode ser enumerado ao inserir ou atualizar um registro.

Essa opção é idêntica a JET_bitRetrieveCopy quando usada com JetRetrieveColumn ou JetRetrieveColumns.

JET_bitEnumerateIgnoreDefault

Se uma determinada coluna não estiver presente no registro, nenhum valor de coluna será retornado. Normalmente, o valor padrão da coluna, se houver, seria retornado nesse caso. É garantido que, se a coluna for definida como um valor diferente do valor padrão, esse valor diferente será retornado (ou seja, se uma coluna com um valor padrão for definida explicitamente como NULL , um NULL será retornado como o valor dessa coluna). Observe que, mesmo que essa opção seja solicitada, ainda é possível ver um valor de coluna que seja igual ao valor padrão. Nenhum esforço é feito para remover valores de coluna que correspondam aos valores padrão.

É importante observar que essa opção afeta a saída de JetEnumerateColumns quando usada com JET_bitEnumeratePresenceOnly ou JET_bitEnumerateTaggedOnly.

JET_bitEnumerateIgnoreUserDefinedDefault

Se uma determinada coluna não estiver presente no registro e tiver um valor padrão definido pelo usuário, nenhum valor de coluna será retornado. Essa opção impedirá que o retorno de chamada que calcula o valor padrão definido pelo usuário para a coluna seja chamado ao enumerar os valores dessa coluna.

Windows Server 2003 e versões anteriores: Para o Windows Server 2003 e versões anteriores, a operação falhará com JET_errCallbackFailed.

Windows Server 2003 SP1: Esse valor possível só está disponível para sistemas operacionais Windows Server 2003 SP1 e posteriores. Se esse valor possível for especificado e a tabela contiver uma coluna que tenha um valor padrão definido pelo usuário, a operação falhará com JET_errCallbackFailed.

JET_bitEnumeratePresenceOnly

Se existir um valor não NULL para o valor de coluna ou coluna solicitado, os dados associados não serão retornados. Em vez disso, o status associado para esse valor de coluna ou coluna será definido como JET_wrnColumnPresent. Se o valor da coluna ou coluna for NULL , JET_wrnColumnNull será retornado como de costume.

JET_bitEnumerateTaggedOnly

Ao enumerar todos os valores de coluna no registro (por exemplo, ou seja, quando cEnumColumnId é zero), somente valores de coluna marcados serão retornados. Essa opção não é permitida ao enumerar uma matriz específica de IDs de coluna.

JET_bitEnumerateInRecordOnly

Windows 7: JET_bitEnumerateInRecordOnly é introduzido no Windows 7.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros de ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno

Descrição

JET_errSuccess

A operação foi concluída com sucesso.

JET_errBadColumnId

A ID da coluna fornecida está fora dos limites legais de uma ID de coluna. Esse erro será retornado por JetEnumerateColumns se IDs de coluna específicas forem solicitadas, uma dessas IDs de coluna for inválida e a primeira ID de coluna inválida falhar com esse erro para sua coluna status código.

JET_errClientRequestToStopJetService

Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.

JET_errColumnNotFound

A coluna descrita pela ID de coluna fornecida não existe na tabela. Esse erro será retornado por JetEnumerateColumns se IDs de coluna específicas forem solicitadas, uma dessas IDs de coluna for inválida e a primeira ID de coluna inválida falhar com esse erro para sua coluna status código.

JET_errInstanceUnavailable

Não é possível concluir a operação porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados.

Windows XP: Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errInvalidgrbit

Uma das opções solicitadas era inválida ou não implementada. Esse erro será retornado por JetEnumerateColumns quando:

  • JET_bitEnumerateLocal é especificado.

  • Um grbit ilegal é especificado.

JET_errInvalidParameter

Um dos parâmetros fornecidos continha um valor inesperado ou continha um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Esse erro será retornado por JetEnumerateColumns quando:

  • pcEnumColumn é NULL.

  • prgEnumColumn é NULL.

  • pfnRealloc é NULL.

JET_errNoCurrentRecord

O cursor não está posicionado em um registro. Isso pode ocorrer por vários motivos diferentes. Por exemplo, isso acontecerá se o cursor estiver posicionado no momento após o último registro no índice atual.

JET_errNotInitialized

Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.

JET_errRecordDeleted

O cursor é posicionado em um registro que foi excluído. Isso pode ocorrer por vários motivos diferentes. O motivo mais comum é que a sessão não está em uma transação, o cursor foi posicionado em um registro, esse registro foi excluído e, em seguida, o cursor tentou referenciar esse registro.

JET_errRestoreInProgress

Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada à sessão.

JET_errSessionSharingViolation

A mesma sessão não pode ser usada para mais de um thread ao mesmo tempo.

Windows XP: Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errTermInProgress

Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.

Com êxito, os dados solicitados serão retornados nos buffers de saída. É responsabilidade do chamador liberar qualquer memória alocada por esse retorno de chamada e retornada nos buffers de saída. Essa memória deve ser liberada por meio do retorno de chamada compatível com realloc fornecido. Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, nenhum dos dados solicitados será retornado. Qualquer memória alocada durante a chamada será liberada automaticamente usando o retorno de chamada compatível com realloc fornecido. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

Se você estiver enumerando todos os valores de coluna no registro e não tiver especificado JET_bitEnumerateIgnoreDefaults, não poderá presumir que nunca verá um valor de coluna ou coluna com um código status de JET_wrnColumnNull. Você poderá ver esse código status se uma coluna tiver um valor padrão e tiver sido definida explicitamente como NULL ou se a coluna for uma coluna não esparsa (por exemplo, uma coluna fixa ou variável).

O parâmetro cbDataMost não se aplica a todos os valores de coluna. Esse parâmetro só truncará texto longo e valores de coluna binária longa que são tão grandes que foram armazenados separadamente do registro.

Se JetEnumerateColumns retornar dados em seus parâmetros de saída, o chamador será responsável por liberar a memória na matriz, bem como qualquer memória referida por ponteiros inseridos nessa matriz.

Requisitos

Requisito Valor

Cliente

Requer o Windows Vista ou o Windows XP.

Servidor

Requer o Windows Server 2008 ou o Windows Server 2003.

Cabeçalho

Declarado em Esent.h.

Biblioteca

Use ESENT.lib.

DLL

Requer ESENT.dll.

Consulte Também

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns