WRITETEXT (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
  É recomendável que a opção BULK não seja usada em aplicativos baseados no SQL Server. Essa opção poderá ser alterada ou removida em uma futura versão do SQL Server.

• 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çã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 de texto em linha, 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çã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

Consulte também

Referência

Conceitos