Partilhar via

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 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

Sesídeo

A sessão a ser usada para esta chamada.

TableID

O cursor a ser usado para esta chamada.

columnid

A JET_COLUMNID da coluna a ser recuperada. Alternativamente, um valor columnid de 0 (zero) pode ser dado. Quando columnid 0 (zero) é dado, todas as colunas marcadas, colunas esparsas e de 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

Buffer de entrada contendo dados a serem usados para o valor da coluna.

cbDados

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 do seguinte:

Valor

Significado

JET_bitSetAppendLV

Esta opção é usada para acrescentar dados a uma coluna do tipo JET_coltypLongText ou JET_coltypLongBinary. O mesmo comportamento pode ser alcançado determinando o tamanho do valor long existente e especificando ibLongValue em psetinfo. No entanto, é mais simples usar este grbit , uma vez que não é necessário saber o tamanho do valor da coluna existente.

JET_bitSetOverwriteLV

Esta 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 tivesse sido definido como 0 (zero) de comprimento antes de definir os novos dados.

JET_bitSetRevertToDefaultValue

Esta opção só é aplicável a colunas marcadas, esparsas ou com vários valores. Isso faz com que a coluna retorne o valor de coluna padrão em operações de coluna de recuperação subsequentes. Todos os valores de coluna existentes são removidos.

JET_bitSetSeparateLV

Esta opção é usada para forçar um valor longo, colunas do tipo JET_coltypLongText ou JET_coltypLongBinary, a ser armazenado separadamente do restante dos dados do 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

Esta opção é usada para interpretar o buffer de entrada como um número inteiro de bytes para definir como o comprimento do valor longo descrito pelo columnid dado e, se fornecido, o número de sequência em psetinfo-itagSequence>. Se o tamanho fornecido for maior do que o valor da coluna existente, a coluna será estendida com 0s. Se o tamanho for menor do que o valor da coluna existente, o valor será truncado.

JET_bitSetUniqueMultiValues

Esta opção é usada para impor que todos os valores em uma coluna de valores múltiplos sejam distintos. Esta opção compara os dados da coluna de origem, sem quaisquer transformações, com outros valores de coluna existentes e um erro é retornado se for encontrada uma duplicata. Se esta opção for dada, então JET_bitSetAppendLV, JET_bitSetOverwriteLV e JET_bitSetSizeLV também não podem ser dadas.

JET_bitSetUniqueNormalizedMultiValues

Esta opção é usada para impor que todos os valores em uma coluna de valores múltiplos sejam distintos. Esta opção compara a transformação normalizada de chave de dados de coluna com outros valores de coluna existentes transformados de forma semelhante e um erro é retornado se uma duplicata for encontrada. Se esta opção for dada, então JET_bitSetAppendLV, JET_bitSetOverwriteLV e JET_bitSetSizeLV também não podem ser dadas.

JET_bitSetZeroLength

Esta 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 ser 0 (zero) comprimento em vez de NULL, e esta opção é usada para diferenciar entre NULL e 0 (zero) comprimento.

Observação 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 comprimento, as tentativas de recuperar a coluna com JetRetrieveColumn ou JetRetrieveColumns terão êxito, 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

Esta opção é usada para tentar a compactação de dados ao armazenar os dados.

Janelas 7: JET_bitSetCompressed é introduzido no Windows 7.

JET_bitSetUncompressed

Esta opção é usada para não tentar compactação ao armazenar os dados.

Janelas 7: JET_bitSetUnCompressed é introduzido no Windows 7.

psetinfo

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

Se psetinfo é dado como NULL , então a função se comporta como se um itagSequence de 1 e um ibLongValue de 0 (zero) fossem dados. Isso faz com que o conjunto de colunas defina o primeiro valor de uma coluna de 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 longa onde os dados definidos devem começar.

itagSequence

Número de sequência do valor desejado da coluna de valores múltiplos a ser definido. Se itagSequence for definido como 0 (zero), o valor fornecido deve ser anexado ao final da sequência de valores múltiplos. Se o número de sequência fornecido for maior do que o último valor multivalorado existente, então novamente o valor dado é acrescentado ao final da sequência de valores. Se o número de sequência corresponder a um valor existente, esse valor é substituído pelo valor dado.

Valor de retorno

Esta 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 ESE, consulte Erros do mecanismo de armazenamento extensível e Parâmetros de tratamento de erros.

Código de retorno

Descrição

JET_errSuccess

A operação foi concluída com êxito.

JET_errBadColumnId

O ID da coluna fornecido está fora dos limites legais de um 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 para JetStopService.

JET_errColumnNotFound

A coluna descrita pelo columnid dado 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. Este 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: Este erro só será devolvido pelo Windows XP e versões posteriores.

JET_errInvalidBufferSize

O tamanho dos dados do valor da coluna 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 de 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 dado psetinfo-cbStruct> não é um tamanho válido para a estrutura JET_SETINFO .

JET_errMultiValuedDuplicate

A operação set column 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 para 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 isso teria feito com que o registro excedesse sua limitação de tamanho relacionada ao tamanho da página. As colunas do tipo JET_coltypLongText ou JET_coltypLongBinary podem ser armazenadas separadamente dos restantes dados de registo. No entanto, outras colunas devem ser armazenadas com o registro e podem fazer com que a limitação de tamanho do registro seja excedida. Mesmo colunas longas exigem 5 bytes de espaço dentro do registro como uma ligação e isso também pode levar a JET_errRecordTooBig serem retornadas.

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: Este erro só será devolvido 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 encerrada.

JET_errUpdateNotPrepared

O cursor não está atualmente no processo de inserção de um novo registro ou atualização de um registro existente.

JET_errVersionStoreOutOfMemory

Este erro ocorrerá quando o tamanho configurado do armazenamento de versão for insuficiente para armazenar 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.

No sucesso, a parte desejada de um valor de coluna para uma determinada coluna é definida com dados copiados do buffer de entrada. O conjunto de dados pode ter sido truncado se excedeu o comprimento máximo especificado para uma coluna de comprimento variável.

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

Observações

A definição de valores longos, valores para colunas JET_coltypLongBinary do tipo JET_coltypLongText ou JET_coltypLongBinary, deve ser feita 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, modificações em valores longos armazenados separadamente podem ser totalmente confirmadas, 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 podem ser totalmente revertidos, cancelando a atualização e revertendo a transação da 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 o JetUpdate é chamado. Isso permite a atualização mais eficiente dos í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 separadamente do registro se os dados no registro excederem seu limite como resultado de uma operação JetSetColumn . O JET_errRecordTooBig de erro só será retornado depois que todos os dados separáveis da coluna de registro tiverem sido armazenados separadamente do registro e o registro ainda exceder o limite de tamanho do registro.

Requerimentos

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.

Ver também

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns

  • Last updated on