Função JetRetrieveColumn

Aplica-se a: Windows | Servidor Windows

Função JetRetrieveColumn

A função JetRetrieveColumn recupera um único valor de coluna do registro atual. O registro é aquele registro 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.

Pode ser dado um valor columnid de 0 (zero) que não se refere a nenhuma coluna individual. Quando columnid 0 (zero) é fornecido, todas as colunas marcadas, esparsas e com vários valores 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 deve ser especificada se o índice atual for o índice clusterizado, já que 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 deve 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 com vários valores serão ignorados automaticamente.

JET_bitRetrieveIgnoreDefault

Essa opção afeta apenas colunas de vários valores 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 é somente para uso interno e não se destina a ser usado em seu aplicativo.

JET_bitRetrieveLongValueRefCount

Esse sinalizador é somente 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 com 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 vários valores 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 vários valores usando columnid de passagem de 0 (zero).

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 do mecanismo 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 colunas com vários valores inválidos foi passado em pretinfo-itagSequence>. Os valores válidos para os números de sequência de valor de coluna de vários valores 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 toda a atividade na instância associada à sessão foi interrompida como resultado de uma chamada para JetStopService.

JET_errColumnNotFound

A coluna descrita pela columnid fornecida não existe na tabela.

JET_errIndexTuplesCannotRetrieveFromIndex

As 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 por 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 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_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 ocorrerá 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 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.

JET_wrnColumnNull

O valor da coluna recuperado é NULL.

Com êxito, o valor da 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 fica inalterado e nenhum dado é copiado no 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 da 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 é de vários valores, 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 com 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, uma vez que esses valores seriam ignorados. Se um aplicativo desejar recuperar todos os valores de coluna de vários valores, incluindo aqueles definidos explicitamente como NULL, jetRetrieveColumns deve ser usado em vez de JetRetrieveColumn. Observe que essa função não retorna o número de valores para uma função de vários valores quando um valor de itagSequence de 0 (zero) é fornecido. Somente JetRetrieveColumns retornará o número de valores de um valor de coluna quando um valor de itagSequence de 0 (zero) for passado.

Se essa função for chamada no nível de transação 0 (zero), por exemplo, a sessão de chamada não estará em uma transação, então uma transação será 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 preenchimento automático é alocado quando a operação de inserção começa e pode ser recuperada do buffer de cópia a qualquer momento até que a atualização seja concluída.

Ao recuperar todas as colunas marcadas, com vários valores e esparsas, definindo columnid como 0 (zero), as colunas são recuperadas na ordem columnid do columnid mais baixo para o columnid mais alto. 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 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_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns