INSERT スカラー関数

INSERT 関数は、source-string の start から始めて、指定されたコード単位の length を削除し、insert-string を挿入したストリングを返します。

構文図を読む構文図をスキップするINSERT(source-string ,start,length,insert-string,CODEUNITS16CODEUNITS32OCTETS)

スキーマは SYSIBM です。INSERT 関数の SYSFUN バージョンは引き続き使用可能です。

INSERT 関数は、length 引数が必須である点を除けば、OVERLAY 関数と同じです。

source-string
ソース・ストリングを指定する式。この式は、組み込みデータ・タイプであるストリング、数値、ブール、日時のいずれかの値を返す必要があります。 値がストリング・データ・タイプでない場合、その値は関数を評価する前に 暗黙的に VARCHAR にキャストされます。
start
整数値を戻す式。この整数値では、ソース・ストリングから指定のコード単位を削除する開始点を指定します (この開始点は、別のストリングの挿入を開始する開始点でもあります)。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、 その値は関数を評価する前に暗黙的に INTEGER にキャストされます。 この整数値は、指定されたストリング単位を使用したコード単位での開始点です。 この整数値は、1 から、暗黙的または明示的なストリング単位での source-string の実際の長さに 1 を加算した値までの範囲でなければなりません (SQLSTATE 22001)。 OCTETS が指定され、結果が GRAPHIC データの場合、値は 1 から、source-string の実際のオクテットの長さに 1 を加算した値までの範囲にある奇数でなければなりません (SQLSTATE 428GC または 22011)。
length
ソース・ストリングから削除する (指定のストリング単位による) コード単位の数を指定する式。削除の開始点は、start で指定する位置になります。 式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。 値は、正整数またはゼロでなければなりません (SQLSTATE 22011)。OCTETS が指定され、結果が GRAPHIC データである場合、値は偶数またはゼロでなければなりません (SQLSTATE 428GC)。
insert-string
source-string に挿入するストリングを指定する式。挿入の開始点は、start で指定する位置になります。 この式は、組み込みデータ・タイプであるストリング、数値、ブール、日時のいずれかの値を返す必要があります。 値がストリング・データ・タイプでない場合、その値は関数を評価する前に 暗黙的に VARCHAR にキャストされます。
CODEUNITS16、CODEUNITS32、または OCTETS
start および length のストリング単位を指定します。

CODEUNITS16 は、start および length を 16 ビットの UTF-16 コード単位で表すことを指定します。CODEUNITS32 は、start および length を 32 ビットの UTF-32 コード単位で表すことを指定します。OCTETS は、start および length をバイト単位で表すことを指定します。

ストリング単位として CODEUNITS16 または CODEUNITS32 を指定した場合に、結果がバイナリー・ストリングまたはビット・データであれば、エラーが戻されます (SQLSTATE 428GC)。 ストリング単位が CODEUNITS16 または OCTETS で指定され、source-string のストリング単位が CODEUNITS32 の場合、エラーが戻されます (SQLSTATE 428GC)。 ストリング単位として OCTETS を指定すると、操作は、source-string のコード・ページで実行されます。 ストリング単位が明示的に指定されなければ、source-string のストリング単位によって、使用される単位が決定されます。 CODEUNITS16、CODEUNITS32、および OCTETS の詳細については、『文字ストリング』の『組み込み関数のストリング単位』を参照してください。

結果のデータ・タイプは、source-string と insert-string のデータ・タイプによって異なります。サポートされているタイプの組み合わせを以下の表にまとめます。結果のストリング単位は、source-string のストリング単位です。 source-string または insert-string のいずれかが FOR BIT DATA と定義された場合、もう一方の引数を CODEUNITS32 のストリング単位で定義することはできません。 2 番目の表は、Unicode データベースのみに適用されます。

表 1. source-string と insert-string のデータ・タイプに対応した関数結果のデータ・タイプ
source-string insert-string 結果
CHAR または VARCHAR CHAR または VARCHAR VARCHAR
GRAPHIC または VARGRAPHIC GRAPHIC または VARGRAPHIC VARGRAPHIC
CLOB CHAR、VARCHAR、または CLOB CLOB
CHAR または VARCHAR CLOB CLOB
DBCLOB GRAPHIC、VARGRAPHIC、または DBCLOB DBCLOB
GRAPHIC または VARGRAPHIC DBCLOB DBCLOB
CHAR または VARCHAR CHAR FOR BIT DATA または VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
CHAR FOR BIT DATA または VARCHAR FOR BIT DATA CHAR、VARCHAR、CHAR FOR BIT DATA、または VARCHAR FOR BIT DATA VARCHAR FOR BIT DATA
BINARY または VARBINARY BINARY または VARBINARY VARBINARY
BLOB BINARY、VARBINARY、または BLOB BLOB
BINARY または VARBINARY BLOB BLOB
注: source-string または insert-string のどちらかがバイナリー・データ・タイプで、もう一方が FOR BIT DATA ストリングである場合、バイナリー・データ・タイプでない引数が、対応するバイナリー・データ・タイプにキャストされるものとして扱われます。
表 2. 関数の source-string と insert-string のデータ・タイプと結果のデータ・タイプ (Unicode データベースのみ)
source-string insert-string 結果
CHAR または VARCHAR GRAPHIC または VARGRAPHIC VARCHAR
GRAPHIC または VARGRAPHIC CHAR または VARCHAR VARGRAPHIC
CLOB GRAPHIC、VARGRAPHIC、または DBCLOB CLOB
DBCLOB CHAR、VARCHAR、または CLOB DBCLOB

