Função JetRetrieveColumn

Artigo
06/12/2023

Aplica-se a: Windows | Windows Server

Função JetRetrieveColumn

A função JetRetrieveColumn recupera um único valor de coluna do registro atual. O registro é aquele associado à entrada de índice na posição atual do cursor. Como alternativa, essa função pode recuperar uma coluna de um registro que está sendo criado no buffer de cópia do cursor. Essa função também pode recuperar dados de coluna de uma entrada de índice que faz referência ao registro atual. Além de recuperar o valor real da coluna, JetRetrieveColumn também pode ser usado para recuperar o tamanho de uma coluna, antes de recuperar os próprios dados de coluna para que os buffers de aplicativo possam ser dimensionados adequadamente.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

Columnid

O JET_COLUMNID da coluna a ser recuperada.

Um valor columnid de 0 (zero) pode ser fornecido, o que não se refere a nenhuma coluna individual. Quando columnid 0 (zero) é fornecido, todas as colunas marcadas, esparsas e com valores múltiplos são tratadas como uma única coluna. Isso facilita a recuperação de todas as colunas esparsas presentes em um registro.

pvData

O buffer de saída que recebe o valor da coluna.

cbData

O tamanho máximo, em bytes, do buffer de saída.

pcbActual

Recebe o tamanho real, em bytes, do valor da coluna.

Se esse parâmetro for NULL, o tamanho real do valor da coluna não será retornado.

grbit

Um grupo de bits que contém as opções a serem usadas para essa chamada, que incluem zero ou mais dos seguintes:

Valor	Significado
JET_bitRetrieveCopy	Esse sinalizador faz com que a coluna de recuperação recupere o valor modificado em vez do valor original. Se o valor não tiver sido modificado, o valor original será recuperado. Dessa forma, um valor que ainda não foi inserido ou atualizado pode ser recuperado durante a operação de inserção ou atualização de um registro.
JET_bitRetrieveFromIndex	Essa opção é usada para recuperar valores de coluna do índice, se possível, sem acessar o registro. Dessa forma, o carregamento desnecessário de registros pode ser evitado quando os dados necessários estão disponíveis nas próprias entradas de índice. Nos casos em que o valor da coluna original não pode ser recuperado do índice, devido a transformações irreversíveis ou truncamento de dados, o registro será acessado e os dados recuperados normalmente. Essa é uma opção de desempenho e só deve ser especificada quando é provável que o valor da coluna possa ser recuperado do índice. Essa opção não deverá ser especificada se o índice atual for o índice clusterizado, pois as entradas de índice para o índice clusterizado ou primário são os próprios registros. Esse bit não poderá ser definido se JET_bitRetrieveFromPrimaryBookmark também estiver definido.
JET_bitRetrieveFromPrimaryBookmark	Essa opção é usada para recuperar valores de coluna do indicador de índice e pode ser diferente do valor do índice quando uma coluna aparece no índice primário e no índice atual. Essa opção não deverá ser especificada se o índice atual for o índice clusterizado ou primário. Esse bit não poderá ser definido se JET_bitRetrieveFromIndex também estiver definido.
JET_bitRetrieveTag	Essa opção é usada para recuperar o número de sequência de um valor de coluna de vários valores em pretinfo-itagSequence>. O campo itagSequence normalmente é uma entrada para recuperar valores de coluna de vários valores de um registro. No entanto, ao recuperar valores de um índice, também é possível associar a entrada de índice a um número de sequência específico e recuperar esse número de sequência também. Recuperar o número de sequência pode ser uma operação dispendiosa e só deve ser feita se necessário.
JET_bitRetrieveNull	Essa opção é usada para recuperar valores NULL de coluna de vários valores. Se essa opção não for especificada, os valores NULL de coluna de vários valores serão ignorados automaticamente.
JET_bitRetrieveIgnoreDefault	Essa opção afeta apenas colunas com valores múltiplos e faz com que um valor NULL seja retornado quando o número de sequência solicitado for 1 e não houver valores definidos para a coluna no registro.
JET_bitRetrieveLongId	Esse sinalizador é apenas para uso interno e não se destina a ser usado em seu aplicativo.
JET_bitRetrieveLongValueRefCount	Esse sinalizador é apenas para uso interno e não se destina a ser usado em seu aplicativo.
JET_bitRetrieveTuple	Esse sinalizador permitirá a recuperação de um segmento de tupla do índice. Esse bit deve ser especificado com JET_bitRetrieveFromIndex.

pretinfo

Se pretinfo for dado como NULL , a função se comportará como se fosse uma itagSequence de 1 e um ibLongValue de 0 (zero). Isso faz com que a recuperação de coluna recupere o primeiro valor de uma coluna de vários valores e recupere dados longos no deslocamento 0 (zero).

Esse parâmetro é usado para fornecer um ou mais dos seguintes:

