UPDATETEXT (Transact-SQL)

Aplica-se a: SQL Server Instância Gerenciada de SQL do Azure

Atualiza um campo text, ntext ou image existente. Use UPDATETEXT para alterar apenas uma parte de uma coluna text, ntext ou image em vigor. Use WRITETEXT para atualizar e substituir todo um campo text, ntext ou image.

Importante

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. Use os tipos de dados de valor grande e a cláusula .WRITE da instrução UPDATE nesse caso.

Convenções de sintaxe de Transact-SQL

Sintaxe

UPDATETEXT [BULK] { table_name.dest_column_name dest_text_ptr }  
  { NULL | insert_offset }  
     { NULL | delete_length }  
     [ WITH LOG ]  
     [ inserted_data  
    | { table_name.src_column_name src_text_ptr } ]  

Argumentos

BULK
Permite carregar ferramentas para carregar um fluxo de dados binários. O fluxo deve ser fornecido pela ferramenta no nível do protocolo TDS. Quando o fluxo de dados não está presente, o processador de consulta ignora a opção de BULK.

Importante

Nós recomendamos que a opção de BULK não seja usada em aplicativos baseados no SQL Server. Essa opção deve ser alterada ou removida em uma futura versão do SQL Server.

table_name . dest_column_name
É o nome da tabela e da coluna text, ntext ou image a ser atualizado. Os nomes de tabela e de coluna devem obedecer às regras de identificadores. A especificação do nome do banco de dados e de nomes de proprietários é opcional.

dest_text_ptr
É um valor de ponteiro de texto (retornado pela função TEXTPTR) que aponta para os dados text, ntext ou image a serem atualizados. dest_text_ptr deve ser binary(16).

insert_offset
É a posição inicial baseada em zero para a atualização. Para colunas text ou image, insert_offset é o número de bytes a ser ignorado do início da coluna existente antes de inserir novos dados. Para colunas ntext, insert_offset é o número de caracteres (cada caractere ntext usa 2 bytes). Os dados text, ntext ou image existentes que começam nessa posição inicial baseada em zero são deslocados para a direita, dando lugar aos novos dados. Um valor de 0 insere os novos dados no início dos dados existentes. Um valor NULL acrescenta os novos dados ao valor dos dados existentes.

delete_length
É o tamanho dos dados a serem excluídos da coluna text, ntext ou image existente, começando na posição insert_offset. O valor de delete_length é especificado em bytes para colunas text e image e em caracteres para colunas ntext. Cada caractere ntext usa 2 bytes. Um valor de 0 não exclui nenhum dado. Um valor NULL exclui todos os dados da posição insert_offset até o final da coluna text ou image existente.

WITH LOG
A criação de log é determinada pelo modelo de recuperação em vigor para o banco de dados.

inserted_data
São os dados a serem inseridos na coluna text, ntext ou image existente no local insert_offset. Esse é um único valor char, nchar, varchar, nvarchar, binary, varbinary, text, ntext ou image. inserted_data pode ser um literal ou uma variável.

table_name.src_column_name
É o nome da tabela e da coluna text, ntext ou image usada como a origem dos dados inseridos. Os nomes de tabela e de coluna devem estar em conformidade com as regras para identificadores.

src_text_ptr
É um valor de ponteiro de texto (retornado pela função TEXTPTR) que aponta para uma coluna text, ntext ou image usada como a origem dos dados inseridos.

Observação

O valor de scr_text_ptr não deve ser o mesmo que o valor dest_text_ptr.

Comentários

Os dados recém-inseridos podem ser uma única constante inserted_data, um nome de tabela, um nome de coluna ou um ponteiro de texto.

Ação de atualizar	Parâmetros UPDATETEXT
Para substituir dados existentes	Especifique um valor de insert_offset não nulo, um valor de delete_length diferente de zero e os novos dados a serem inseridos.
Para excluir dados existentes	Especifique um valor não nulo de insert_offset e um delete_length diferente de zero. Não especifique novos dados a serem inseridos.
Para inserir novos dados	Especifique o valor de insert_offset, um delete_length igual a 0 e os novos dados a serem inseridos.

Para obter um melhor desempenho, recomendamos que os dados text, ntext e image sejam inseridos ou atualizados em tamanhos de partes que sejam múltiplos de 8.040 bytes.

No SQL Server, podem existir ponteiros de texto em linha para os dados de text, ntext ou image, mas talvez eles não sejam válidos. Para obter informações sobre a opção text in row, confira sp_tableoption (Transact-SQL). Para obter informações sobre como invalidar ponteiros de texto, confira sp_invalidate_textptr (Transact-SQL).

Para inicializar colunas text com NULL, use WRITETEXT; UPDATETEXT inicializa colunas text com uma cadeia de caracteres vazia.

Permissões

Requer a permissão UPDATE na tabela especificada.

Exemplos

O exemplo a seguir coloca o ponteiro de texto na variável local @ptrval e, depois, usa UPDATETEXT para atualizar um erro ortográfico.

Observação

Para executar este exemplo, é necessário instalar o banco de dados pubs.

USE pubs;  
GO  
ALTER DATABASE pubs SET RECOVERY SIMPLE;  
GO  
DECLARE @ptrval BINARY(16);  
SELECT @ptrval = TEXTPTR(pr_info)   
   FROM pub_info pr, publishers p  
      WHERE p.pub_id = pr.pub_id   
      AND p.pub_name = 'New Moon Books'  
UPDATETEXT pub_info.pr_info @ptrval 88 1 'b';  
GO  
ALTER DATABASE pubs SET RECOVERY FULL;  
GO  

Consulte Também

READTEXT (Transact-SQL)
TEXTPTR (Transact-SQL)
WRITETEXT (Transact-SQL)