UPDATETEXT (Transact-SQL)

Atualiza um campo text, ntext ou image existente. Use UPDATETEXT para alterar somente uma parte de uma coluna text, ntext ou image existente. Use WRITETEXT para atualizar e substituir um campo text, ntext ou image inteiro.

Importante
Esse recurso será removido em uma versão futura do Microsoft 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 em seu lugar.

Convenções da sintaxe 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 atualizada. Os nomes de tabela e de coluna devem estar em conformidade com as regras para 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 as colunas text ou image, insert_offset é o número de bytes a serem ignorados no 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 comprimento dos dados a serem excluídos da coluna text, ntext ou image existente, começando da posição insert_offset. O valor delete_lengthé especificado em bytes para as colunas text e image e em caracteres para as 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 fim 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. Este é 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 usadas 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 scr_text_ptrnão deve ser igual ao valor dest_text_ptr.

Comentários

Dados recentemente inseridos podem ser uma única constante inserted_data, nome de tabela, nome de coluna ou ponteiro de texto.

Ação de atualizar	Parâmetros UPDATETEXT
Para substituir dados existentes	Especifique um valor insert_offset não nulo, um valor delete_length diferente de zero e os novos dados a serem inseridos.
Para excluir dados existentes	Especifique um valor insert_offset não nulo e um delete_length diferente de zero. Não especifique novos dados a serem inseridos.
Para inserir novos dados	Especifique o valor insert_offset, um valor delete_length de 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 blocos de tamanhos que sejam múltiplos de 8.040 bytes.

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

Para inicializar as colunas text para NULL, use WRITETEXT; UPDATETEXT inicializa as colunas text para 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

Referência

READTEXT (Transact-SQL)

TEXTPTR (Transact-SQL)

WRITETEXT (Transact-SQL)