Função JetSetColumn

Aplica-se a: Windows | Windows Server

Função JetSetColumn

A função JetSetColumn modifica um único valor de coluna em um registro modificado a ser inserido ou para atualizar o registro atual. Ele pode substituir um valor existente, adicionar um novo valor a uma sequência de valores em uma coluna de vários valores, remover um valor de uma sequência de valores em uma coluna de vários valores ou atualizar todo ou parte de um valor longo, uma coluna do tipo JET_coltypLongText ou JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

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. Como alternativa, um valor columnid de 0 (zero) pode ser fornecido. Quando columnid 0 (zero) é fornecido, todas as colunas marcadas, colunas 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

Buffer de entrada que contém dados a serem usados para o valor da coluna.

cbData

Tamanho em bytes do buffer de entrada.

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_bitSetAppendLV	Essa opção é usada para acrescentar dados a uma coluna do tipo JET_coltypLongText ou JET_coltypLongBinary. O mesmo comportamento pode ser obtido determinando o tamanho do valor longo existente e especificando ibLongValue em psetinfo. No entanto, é mais simples usar esse grbit , pois não é necessário saber o tamanho do valor de coluna existente.
JET_bitSetOverwriteLV	Essa opção é usada para substituir o valor longo existente pelos dados recém-fornecidos. Quando essa opção é usada, é como se o valor longo existente tenha sido definido como 0 (zero) de comprimento antes de definir os novos dados.
JET_bitSetRevertToDefaultValue	Essa opção só é aplicável a colunas marcadas, esparsas ou com valores múltiplos. Isso faz com que a coluna retorne o valor da coluna padrão em operações de coluna de recuperação subsequentes. Todos os valores de coluna existentes são removidos.
JET_bitSetSeparateLV	Essa opção é usada para forçar que um valor longo, colunas do tipo JET_coltypLongText ou JET_coltypLongBinary, sejam armazenados separadamente do restante dos dados de registro. Isso ocorre normalmente quando o tamanho do valor longo impede que ele seja armazenado com os dados de registro restantes. No entanto, essa opção pode ser usada para forçar o valor longo a ser armazenado separadamente. Observe que valores longos de quatro bytes de tamanho menor não podem ser forçados a serem separados. Nesses casos, a opção é ignorada.
JET_bitSetSizeLV	Essa opção é usada para interpretar o buffer de entrada como um número inteiro de bytes a ser definido como o comprimento do valor longo descrito pelo columnid especificado e, se fornecido, o número de sequência em psetinfo-itagSequence>. Se o tamanho fornecido for maior que o valor de coluna existente, a coluna será estendida com 0s. Se o tamanho for menor que o valor de coluna existente, o valor será truncado.
JET_bitSetUniqueMultiValues	Essa opção é usada para impor que todos os valores em uma coluna com vários valores sejam distintos. Essa opção compara os dados da coluna de origem, sem transformações, com outros valores de coluna existentes e um erro é retornado se uma duplicata for encontrada. Se essa opção for fornecida, JET_bitSetAppendLV, JET_bitSetOverwriteLV e JET_bitSetSizeLV também não poderão ser dadas.
JET_bitSetUniqueNormalizedMultiValues	Essa opção é usada para impor que todos os valores em uma coluna com vários valores sejam distintos. Essa opção compara a transformação normalizada de chave dos dados de coluna com outros valores de coluna existentes transformados da mesma forma e um erro é retornado se uma duplicata for encontrada. Se essa opção for fornecida, JET_bitSetAppendLV, JET_bitSetOverwriteLV e JET_bitSetSizeLV também não poderão ser dadas.
JET_bitSetZeroLength	Essa opção é usada para definir um valor como comprimento zero. Normalmente, um valor de coluna é definido como NULL passando um cbMax de 0 (zero). No entanto, para alguns tipos, como JET_coltypText, um valor de coluna pode ter 0 (zero) comprimento em vez de NULL, e essa opção é usada para diferenciar entre NULL e 0 (zero). Nota Em geral, se a coluna for uma coluna de comprimento fixo, esse bit será ignorado e a coluna será definida como NULL. No entanto, se a coluna for uma coluna marcada de comprimento fixo, o comprimento da coluna será definido como 0. Quando a coluna marcada de comprimento fixo é definida como 0 de comprimento, as tentativas de recuperar a coluna com JetRetrieveColumn ou JetRetrieveColumns serão bem-sucedidas, mas o comprimento real retornado no parâmetro cbActual é 0.
JET_bitSetIntrinsicLV	Essa opção é usada para armazenar todo o valor longo no registro.
JET_bitSetCompressed	Essa opção é usada para tentar compactação de dados ao armazenar os dados. Windows 7: JET_bitSetCompressed é introduzido no Windows 7.
JET_bitSetUncompressed	Essa opção é usada para não tentar compactação ao armazenar os dados. Windows 7: JET_bitSetUnCompressed é introduzido no Windows 7.

psetinfo

Ponteiro para parâmetros de entrada opcionais que podem ser definidos para essa função usando a estrutura JET_SETINFO .

Se psetinfo 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 o conjunto de colunas defina o primeiro valor de uma coluna com vários valores e defina dados longos começando no deslocamento 0 (zero).

