Função JetRetrieveColumns

Aplica-se a: Windows | servidor Windows

Função JetRetrieveColumns

A função JetRetrieveColumns recupera vários valores de coluna do registro atual em uma única operação. Uma matriz de estruturas JET_RETRIEVECOLUMN é usada para descrever o conjunto de valores de coluna a serem recuperados e para descrever buffers de saída para cada valor de coluna a ser recuperado.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

Parâmetros

sesid

A sessão a ser usada para esta chamada.

Tableid

O cursor a ser usado para essa chamada.

pretrievecolumn

Um ponteiro para uma matriz de uma ou mais estruturas JET_RETRIEVECOLUMN . Cada estrutura inclui descrições de qual valor de coluna recuperar e onde armazenar dados retornados.

cretrievecolumn

O número de estruturas JET_RETRIEVECOLUMN na matriz fornecida por pretrievecolumn.

Valor de retorno

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 do ESE, consulte Erros extensíveis Armazenamento mecanismo e parâmetros de tratamento de erros.

Código de retorno	Descrição
JET_errSuccess	A operação foi concluída com sucesso.
JET_errBadItagSequence	Um valor de número de sequência de colunas com valores múltiplos inválidos foi passado em pretinfo-itagSequence>. Os valores válidos para os números de sequência de valores de coluna com valores de coluna com valores múltiplos são 1 ou maior. Um valor de 0 (zero) é válido para essa função, mas é inválido para JetRetrieveColumn.
JET_errBadColumnId	A ID da coluna fornecida está fora dos limites legais de uma ID de coluna.
JET_errClientRequestToStopJetService	Não é possível concluir a operação porque toda a atividade na instância associada à sessão cessou como resultado de uma chamada ao JetStopService.
JET_errColumnNotFound	A coluna descrita pela columnid fornecida não existe na tabela.
JET_errIndexTuplesCannotRetrieveFromIndex	Colunas indexadas como subcadeias de caracteres não podem ser recuperadas do índice, pois apenas uma pequena parte da coluna normalmente está presente em cada entrada de índice.
JET_errInvalidBufferSize	Em alguns casos, o buffer fornecido para a coluna de recuperação deve ser dimensionado suficientemente para retornar qualquer quantidade do valor da coluna. Por exemplo, as colunas atualizáveis de escrow são ajustadas para serem consistentes para o contexto transacional da sessão de chamada e esse ajuste requer o buffer fornecido pelo chamador. Se o espaço em buffer insuficiente for fornecido, JET_errInvalidBufferSize será retornado e nenhum dado de coluna será retornado.
JET_errInvalidgrbit	As opções fornecidas são desconhecidas ou uma combinação ilegal de configurações de bits conhecidas.
JET_errInvalidParameter	Um ou mais dos parâmetros dados estão incorretos. Isso pode acontecer se o retinfo.cbStruct for menor que o tamanho da JET_RETINFO.
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 por Windows XP e versões posteriores.
JET_errNoCurrentRecord	O cursor não está posicionado em um registro. Isso pode ocorrer por vários motivos diferentes. Por exemplo, isso ocorrerá se o cursor estiver posicionado 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_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 por 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.
JET_wrnBufferTruncated	Não foi possível recuperar todo o valor da coluna porque o buffer fornecido é menor que o tamanho da coluna.

Com êxito, os dados das colunas e o tamanho da coluna são retornados em buffers fornecidos descritos na matriz de estruturas JET_RETRIEVECOLUMN . Se uma itagSequence foi definida como 0 (zero) para indicar que o número de instâncias de um campo com valores múltiplos foi desejado em vez de dados de coluna, o número de instâncias de uma coluna com valores múltiplos será retornado no próprio campo itagSequence . Cada estrutura JET_RETRIEVECOLUMN tem um campo de erro que contém avisos para a coluna recuperada. Se a coluna tiver sido valor NULL , o código de erro será definido como JET_wrnColumnNull.

Em caso de falha, o local do cursor é deixado inalterado e nenhum dado é copiado para o buffer fornecido.

Comentários

JetRetrieveColumns dá suporte a um recurso que JetRetrieveColumn não dá. Essa é a capacidade de recuperar o número de instâncias de uma coluna com valores múltiplos. A finalidade desse recurso é permitir que um aplicativo recupere todos os valores de uma coluna. Isso pode ser feito determinando primeiro o número de valores que uma coluna tem. Em seguida, seus comprimentos podem ser determinados chamando JetRetrieveColumns novamente com um JET_RETRIEVECOLUMN estrutura alocada para cada valor para determinar o comprimento dos dados de coluna. Isso pode ser feito passando ponteiros NULLpvData com cbMax de 0 (zero) e recuperando o comprimento da coluna no cbActual. A terceira e a última chamada podem ser feitas com memória alocada para os dados de valor da coluna.

Se qualquer coluna recuperada for truncada devido a um buffer de comprimento insuficiente, a API retornará JET_wrnBufferTruncated. No entanto, outros erros JET_wrnColumnNull são retornados somente no campo de erro no JET_RETRIEVECOLUMN. O motivo para isso é que os aplicativos geralmente querem garantir que todos os dados foram recuperados e retornar esse erro do JetRetrieveColumns facilita esse entendimento.

Requisitos

Requisito	Valor
Cliente	Requer Windows Vista, Windows XP ou Windows 2000 Professional.
Servidor	Requer Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.

Consulte Também

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns