LPAD スカラー関数

LPAD 関数は、ストリングの左側に、指定された文字ストリングまたはブランクを埋め込みます。

スキーマは SYSIBM です。

LPAD 関数は、ストリング式内の先行ブランクまたは末尾ブランクを有効として扱います。埋め込みは、string-expression の実際の長さが integer より短く、pad が空ストリングでない場合のみ行われます。

ストリング式

ソース・ストリングを指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、バイナリー・ストリング、CLOB 値または DBCLOB 値、数値、ブール値、または日時値を戻す必要があります。値に応じて以下のようになります。

CLOB、数値、ブール値、または日時値。関数が評価される前に VARCHAR に暗黙的にキャストされます。
DBCLOB 値の場合は、関数の評価の前に VARGRAPHIC に暗黙的にキャストされます。

値のデータ・タイプを BLOB にすることはできません (SQLSTATE 42815)。

整数

ストリング式のストリング単位で結果の実際の長さを指定する式。式は、組み込み数値、ブール値、または文字ストリングを返す必要があります。 Unicode データベースでは、この式で GRAPHIC ストリングを返すこともできます。その場合、関数の評価の前にまず文字ストリングに変換されます。この式で返される値が整数でない場合、関数の評価の前に INTEGER にキャストされます。値は、ゼロ、またはストリング式の単位の結果データ・タイプの最大長以下の正整数でなければなりません。

パッド

埋め込むストリングを指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、バイナリー・ストリング、CLOB 値または DBCLOB 値、数値、ブール値、または日時値を戻す必要があります。値に応じて以下のようになります。

CLOB、数値、ブール値、または日時値。関数が評価される前に VARCHAR に暗黙的にキャストされます。
DBCLOB 値の場合は、関数の評価の前に VARGRAPHIC に暗黙的にキャストされます。

pad のデータ・タイプを BLOB にすることはできません (SQLSTATE 42815)。

ストリング式のデータ・タイプに応じて、以下のようにデフォルトの埋め込みストリングが決まります。

ストリング式が文字ストリングである場合、SBCS ブランク文字。
ストリング式が GRAPHIC ストリングである場合、表意文字のブランク文字。 EUC データベースの GRAPHIC ストリングの場合は、X'3000' が使用されます。 Unicode データベースの GRAPHIC ストリングの場合は、X'0020' が使用されます。
ストリング式がバイナリー・ストリングである場合、16 進数のゼロ (X'00')。

結果

結果のデータ・タイプは、ストリング式のデータ・タイプによって異なります。

データ・タイプが VARCHAR または CHAR の場合、VARCHAR
データ・タイプが VARGRAPHIC または GRAPHIC の場合、VARGRAPHIC
データ・タイプが VARBINARY または BINARY の場合、VARBINARY

この関数の結果は、可変長ストリングで、ストリング単位およびコード・ページはストリング式と同じになります。ストリング式と埋め込み式の値は、互換性のあるデータ・タイプでなければなりません。ストリング式と埋め込み式のコード・ページが異なる場合は、埋め込み式がストリング式のコード・ページに変換されます。ストリング式または埋め込み式が FOR BIT DATA またはバイナリー・ストリングである場合、文字は変換されません。

この結果の長さ属性は、integer の値が、関数呼び出しを含む SQL ステートメントのコンパイル時に使用可能か(例えば、定数または定数式として指定されている場合)、または関数の実行時にのみ使用可能か (例えば、関数呼び出しの結果として指定されている場合) によって異なります。値が、関数呼び出しを含む SQL ステートメントのコンパイル時に使用可能な場合に、integer がゼロより大きいと、結果の長さ属性は integer になります。 integer が 0 の場合、結果の長さ属性は 1 です。値が関数の実行時にのみ使用可能な場合、結果の長さ属性は、以下の表に従って決定されます。

表 1. 関数の実行時にのみ integer が使用可能である場合の結果の長さの決定
string-expression のデータ・タイプ	結果データ・タイプの長さ
CHAR(n)、VARCHAR(n)、BINARY(n)、または VARBINARY(n)	n+100 と 32 672 のうちの最小値
GRAPHIC(n) または VARGRAPHIC(n)	n+100 と 16 336 のうちの最小値
ストリング単位が CODEUNITS32 の CHAR(n) または VARCHAR(n) または GRAPHIC(n) または VARGRAPHIC(n) (Unicode データベースのみ)	n+100 と 8 168 のうちの最小値

結果の実際の長さは integer から決定されます。 integer が 0 の場合、実際の長さは 0 で、結果は空の結果ストリングになります。 integer が string-expression の実際の長さよりも小さい場合、実際の長さは integer で、結果は切り捨てられます。

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

例

例 1: NAME は、値 Chris、Meg、および Jeff を含む VARCHAR (15) 列であるとします。次の照会では、値の左側にピリオドが完全に埋め込まれます。
```
SELECT LPAD(NAME,15,'.' ) AS NAME FROM T1;
```
これは、以下のものを戻します。
```
NAME 
--------------- 
..........Chris
............Meg 
...........Jeff
```
例 2: NAME は、値 Chris、Meg、および Jeff を含む VARCHAR (15) 列であるとします。次の照会では、長さ 5 までのみ各値にピリオドが埋め込まれます。
```
SELECT LPAD(NAME,5,'.' ) AS NAME FROM T1;
```
これは、以下のものを戻します。
```
NAME 
----- 
Chris 
..Meg 
.Jeff
```
例 3: NAME は、値 Chris、Meg、および Jeff を含む CHAR(15) 列であるとします。 NAME は固定長の文字フィールドで、既にブランクが埋め込まれているため、LPAD 関数は埋め込みを行いません。ただし、結果の長さは 5 なので、列の切り捨てが行われます。
```
SELECT LPAD(NAME,5,'.' ) AS NAME FROM T1;
```
これは、以下のものを戻します。
```
NAME 
----- 
Chris 
Meg 
Jeff
```
例 4: NAME は、値 Chris、Meg、および Jeff を含む VARCHAR (15) 列であるとします。場合によって、指定された埋め込みストリングの部分的なインスタンスが戻されます。
```
SELECT LPAD(NAME,15,'123' ) AS NAME FROM T1;
```
これは、以下のものを戻します。
```
NAME 
--------------- 
1231231231Chris 
123123123123Meg 
12312312312Jeff
```
例 5: NAME は、値 Chris、Meg、および Jeff を含む VARCHAR (15) 列であるとします。 Chris では切り捨てが、Meg では埋め込みが行われ、Jeff は変更されないことに注意してください。
```
SELECT LPAD(NAME,4,'.' ) AS NAME FROM T1;
```
これは、以下のものを戻します。
```
NAME 
---- 
Chri 
.Meg 
Jeff
```