As seguintes opções podem ser definidas para este parâmetro:

Valor	Significado
ibLongValue	Deslocamento binário em um valor de coluna longo em que os dados de conjunto devem começar.
itagSequence	Número de sequência do valor de coluna de vários valores desejado a ser definido. Se itagSequence for definido como 0 (zero), o valor fornecido deverá ser acrescentado ao final da sequência de valores de vários valores. Se o número de sequência fornecido for maior que o último valor multivalizado existente, novamente o valor fornecido será acrescentado ao final da sequência de valores. Se o número de sequência corresponder a um valor existente, esse valor será substituído pelo valor fornecido.

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 do 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_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 columnid fornecida não existe na tabela.
JET_errColumnNotUpdatable	Foi feita uma tentativa ilegal de atualizar um valor longo durante uma operação de atualização original de exclusão de cópia de inserção.
JET_errColumnTooBig	Os dados de valor de coluna fornecidos no buffer de entrada excedem a limitação de tamanho natural para uma coluna de comprimento fixo ou configurada para texto de comprimento fixo ou colunas binárias. Esse erro também é retornado ao passar mais de 1024 bytes de dados para uma coluna longa e definir o sinalizador JET_bitSetIntrinsicLV.
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_errInvalidBufferSize	O tamanho de dados do valor de coluna fornecido não corresponde ao que é natural para o tipo de dados de comprimento fixo.
JET_errInvalidColumnType	Foi feita uma tentativa ilegal de atualizar uma coluna de incremento automático durante uma operação de inserção ou atualização ou atualizar uma coluna de versão durante uma operação de substituição.
JET_errInvalidgrbit	As opções fornecidas são desconhecidas ou uma combinação ilegal de configurações de bits conhecidas.
JET_errInvalidParameter	O psetinfo-cbStruct> especificado não é um tamanho válido para a estrutura JET_SETINFO .
JET_errMultiValuedDuplicate	A operação definir coluna tentou criar um valor duplicado e especificou JET_bitSetUniqueMultiValues ou JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errNotInTransaction	Foi feita uma tentativa ilegal de atualizar um valor de coluna longa quando a sessão de chamada não estava em uma transação.
JET_errNullInvalid	Foi feita uma tentativa ilegal de definir uma coluna não NULL como NULL.
JET_errColumnIllegalNull	O mesmo que JET_errNullInvalid.
JET_errRecordTooBig	O valor da coluna não pôde ser definido como o valor no buffer de entrada porque teria feito com que o registro excedesse a limitação de tamanho relacionado ao tamanho da página. Colunas do tipo JET_coltypLongText ou JET_coltypLongBinary podem ser armazenadas separadamente dos dados de registro restantes. No entanto, outras colunas devem ser armazenadas com o registro e podem fazer com que a limitação do tamanho do registro seja excedida. Mesmo colunas longas exigem 5 bytes de espaço dentro do registro como uma vinculação e isso também pode levar a JET_errRecordTooBig ser retornado.
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_errUpdateNotPrepared	O cursor não está no processo de inserir um novo registro ou atualizar um registro existente.
JET_errVersionStoreOutOfMemory	Esse erro ocorrerá quando o tamanho configurado do repositório de versão for insuficiente para manter todas as atualizações pendentes.
JET_wrnColumnMaxTruncated	O valor da coluna no buffer de entrada excedeu o comprimento máximo configurado para uma coluna de comprimento variável e foi truncado.

Em caso de êxito, a parte desejada de um valor de coluna para a coluna fornecida é definida com os dados copiados do buffer de entrada. O conjunto de dados poderá ter sido truncado se exceder o comprimento máximo especificado para uma coluna de comprimento variável.

Em caso de falha, o local do cursor fica inalterado e nenhum dado de valor de coluna é atualizado no buffer de cópia.

Comentários

Definir valores longos, valores para colunas JET_coltypLongBinary do tipo JET_coltypLongText ou JET_coltypLongBinary, deve ser feito somente quando a sessão de chamada estiver em uma transação. Se a sessão de chamada não estiver em uma transação, as modificações em valores longos armazenados separadamente poderão ser confirmadas totalmente mesmo quando a operação de atualização for cancelada posteriormente. Se a sessão de chamada estiver em uma transação, os efeitos da atualização poderão ser totalmente revertidos cancelando a atualização e revertendo a transação de sessão.

As atualizações de índice não são executadas como resultado de operações jetSetColumn . Em vez disso, os índices são atualizados somente depois que todas as modificações de coluna são concluídas e JetUpdate é chamado. Isso permite a atualização mais eficiente de índices quando os índices envolvem mais de uma coluna sendo modificada.

Um registro é limitado em tamanho com base no tamanho da página do banco de dados. Quaisquer valores longos no registro maiores que cinco bytes serão armazenados separados do registro caso os dados no registro excedam seu limite como resultado de uma operação JetSetColumn . O erro JET_errRecordTooBig será retornado somente depois que todos os dados de coluna de registro separáveis tiverem sido armazenados separadamente do registro e o registro ainda exceder o limite de tamanho do registro.

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_SETINFO
JetRetrieveColumn
JetSetColumns