Partilhar via

  • Artigo

WRITETEXT (Transact-SQL)

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

Observação importanteImportante

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.

Ícone de vínculo de tópicoConvenções de sintaxe Transact-SQL

Sintaxe

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

Argumentos

  • table**.**column
    É 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.

  • text_ptr
    É um valor que armazena o ponteiro nos dados text, ntext ou image. text_ptr deve ser binary(16). Para criar um ponteiro de texto, execute uma instrução INSERT ou UPDATE com 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 text, ntext ou image reais a serem armazenados. data pode ser uma literal ou um parâmetro. O comprimento máximo de texto que pode ser inserido interativamente com WRITETEXT é aproximadamente 120 KB para dados text, ntext e image.

Comentários

Use WRITETEXT para substituir dados text, ntext e image, e UPDATETEXT para modificar dados text, ntext e image. UPDATETEXT é mais flexível porque altera somente uma parte de uma coluna text, ntext ou image, em vez da coluna inteira.

Para melhor desempenho, recomenda-se que dados text, ntext e image sejam inseridos ou atualizados em tamanhos de blocos múltiplos de 8040 bytes.

Se o modelo de recuperação do banco de dados for simples ou com log de operações em massa, as operações de text, ntext e image que usem WRITETEXT serão operações minimamente registradas quando novos dados forem inseridos ou anexados. Para obter mais informações, consulte Operações que podem ser minimamente registradas em log.

ObservaçãoObservaçã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 text quando valores nulos explícitos ou implícitos forem adicionados a colunas text com INSERT e nenhum ponteiro de texto puder ser obtido para tais nulos. Para inicializar colunas 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 SQLPutData de ODBC é mais rápida e usa menos memória dinâmica que WRITETEXT. Esta função pode inserir até 2 gigabytes de dados text, ntext ou image.

No SQL Server, podem existir ponteiros de texto em linha para dados text, ntext ou image, mas podem não ser 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).

Permissões

Requer 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 texto na linha apontada por @ptrval.

ObservaçãoObservação

Para executar este exemplo, você deve instalar o banco de dados de exemplo pubs. Para obter informações sobre como instalar o banco de dados de exemplo pubs, consulte Baixando os bancos de dados de exemplo Northwind e 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