INSERT (fonction scalaire)

La fonction INSERT renvoie une chaîne dans laquelle, à partir de start dans source-string, length des unités de code spécifiées ont été supprimées et insert-string a été inséré.

Read syntax diagramSkip visual syntax diagramINSERT(source-string ,start,length,insert-string,CODEUNITS16CODEUNITS32OCTETS)

Le schéma est SYSIBM. La version SYSFUN de la fonction INSERT reste disponible.

La fonction INSERT est identique à la fonction OVERLAY, sauf que l'argument de longueur est obligatoire.

chaîne-source
Expression qui spécifie la chaîne source. L'expression doit renvoyer une valeur qui est une chaîne intégrée, un type de données numérique, booléenou date-heure. Si la valeur n'est pas un type de données chaîne, elle est implicitement transtypée en VARCHAR avant d'évaluer la fonction.
démarrage
Expression qui renvoie une valeur entière. La valeur entière indique le point de départ dans la chaîne source où la suppression des unités de code et l'insertion d'une autre chaîne doivent commencer. L'expression doit renvoyer une valeur qui est un type de données numérique intégré, CHAR, VARCHAR, GRAPHIC ou VARGRAPHIC. Si la valeur n'est pas de type INTEGER, elle est implicitement transtypée en INTEGER avant d'évaluer la fonction. La valeur entière est le point de départ des unités de code utilisant les unités de chaîne spécifiées. La valeur entière doit être comprise entre 1 et la longueur réelle de source-string en unités de chaîne implicites ou explicites plus un (SQLSTATE 22001). Si OCTETS est spécifié et que le résultat est des données graphiques, la valeur doit être un nombre impair compris entre 1 et la longueur d'octet réelle de source-string plus un (SQLSTATE 428GC ou 22011).
longueur
Expression qui spécifie le nombre d' unités de code (dans les unités de chaîne spécifiées) à supprimer de la chaîne source, à partir de la position identifiée par start. L'expression doit renvoyer une valeur qui est un type de données numérique intégré, CHAR, VARCHAR, GRAPHIC ou VARGRAPHIC. Si la valeur n'est pas de type INTEGER, elle est implicitement transtypée en INTEGER avant d'évaluer la fonction. La valeur doit être un entier positif ou zéro (SQLSTATE 22011). Si OCTETS est spécifié et que le résultat est des données graphiques, la valeur doit être un nombre pair ou zéro (SQLSTATE 428GC).
chaîne-insertion
Expression qui spécifie la chaîne à insérer dans source-string, à partir de la position identifiée par start. L'expression doit renvoyer une valeur qui est une chaîne intégrée, un type de données numérique, booléenou date-heure. Si la valeur n'est pas un type de données chaîne, elle est implicitement transtypée en VARCHAR avant d'évaluer la fonction.
CODEUNITS16, CODEUNITS32ou OCTETS
Indique l'unité de chaîne start et length.

CODEUNITS16 indique que start et length sont exprimés en unités de code UTF-16 16 bits. CODEUNITS32 indique que start et length sont exprimés en unités de code UTF-32 32 bits. OCTETS indique que start et length sont exprimés en octets.

Si l'unité de chaîne est CODEUNITS16 ou CODEUNITS32et que le résultat est une chaîne binaire ou des données binaires, une erreur est renvoyée (SQLSTATE 428GC). Si l'unité de chaîne est spécifiée comme CODEUNITS16 ou OCTETS et que les unités de chaîne de la chaîne source sont CODEUNITS32, une erreur est renvoyée (SQLSTATE 428GC). Si l'unité de chaîne est spécifiée en tant que OCTETS, l'opération est effectuée dans la page de codes de la chaîne source. Si une unité de chaîne n'est pas explicitement spécifiée, l'unité de chaîne de la chaîne source détermine l'unité utilisée. Pour plus d'informations sur CODEUNITS16, CODEUNITS32et OCTETS, voir Unités de chaîne dans les fonctions intégrées dans Chaînes de caractères.

Le type de données du résultat dépend des types de données source-string et insert-string, comme indiqué dans les tableaux suivants des combinaisons de types prises en charge. L'unité de chaîne du résultat est l'unité de chaîne de source-string. Si source-string ou insert-string est défini comme FOR BIT DATA, l'autre argument ne peut pas être défini avec des unités de chaîne de CODEUNITS32.La deuxième table s'applique uniquement aux bases de données Unicode.

Tableau 1. Type de données du résultat en tant que fonction des types de données de source-string et insert-string
chaîne-source chaîne-insertion Résultat
Car ou Varcar Car ou Varcar VARCHAR
GRAPHIC ou VARGRAPHIC GRAPHIC ou VARGRAPHIC VARGRAPHIC
CLOB CHAR, VARCHAR ou CLOB CLOB
Car ou Varcar CLOB CLOB
DBCLOB GRAPHIC, VARGRAPHIC ou DBCLOB DBCLOB
GRAPHIC ou VARGRAPHIC DBCLOB DBCLOB
Car ou Varcar CHAR FOR BIT DATA ou VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
CHAR FOR BIT DATA ou VARCHAR FOR BIT DATA CHAR, VARCHAR, CHAR FOR BIT DATA ou VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
BINARY ou VARBINARY BINARY ou VARBINARY VARBINARY
BLOB BINARY, VARBINARY ou BLOB BLOB
BINARY ou VARBINARY BLOB BLOB
Remarque: Si source-string ou insert-string est un type de données binaire et que l'autre est une chaîne FOR BIT DATA, l'argument qui n'est pas un type de données binaire est traité comme s'il avait été transtypé vers le type de données binaires correspondant.
Tableau 2. Type de données du résultat en fonction des types de données de source-string et insert-string (bases de données Unicode uniquement)
chaîne-source chaîne-insertion Résultat
Car ou Varcar GRAPHIC ou VARGRAPHIC VARCHAR
GRAPHIC ou VARGRAPHIC Car ou Varcar VARGRAPHIC
CLOB GRAPHIC, VARGRAPHIC ou DBCLOB CLOB
DBCLOB CHAR, VARCHAR ou CLOB DBCLOB

Une chaîne source peut avoir une longueur de 0 ; dans ce cas, start doit être 1 (comme indiqué par les limites de start décrites précédemment) et le résultat de la fonction est une copie de insert-string.

Une chaîne d'insertion peut également avoir une longueur de 0. Cela a pour effet de supprimer les unités de code identifiées par start et length de la chaîne source.

L'attribut de longueur du résultat est l'attribut de longueur de source-string plus l'attribut de longueur de insert-string lorsque les unités de chaîne de source-string et insert-string sont identiques ou que les unités de chaîne de résultat sont CODEUNITS32. Les cas spéciaux sont répertoriés dans le tableau suivant.
Tableau 3. Type de données du résultat en fonction des types de données de source-string et insert-string (cas spéciaux)
chaîne-source chaîne-insertion Résultat
Type de données Unités de chaîne Type de données Unités de chaîne attribut de longueur (length attribute) Unités de chaîne
Chaîne de caractères avec l'attribut de longueur A OCTETS Chaîne graphique avec l'attribut de longueur B CODEUNITS16 A+3*B OCTETS
Chaîne de caractères avec l'attribut de longueur A OCTETS Chaîne graphique avec l'attribut de longueur B CODEUNITS32 A+4*B OCTETS
Chaîne de caractères avec l'attribut de longueur A OCTETS Caractère avec attribut de longueur B CODEUNITS32 A+4*B OCTETS
Chaîne graphique avec l'attribut de longueur A CODEUNITS16 Caractère avec attribut de longueur B OCTETS A + B CODEUNITS16
Chaîne graphique avec l'attribut de longueur A CODEUNITS16 Caractère avec attribut de longueur B CODEUNITS32 A+2*B CODEUNITS16
Chaîne graphique avec l'attribut de longueur A CODEUNITS16 Chaîne graphique avec l'attribut de longueur B CODEUNITS32 A+2*B CODEUNITS16
Longueur réelle du résultat dépend de la longueur réelle de chaîne-source, de la longueur réelle de la chaîne supprimée, de la longueur réelle de chaîne-insertionet des unités de chaîne utilisées pour les arguments démarrage et longueur . Par exemple, si les arguments de chaîne sont des chaînes de caractères dans OCTETS et que OCTETS est utilisé comme quatrième argument, la longueur réelle du résultat est A1 -MIN ((A1 - V2 + 1), V3) + A4, où:
  • A1 est la longueur réelle de source-string
  • V2 est la valeur de start
  • V3 est la valeur de length
  • A4 est la longueur réelle de insert-string