Valor	Significado
ibLongValue	Fornece um deslocamento binário em um valor de coluna longa ao recuperar uma parte de um valor de coluna.
itagSequence	Fornece o número de sequência do valor de coluna de valores múltiplos desejado. Observe que esse campo só será definido se o JET_bitRetrieveTag for especificado. Caso contrário, ele não será modificado.
columnidNextTagged	Retorna a ID da coluna do valor de coluna retornado ao recuperar todas as colunas marcadas, esparsas e com valores múltiplos usando columnid de passagem de 0 (zero).

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.
JET_errBadItagSequence	Um valor de número de sequência de coluna de valores múltiplos inválido foi passado em pretinfo-itagSequence>. Os valores válidos para os números de sequência de valores de coluna com valores múltiplos são 1 ou maior. Um valor de 0 (zero) é inválido para essa função.
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 pelo columnid fornecido 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_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. Esse erro só será retornado pelo Windows XP e versões posteriores.
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 caução 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_errInvalidParameter	Um ou mais dos parâmetros dados estão incorretos. Isso pode acontecer se o retinfo.cbStruct for menor que o tamanho de JET_RETINFO.
JET_errInvalidgrbit	As opções fornecidas são desconhecidas ou uma combinação ilegal de configurações de bits conhecidas.
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_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.
JET_wrnBufferTruncated	Não foi possível recuperar o valor inteiro da coluna porque o buffer fornecido é menor que o tamanho da coluna.
JET_wrnColumnNull	O valor da coluna recuperado é NULL.

Em caso de êxito, o valor da coluna para a coluna fornecida é copiado para o buffer fornecido. Menos do que todo o valor da coluna é copiado com o aviso JET_wrnBufferTruncated é retornado. Se o pcbActual tiver sido fornecido, o tamanho real do valor da coluna será retornado. Observe que os valores NULL têm 0 (zero) de comprimento e, portanto, definirão o tamanho retornado como 0 (zero). Se a coluna recuperada for uma coluna de vários valores e o pretinfo tiver sido fornecido e JET_bitReturnTag foi definido como uma opção, o número de sequência do valor da coluna será retornado em pretinfo-itagSequence>.

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

Comentários

Essa chamada é usada apenas uma vez para recuperar dados de tamanho fixo ou conhecido para colunas não com valores múltiplos. No entanto, quando os dados de coluna são de tamanho desconhecido, essa chamada normalmente é usada duas vezes. Ele é chamado primeiro para determinar o tamanho dos dados para que ele possa alocar o espaço de armazenamento necessário. Em seguida, a mesma chamada é feita novamente para recuperar os dados da coluna. Quando o número real de valores é desconhecido, porque uma coluna tem valores múltiplos, a chamada normalmente é usada três vezes. Primeiro para obter o número de valores e, em seguida, mais duas vezes para alocar armazenamento e recuperar os dados reais.

A recuperação de todos os valores de uma coluna de vários valores pode ser feita chamando repetidamente essa função com um valor pretinfo-itagSequence> começando em 1 e aumentando em cada chamada subsequente. O último valor de coluna é conhecido por ser recuperado quando um JET_wrnColumnNull é retornado da função. Observe que esse método não poderá ser feito se a coluna de vários valores tiver valores NULL explícitos definidos em sua sequência de valores, pois esses valores seriam ignorados. Se um aplicativo quiser recuperar todos os valores de coluna de valores múltiplos, incluindo aqueles explicitamente definidos como NULL, JetRetrieveColumns deverá ser usado em vez de JetRetrieveColumn. Observe que essa função não retorna o número de valores para uma função com valores múltiplos quando um valor itagSequence de 0 (zero) é fornecido. Somente JetRetrieveColumns retornará o número de valores de um valor de coluna quando um valor itagSequence de 0 (zero) for passado.

Se essa função for chamada no nível da transação 0 (zero), por exemplo, a sessão de chamada não está em si em uma transação, então uma transação é aberta e fechada dentro da função . A finalidade disso é retornar resultados consistentes no caso de um valor longo abranger páginas de banco de dados. Observe que a transação é liberada entre chamadas de função e uma série de chamadas para essa função quando a sessão não está em uma transação pode retornar dados atualizados após a primeira chamada para essa função.

O valor da coluna padrão será recuperado quando a coluna não tiver sido definida explicitamente como outro valor, a menos que a opção JET_bitRetrieveIgnoreDefault esteja definida.

Recuperar o valor da coluna de preenchimento automático do buffer de cópia antes da inserção é um meio comum de identificar um registro exclusivamente para vinculação ao inserir dados normalizados em várias tabelas. O valor de autoincremento é alocado quando a operação de inserção começa e pode ser recuperado do buffer de cópia a qualquer momento até que a atualização seja concluída.

Ao recuperar todas as colunas marcadas, com valores múltiplos e esparsas, definindo columnid como 0 (zero), as colunas são recuperadas em ordem columnid da columnid mais baixa para a columnid mais alta. A mesma ordem de valores de coluna é retornada sempre que os valores de coluna são recuperados. A ordem é determinística.

Requisitos

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

Consulte Também

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns

Função JetRetrieveColumn