LEFT スカラー関数

LEFT 関数は、string-expression の左端にある長さ length のストリングを戻します (長さは、指定のストリング単位での長さになります)。

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

ストリング式結果を取り出すストリングを指定する式。式は、組み込みストリング、数値、ブール値、または日時値を返す必要があります。ストリングでない値は、関数の評価の前に VARCHAR に暗黙的にキャストされます。ストリングのサブストリングは、ストリングの 0 個以上の連続するコード・ポイントで構成されます。

string-expression の右側には必要な数の埋め込み文字が埋め込まれ、string-expression の指定のサブストリングが常に存在するようになります。埋め込み用の文字は、埋め込みが行われるコンテキストでストリングに埋め込みを適用するための文字と同じです。埋め込みの詳細については、『ストリング割り当て』と『割り当てと比較』を参照してください。

length

結果の長さを指定する式。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。 length は 0 以上でなければなりません (SQLSTATE 22011)。 OCTETS が指定され、結果が GRAPHIC データである場合、値は偶数でなければなりません (SQLSTATE 428GC)。

length が定数でなく、ストリング単位が指定されない場合、length は string-expression の長さ属性以下でなければなりません (SQLSTATE 22011)。

length が定数でなく、ストリング単位が指定される場合、length は、次の表の対応する値以下でなければなりません (SQLSTATE 22011)。

表 1. `length` が定数でなく、ストリング単位が指定される場合の `length` の最大値
`string-expression` のストリング単位	指定されたストリング単位	`length` の最大値 L = `string-expression` の長さ属性
OCTETS	OCTETS	L
OCTETS	CODEUNITS16	L/2
OCTETS	CODEUNITS32	L/4
CODEUNITS16	OCTETS	L*2
CODEUNITS16	CODEUNITS16	L
CODEUNITS16	CODEUNITS32	L/2
CODEUNITS32	OCTETS	L*4
CODEUNITS32	CODEUNITS16	L*2
CODEUNITS32	CODEUNITS32	L

length が定数の場合は、string-expression のデータ・タイプに応じて次のような制限があります。

CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC: length は、32,672 OCTETS、16,336 CODEUNITS16 、または 8168 CODEUNITS32 以下でなければなりません (SQLSTATE 22011)。
CLOB または DBCLOB: length は、2,147,483,647 OCTETS、1,073,741,823 CODEUNITS16、または 53,6870,911 CODEUNITS32 以下でなければなりません (SQLSTATE 22011)。
BLOB: length は、2,147,483,647 OCTETS 以下でなければなりません (SQLSTATE 22011)。

CODEUNITS16、CODEUNITS32、または OCTETS

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

CODEUNITS16 は、 length が 16 ビット UTF-16 コード単位で表現されることを指定します。 CODEUNITS32 は、 length が 32 ビットの UTF-32 コード単位で表現されることを指定します。 OCTETS を指定すると、length は、バイト単位の長さになります。

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

結果

この関数の結果は、 string-expressionのデータ・タイプによって異なる可変長ストリングになります。

string-expression が CHAR または VARCHAR の場合は VARCHAR
string-expression が CLOB の場合は CLOB
string-expression が GRAPHIC または VARGRAPHIC の場合は VARGRAPHIC
string-expression が DBCLOB の場合は DBCLOB
string-expression が BINARY または VARBINARY の場合は VARBINARY
string-expression が BLOB の場合は BLOB

結果のストリング単位は、string-expression のストリング単位です。結果の長さ属性は、次のように、length とストリング単位がどう指定されているかによって異なります。

length が定数でない場合、結果の長さ属性は string-expression の長さ属性と同じになります。
length が定数で、ストリング単位が指定されていない場合、結果の長さ属性は、length と string-expression の長さ属性のうち大きい方になります。

length が定数で、ストリング単位が指定されている場合、結果の長さ属性は、次の表 2 に示すようになります。

表 2. `length` が定数でストリング単位が指定されている場合の結果の長さ属性
`string-expression` のストリング単位	指定されたストリング単位	`length` の最大値 L = `string-expression` の長さ属性
OCTETS	OCTETS	max (L、 `length`)
OCTETS	CODEUNITS16	max (L, `長さ` * 2)
OCTETS	CODEUNITS32	max (L, `長さ` * 4)
CODEUNITS16	OCTETS	max (L, `長さ` /2)
CODEUNITS16	CODEUNITS16	max (L、 `length`)
CODEUNITS16	CODEUNITS32	max (L, `長さ` * 2)
CODEUNITS32	OCTETS	max (L, `長さ` /4)
CODEUNITS32	CODEUNITS16	max (L, `長さ` /2)
CODEUNITS32	CODEUNITS32	max (L、 `length`)

結果の実際の長さ (ストリング単位) は、length です。

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

例

例 1: 変数 ALPHA の値が「ABCDEF」であるとします。以下のステートメント:
```
   SELECT LEFT(ALPHA,3)
     FROM SYSIBM.SYSDUMMY1
```
ALPHA の左端の 3 文字である "ABC" が戻されます。
例 2: VARCHAR(50) で定義されている変数 NAME の値が「KATIE AUSTIN」、整変数 FIRSTNAME_LEN の値が 5 であると想定して、以下のステートメントを実行します。以下のステートメント:
```
   SELECT LEFT(NAME,FIRSTNAME_LEN)
     FROM SYSIBM.SYSDUMMY1
```
KATIE (K)が戻されます。
例 3: 以下のステートメントは、長さゼロのストリングを戻します。
```
   SELECT LEFT('ABCABC',0)
     FROM SYSIBM.SYSDUMMY1
```
例 4: EMPLOYEE 表の FIRSTNME 列は VARCHAR (12) として定義されます。「BROWN」というラストネームの従業員のファーストネームを検出し、そのファーストネームを 10 バイト・ストリングで戻すには、以下のようにします。
```
   SELECT LEFT(FIRSTNME, 10)
     FROM EMPLOYEE
     WHERE LASTNAME = 'BROWN'
```
「DAVID」という値の後に 5 つのブランク文字が埋め込まれた VARCHAR(12) ストリングが戻されます。

例 5: Unicode データベースでは、FIRSTNAME が VARCHAR(12) の列になっています。その値の 1 つ、6 文字のストリング「Jürgen」です。 FIRSTNAME が以下の値を持つ場合:

   Function...                       Returns...

   LEFT(FIRSTNAME,2,CODEUNITS32)   'Jü' -- x'4AC3BC'
   LEFT(FIRSTNAME,2,CODEUNITS16)   'Jü' -- x'4AC3BC'
   LEFT(FIRSTNAME,2,OCTETS)        'J'  -- x'4A20', a truncated string

例 6: 以下の例は、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'
20 バイトの長さ属性が指定されている変数 UTF8_VAR に、ストリングの UTF-8 表現が格納されると想定します。
```
   SELECT LEFT(UTF8_VAR, 2, CODEUNITS16),
     LEFT(UTF8_VAR, 2, CODEUNITS32),
     LEFT(UTF8_VAR, 2, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ "&"、"& N"、および "bb"という値を戻します。"b" はブランク文字を表します。
```
   SELECT LEFT(UTF8_VAR, 5, CODEUNITS16),
     LEFT(UTF8_VAR, 5, CODEUNITS32),
     LEFT(UTF8_VAR, 5, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ "&N~A"、"&N~AB"、および "&N"という値を戻します。
```
   SELECT LEFT(UTF8_VAR, 10, CODEUNITS16),
     LEFT(UTF8_VAR, 10, CODEUNITS32),
     LEFT(UTF8_VAR, 10, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ "&N~ABbbbb"、"&N~ABbbbbb"、および "&N~ABb"の値を戻します (“b” はブランク文字です)。
20 コード単位の長さ属性が指定されている変数 UTF16_VAR に、ストリングの UTF-16BE 表現が格納されると想定します。
```
   SELECT LEFT(UTF16_VAR, 2, CODEUNITS16),
     LEFT(UTF16_VAR, 2, CODEUNITS32),
     HEX (LEFT(UTF16_VAR, 2, OCTETS))
   FROM SYSIBM.SYSDUMMY1
```
"&"、"&N"、および X'D834'という値がそれぞれ戻されます (X'D834' は一致しない上位サロゲートです)。
```
   SELECT LEFT(UTF16_VAR, 5, CODEUNITS16),
     LEFT(UTF16_VAR, 5, CODEUNITS32),
     LEFT(UTF16_VAR, 6, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ "&N~A"、"&N~AB"、および "&N"という値を戻します。
```
   SELECT LEFT(UTF16_VAR, 10, CODEUNITS16),
     LEFT(UTF16_VAR, 10, CODEUNITS32),
     LEFT(UTF16_VAR, 10, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ"&N~ABbbbb"、"&N~ABbbbb"、および "&N~A" という値を戻します。“b” はブランク文字を表します。

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