Si la longueur réelle de la chaîne de résultat dépasse le maximum autorisé pour le type de données renvoyé, une erreur est renvoyée (SQLSTATE 54006).

Si un argument peut être null, le résultat peut être null ; si un argument est null, le résultat est la valeur null.

Exemples

  • Exemple 1: Créez les chaînes INSISTANT, INSISERTINGet INSTING à partir de la chaîne INSERTING en insérant du texte au milieu du texte existant.
       SELECT INSERT('INSERTING',4,2,'IS'),
     INSERT('INSERTING',4,0,'IS'),
     INSERT('INSERTING',4,2,'')
     FROM SYSIBM.SYSDUMMY1
  • Exemple 2: créez les chaînes XXINSERTING, XXNSERT EN COURS, XXSERTet XXEN COURS à partir de la chaîne INSERTION en insérant du texte avant le texte existant, en utilisant 1 comme point de départ.
       SELECT INSERT('INSERTING',1,0,'XX'),
     INSERT('INSERTING',1,1,'XX'),
     INSERT('INSERTING',1,2,'XX'),
     INSERT('INSERTING',1,3,'XX')
     FROM SYSIBM.SYSDUMMY1
  • Exemple 3: Créez la chaîne ABCABCXX à partir de la chaîne ABCABC en insérant du texte après le texte existant. Etant donné que la chaîne source comporte 6 caractères, définissez la position de début sur 7 (un plus la longueur de la chaîne source).
       SELECT INSERT('ABCABC',7,0,'XX')
     FROM SYSIBM.SYSDUMMY1
  • Exemple 4: Remplacez la chaîne Hegelstraße par Hegelstrasse.
       SELECT INSERT('Hegelstraße',10,1,'ss',CODEUNITS16)
     FROM SYSIBM.SYSDUMMY1
  • Exemple 5: L'exemple suivant fonctionne avec la chaîne Unicode & N ~ AB, où & est le symbole musical G clé caractère, et ~ est le caractère tilde de combinaison. Cette chaîne est affichée sous différentes formes de codage Unicode dans l'exemple suivant:
      & N ~ Le octet
    UTF-8 X'F09D849E' X'4E' X' CC83 X'41' X'42'
    UTF-16BE X'D834DD1E' X'004E' X'0303' X'0041' X'0042'
    Supposons que les variables UTF8_VAR et UTF16_VAR contiennent les représentations UTF-8 et UTF-16BE de la chaîne, respectivement. Utilisez la fonction INSERT pour insérer un C dans la chaîne Unicode & N ~ AB.
       SELECT INSERT(UTF8_VAR, 1, 4, 'C', CODEUNITS16),
     INSERT(UTF8_VAR, 1, 4, 'C', CODEUNITS32),
     INSERT(UTF8_VAR, 1, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1
    renvoie les valeurs CAB, CBet CN ~ AB, respectivement.
       SELECT INSERT(UTF8_VAR, 5, 1, 'C', CODEUNITS16),
     INSERT(UTF8_VAR, 5, 1, 'C', CODEUNITS32),
     INSERT(UTF8_VAR, 5, 1, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1
    renvoie les valeurs & N ~ CB, & N ~ ACet & C ~ AB, respectivement.
       SELECT INSERT(UTF16_VAR, 1, 4, 'C', CODEUNITS16),
     INSERT(UTF16_VAR, 1, 4, 'C', CODEUNITS32),
     INSERT(UTF16_VAR, 1, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1
    renvoie les valeurs CAB, CBet CN ~ AB, respectivement.
       SELECT INSERT(UTF16_VAR, 5, 2, 'C', CODEUNITS16),
     INSERT(UTF16_VAR, 5, 1, 'C', CODEUNITS32),
     INSERT(UTF16_VAR, 5, 4, 'C', OCTETS)
   FROM SYSIBM.SYSDUMMY1
    renvoie les valeurs & N ~ C, & N ~ ACet & CAB, respectivement.