UPDATETEXT (Transact-SQL)

Article
05/23/2023

S’applique à : SQL Server Azure SQL Managed Instance

Met à jour un champ text, ntext ou image existant. Utilisez UPDATETEXT pour changer seulement une partie d’une colonne text, ntext ou image. Utilisez WRITETEXT pour mettre à jour et remplacer un champ text, ntext ou image entier.

Important

Cette fonctionnalité sera supprimée dans une version future de SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement, et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Utilisez plutôt les types de données à valeur élevée et la clause .WRITE de l’instruction UPDATE.

Conventions de la syntaxe Transact-SQL

Syntaxe

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 } ]

Arguments

BULK
Permet aux outils de téléchargement de télécharger un flux de données binaires. Le flux de données doit être fourni par l'outil au niveau du protocole TDS. Lorsque le flux de données n'est pas présent, le processeur de requêtes ignore l'option BULK.

Important

Nous recommandons de ne pas utiliser l’option BULK dans les applications basées sur SQL Server. Cette option est susceptible d’être modifiée ou supprimée dans une future version de SQL Server.

table_name . dest_column_name
Nom de la table et de la colonne text, ntext ou image à mettre à jour. Les noms de table et les noms de colonne doivent suivre les règles applicables aux identificateurs. La spécification des noms de la base de données et du propriétaire est facultative.

dest_text_ptr
Valeur de pointeur de texte (retournée par la fonction TEXTPTR) qui pointe vers les données text, ntext ou image à mettre à jour. dest_text_ptr doit être de type binary(16).

insert_offset
Position de départ de la mise à jour (commence à zéro). Pour les colonnes text ou image, insert_offset correspond au nombre d’octets à ignorer depuis le début de la colonne existante, avant l’insertion de nouvelles données. Pour les colonnes ntext, insert_offset correspond au nombre de caractères (chaque caractère ntext utilise deux octets). Les données text, ntext ou image existantes commençant à cette position de départ basée sur zéro sont décalées vers la droite pour laisser de l’espace pour les nouvelles données. Une valeur 0 signifie que les nouvelles données seront insérées au début des données existantes. Une valeur NULL signifie que les nouvelles données seront ajoutées à la fin des données existantes.

delete_length
Longueur des données à supprimer dans la colonne text, ntext ou image existante, à partir de la position insert_offset. La valeur delete_length est spécifiée en octets pour les colonnes text et image et en caractères pour les colonnes ntext. Chaque caractère ntext utilise deux octets. La valeur 0 signifie aucune suppression de données. La valeur NULL supprime toutes les données entre la position insert_offset et la fin de la colonne text ou image existante.

WITH LOG
L'enregistrement dans un journal est déterminé par le mode de récupération en vigueur dans la base de données.

inserted_data
Données à insérer dans la colonne text, ntext ou image existante à la position insert_offset. Il s’agit d’une valeur unique de type char, nchar, varchar, nvarchar, binary, varbinary, text, ntext ou image. La valeur inserted_data peut être un littéral ou une variable.

table_name.src_column_name
Noms de la table et de la colonne text, ntext ou image utilisée comme source des données insérées. Les noms de tables et de colonnes doivent respecter les règles des identificateurs.

src_text_ptr
Valeur de pointeur de texte (retournée par la fonction TEXTPTR) qui pointe vers une colonne text, ntext ou image utilisée comme source des données insérées.

Notes

La valeur scr_text_ptr doit être différente de la valeur dest_text_ptr.

Remarques

Les nouvelles données insérées peuvent correspondre à une constante, un nom de table, un nom de colonne ou un pointeur de texte inserted_data unique.

Action de mise à jour	Paramètres UPDATETEXT
Remplacement des données existantes	Spécifiez une valeur insert_offset non NULL, une valeur delete_length différente de zéro et les nouvelles données à insérer.
Suppression des données existantes	Spécifiez une valeur insert_offset non NULL et une valeur delete_length différente de zéro. Ne spécifiez pas de nouvelles données à insérer.
Insertion de nouvelles données	Spécifiez la valeur insert_offset, une valeur delete_length différente de zéro et les nouvelles données à insérer.

Pour obtenir des performances optimales, nous vous recommandons d’insérer ou de mettre à jour les données text, ntext et image dans des tailles de bloc qui sont des multiples de 8 040 octets.

Dans SQL Server, les pointeurs de texte dans la ligne vers les données text, ntext ou image sont possibles, mais ils peuvent ne pas être valides. Pour plus d’informations sur l’option text in row, consultez sp_tableoption (Transact-SQL). Pour plus d’informations sur l’invalidation des pointeurs de texte, consultez sp_invalidate_textptr (Transact-SQL).

Pour initialiser les colonnes text avec la valeur NULL, utilisez WRITETEXT. UPDATETEXT initialise les colonnes text avec une chaîne vide.

Autorisations

Nécessite une autorisation UPDATE sur la table spécifiée.

Exemples

L'exemple suivant place le pointeur de texte dans la variable locale @ptrval, puis utilise UPDATETEXT pour corriger une faute d'orthographe.

Notes

Pour exécuter cet exemple, vous devez installer la base de données 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

Voir aussi

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

Partage via