WRITETEXT (Transact-SQL)

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

Permite a atualização interativa minimamente registrada de uma coluna de text, ntext ou image existente. WRITETEXT substitui quaisquer dados existentes na coluna afetada. WRITETEXT não pode ser usado em colunas de text, ntext e image em exibições.

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

WRITETEXT [BULK]  
  { table.column text_ptr }  
  [ WITH LOG ] { data }  

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 .column
É o nome da tabela e da coluna de text, ntext ou image a ser atualizado. Os nomes de tabela e de coluna precisam estar de acordo com as regras para identificadores. A especificação do nome do banco de dados e de nomes de proprietários é opcional.

text_ptr
É um valor que armazena o ponteiro para os dados de text, ntext ou image. text_ptr precisa ser binary(16). Para criar um ponteiro de texto, execute uma instrução INSERT ou UPDATE com os dados não nulos para a coluna text, ntext ou image.

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

data
São os dados reais de text, ntext ou image a serem armazenados. data pode ser um literal ou um parâmetro. O comprimento máximo do texto que pode ser inserido de forma interativa com WRITETEXT é de aproximadamente 120 KB para dados de text, ntext e image.

Comentários

Use WRITETEXT para substituir dados de text, ntext e image e UPDATETEXT para modificar dados de text, ntext e image. UPDATETEXT é mais flexível porque altera somente uma parte de uma coluna de text, ntext ou image e não a coluna inteira.

Para obter o melhor desempenho possível, recomenda-se que os dados de text, ntext e image sejam inseridos ou atualizados em partes com tamanhos que sejam múltiplos de 8040 bytes.

Se o modelo de recuperação do banco de dados for simples ou bulk-logged, as operações de text, ntext e image que usam WRITETEXT serão registradas minimamente quando novos dados forem inseridos ou anexados.

Observação

A criação mínima de log não é usada quando valores existentes são atualizados.

Para que WRITETEXT funcione corretamente, a coluna já deve conter um ponteiro de texto válido.

Se a tabela não tiver texto em linha, o SQL Server economizará espaço com a não inicialização de colunas de text quando valores nulos explícitos ou implícitos forem adicionados em colunas de text com INSERT e quando nenhum ponteiro de texto puder ser obtido para esses nulos. Para inicializar colunas de text como NULL, use a instrução UPDATE. Se a tabela tiver texto em linha, não será necessário inicializar a coluna de texto para nulos e sempre será possível obter um ponteiro de texto.

A função ODBC SQLPutData é mais rápida e usa menos memória dinâmica que WRITETEXT. Esta função pode inserir até 2 gigabytes de dados de text, ntext ou image.

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

Permissões

Requer a permissão UPDATE na tabela especificada. A permissão será transferível quando a permissão UPDATE for transferida.

Exemplos

O exemplo a seguir coloca o ponteiro de texto na variável local @ptrval e, depois, WRITETEXT coloca a nova cadeia de caracteres de texto na linha apontada por @ptrval.

Observação

Para executar este exemplo, você deve instalar o banco de dados de exemplo 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'  
WRITETEXT pub_info.pr_info @ptrval 'New Moon Books (NMB) has just released another top ten publication. With the latest publication this makes NMB the hottest new publisher of the year!';  
GO  
ALTER DATABASE pubs SET RECOVERY SIMPLE;  
GO  

Consulte Também

Tipos de dados (Transact-SQL)
DECLARE @local_variable (Transact-SQL)
DELETE (Transact-SQL)
SELECT (Transact-SQL)
Instruções SET (Transact-SQL)
UPDATETEXT (Transact-SQL)