source-string の長さは 0 にすることもできます。 その場合、(前述の start の境界が示すとおり) start が 1 でなければならず、関数の結果は insert-string のコピーになります。

insert-string の長さを 0 にすることも可能です。この結果として、start と length で指定したコード単位が source-string から削除されます。

結果の長さ属性は、source-string と insert-string のストリング単位が同じか、または結果のストリング単位が CODEUNITS32 の場合、 source-string の長さ属性と insert-string の長さ属性を加算した値になります。 特殊なケースについては、次の表にリストされています。
表 3. source-string と insert-string のデータ・タイプの関数としての結果のデータ・タイプ (特殊なケース)
source-string insert-string 結果
データ・タイプ ストリング単位 データ・タイプ ストリング単位 長さ属性 ストリング単位
長さ属性 A を持つ文字ストリング OCTETS 長さ属性 B を持つ GRAPHIC ストリング CODEUNITS16 A+3*B OCTETS
長さ属性 A を持つ文字ストリング OCTETS 長さ属性 B を持つ GRAPHIC ストリング CODEUNITS32 A+4*B OCTETS
長さ属性 A を持つ文字ストリング OCTETS 長さ属性 B を持つ文字 CODEUNITS32 A+4*B OCTETS
長さ属性 A を持つ GRAPHIC ストリング CODEUNITS16 長さ属性 B を持つ文字 OCTETS A+B CODEUNITS16
長さ属性 A を持つ GRAPHIC ストリング CODEUNITS16 長さ属性 B を持つ文字 CODEUNITS32 A+2*B CODEUNITS16
長さ属性 A を持つ GRAPHIC ストリング CODEUNITS16 長さ属性 B を持つ GRAPHIC ストリング CODEUNITS32 A+2*B CODEUNITS16
結果の実際の長さは、source-string の実際の長さ、削除されたストリングの実際の長さ、insert-string の実際の長さ、および start と length の各引数に使用されたストリング単位によって決まります。例えば、ストリング引数が OCTETS の文字ストリングで、OCTETS が 4 番目の引数として使用され、結果の実際の長さは、A1 - MIN((A1 - V2 + 1), V3) + A4 で、各変数の意味は以下のとおりです。
  • A1 は source-string の実際の長さ
  • V2 は start の値
  • V3 は length の値
  • A4 は insert-string の実際の長さ
結果のストリングの実際の長さが戻りデータ・タイプの最大値を超える場合、エラーが戻されます (SQLSTATE 54006)。

引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。 引数のいずれかが NULL の場合、その結果は NULL 値です。

例

  • 例 1: INSERTING というストリングから、INSISTING、INSISERTING、INSTING というストリングを作成するために、既存のテキストの中にテキストを挿入します。 
       SELECT INSERT('INSERTING',4,2,'IS'),
     INSERT('INSERTING',4,0,'IS'),
     INSERT('INSERTING',4,2,'')
     FROM SYSIBM.SYSDUMMY1
  • 例 2: INSERTING というストリングから、XXINSERTING、XXNSERTING、XXSERTING、XXERTING というストリングを作成するために、1 という開始点を使用して既存のテキストの前にテキストを挿入します。 
       SELECT INSERT('INSERTING',1,0,'XX'),
     INSERT('INSERTING',1,1,'XX'),
     INSERT('INSERTING',1,2,'XX'),
     INSERT('INSERTING',1,3,'XX')
     FROM SYSIBM.SYSDUMMY1
  • 例 3: "ABCABC" というストリングから、"ABCABCXX" というストリングを作成するために、既存のテキストの後にテキストを挿入します。ソース・ストリングの長さは 6 文字なので、開始点を 7 (つまり、ソース・ストリングの長さに 1 を加算した値) に設定します。 
       SELECT INSERT('ABCABC',7,0,'XX')
     FROM SYSIBM.SYSDUMMY1
  • 例 4: ストリング "Hegelstraße" を "Hegelstrasse" に変更します。
       SELECT INSERT('Hegelstraße',10,1,'ss',CODEUNITS16)
     FROM SYSIBM.SYSDUMMY1
  • Example 5: 以下の例は、Unicode ストリング "&N~AB" に対応します。 "&" は音楽のト音記号、"~" は結合チルド文字です。 以下の例では、このストリングを異なる Unicode エンコード方式で示しています。
      & N ~ A B
    UTF-8 X'F09D849E' X'4E' X'CC83' X'41' X'42'
    UTF-16BE X'D834DD1E' X'004E' X'0303' X'0041' X'0042'
    変数 UTF8_VAR および UTF16_VAR に、ストリングの UTF-8 表記および UTF-16BE 表記がそれぞれ含まれているとします。 INSERT 関数を使用して、Unicode ストリング "&N~AB" に "C" を挿入します。
       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
    それぞれ CAB、CB、CN~AB という値を戻します。 
       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
    それぞれ &N~CB、&N~AC、&C~AB という値を戻します。 
       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
    それぞれ CAB、CB、CN~AB という値を戻します。 
       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
    それぞれ &N~C、&N~AC、&CAB という値を戻します。