OVERLAY スカラー関数

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

スキーマは SYSIBM です。

source-string

ソース・ストリングを指定する式。この式は、組み込みデータ・タイプであるストリング、数値、ブール、日時のいずれかの値を返す必要があります。値がストリング・データ・タイプでない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。

insert-string

source-string に挿入するストリングを指定する式。挿入の開始点は、start で指定する位置になります。この式は、組み込みデータ・タイプであるストリング、数値、ブール、日時のいずれかの値を返す必要があります。値がストリング・データ・タイプでない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。 insert-string のコード・ページが source-string のコード・ページと異なる場合は、insert-string は source-string のコード・ページに変換されます。

start

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

length

ソース・ストリングから削除する (指定のストリング単位による) コード単位の数を指定する式。削除の開始点は、start で指定する位置になります。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。値は、正整数またはゼロでなければなりません (SQLSTATE 22011)。OCTETS が指定され、結果が GRAPHIC データである場合、値は偶数またはゼロでなければなりません (SQLSTATE 428GC)。

length を指定しないことは、1 の値を指定することと同じです。ただし、OCTETS を指定して結果が GRAPHIC データである場合を除きます (この場合は、length を指定しないことは 2 の値を指定することと同じです。)。

CODEUNITS16、CODEUNITS32、または OCTETS

start および length のストリング単位を指定します。

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

ストリング単位として CODEUNITS16 または CODEUNITS32 を指定した場合に、結果がバイナリー・ストリングまたは FOR BIT DATA ストリングであれば、エラーが戻されます (SQLSTATE 428GC)。ストリング単位が CODEUNITS16 または OCTETS として指定されており、source-string のストリング単位が CODEUNITS32 である場合は、エラーが戻されます (SQLSTATE 428GC)。ストリング単位として OCTETS を指定すると、操作は、source-string のコード・ページで実行されます。

ストリング単位引数が指定されておらず、source-string と insert-string の両方が FOR BIT DATA 以外の文字ストリングであるか、グラフィック・ストリングである場合、デフォルトは CODEUNITS32 です。それ以外の場合、デフォルトは OCTETS です。

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	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` のデータ・タイプの関数で示される結果のデータ・タイプ (Unicode データベースのみの特殊ケース)
`source-string`		`insert-string`		結果
データ・タイプ	ストリング単位	データ・タイプ	ストリング単位	長さ属性	ストリング単位
長さ属性 A を持つ文字ストリング	OCTETS	長さ属性 B を持つ GRAPHIC ストリング	CODEUNITS16	A+3*B	OCTETS
			CODEUNITS32	A+4*B
		長さ属性 B を持つ文字	CODEUNITS32	A+4*B
長さ属性 A を持つ GRAPHIC ストリング	CODEUNITS16	長さ属性 B を持つ文字	OCTETS	A+B	CODEUNITS16
			CODEUNITS32	A+2*B
		長さ属性 B を持つ GRAPHIC ストリング	CODEUNITS32	A+2*B

結果の実際の長さは、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 OVERLAY('INSERTING','IS',4,2,OCTETS),
     OVERLAY('INSERTING','IS',4,0,OCTETS),
     OVERLAY('INSERTING','',4,2,OCTETS)
     FROM SYSIBM.SYSDUMMY1
```
例 2: 'INSERTING' というストリングから、'XXINSERTING'、'XXNSERTING'、'XXSERTING'、'XXERTING' というストリングを作成するために、1 という開始点を使用して既存のテキストの前にテキストを挿入します。
```
   SELECT OVERLAY('INSERTING','XX',1,0,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,1,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,2,CODEUNITS16)),
     OVERLAY('INSERTING','XX',1,3,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1
```
例 3: 'ABCABC' というストリングから、'ABCABCXX' というストリングを作成するために、既存のテキストの後にテキストを挿入します。ソース・ストリングの長さは 6 文字なので、開始点を 7 (つまり、ソース・ストリングの長さに 1 を加算した値) に設定します。
```
   SELECT OVERLAY('ABCABC','XX',7,0,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1
```

例 4: ストリング 'Hegelstraße' を 'Hegelstrasse' に変更します。

   SELECT OVERLAY('Hegelstraße','ss',10,1,CODEUNITS16))
     FROM SYSIBM.SYSDUMMY1

例 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 表記がそれぞれ含まれているとします。 OVERLAY 関数を使用して、'C' を Unicode ストリング '&N~AB' に挿入します。
```
   SELECT OVERLAY(UTF8_VAR, 'C', 1, CODEUNITS16),
     OVERLAY(UTF8_VAR, 'C', 1, CODEUNITS32),
     OVERLAY(UTF8_VAR, 'C', 1, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ値 'C?N~AB'、'CN~AB'、および 'CbbbN~AB' が返されます。ここで '?' は X'EDB49E' を表し、中間の UTF-16 形式の X'DD1E' に対応します。また 'bbb' により UTF-8 の不完全な文字 X'9D849E' が置き換えられます。
```
   SELECT OVERLAY(UTF8_VAR, 'C', 5, CODEUNITS16),
     OVERLAY(UTF8_VAR, 'C', 5, CODEUNITS32),
     OVERLAY(UTF8_VAR, 'C', 5, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ値 '&N~CB'、'&N~AC'、および '&N~AB' が返されます。
```
   SELECT OVERLAY(UTF16_VAR, 'C', 1, CODEUNITS16),
     OVERLAY(UTF16_VAR, 'C', 1, CODEUNITS32)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ値 'C?N~AB' および 'CN~AB' が返されます。ここで '?' により、不一致の低位サロゲート U+DD1E が表されます。
```
   SELECT OVERLAY(UTF16_VAR, 'C', 5, CODEUNITS16),
     OVERLAY(UTF16_VAR, 'C', 5, CODEUNITS32)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ値 '&N~CB' および '&N~AC' が返されます。

	'&'	'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'