COLLATION_KEY スカラー関数

COLLATION_KEY 関数は、指定の照合順序における、式の引数の照合キーを表す VARBINARY ストリングを戻します。

スキーマは SYSIBM です。

2 つのストリングの COLLATION_KEY の結果では、指定した collation-name 内のそれらの順序を判別するためのバイナリー比較を行うことができます。比較が意味を持つためには、使用される結果が同じ collation-name に基づいている必要があります。

ストリング式

照合キーを求める式。式は、組み込み文字ストリング、グラフィック・ストリング、数値、日時のいずれかのデータ・タイプの値を戻す必要があります。数値および日時のデータ・タイプは、暗黙的キャストを介してサポートされます。この式は FOR BIT DATA サブタイプであってはなりません (SQLSTATE 429BM)。 CLOB、数値、または日時のデータ・タイプの式は、関数の評価の前に VARCHAR にキャストされます。 DBCLOB の式は、関数の評価の前に VARGRAPHIC にキャストされます。 string-expression が UTF-16 でない場合、この関数は、string-expression のコード・ページを UTF-16 に変換します。コード・ページ変換の結果に置換文字が 1 つ以上含まれている場合、この関数は、その置換文字を含む UTF-16 ストリングの照合キーを戻します。そのような場合は、SQLCA 内の警告標識 SQLWARN8 が「W」に設定されます。

照合名 (collation-name)

照合キーを求めるために使用する照合順序を指定する式。この式は CHAR または VARCHAR の値を戻す必要があります。 Unicode データベースでは、式は GRAPHIC または VARGRAPHIC にすることもできます。この式は定数でなければなりません (SQLSTATE 428I9)。 collation-name の値は、大/小文字の区別がなく、Unicode 照合アルゴリズムに基づく照合順序または Unicode データの言語対応型の照合順序でなければなりません (SQLSTATE 42704)。

length

結果の長さ属性をバイト単位で指定する式。この式は、数値、CHAR、または VARCHAR の組み込みデータ・タイプの値を戻す必要があります。 Unicode データベースでは、式は GRAPHIC または VARGRAPHIC のデータ・タイプにすることもできます。 CHAR、VARCHAR、GRAPHIC、および VARGRAPHIC は、暗黙的キャストを介してサポートされます。 INTEGER でない式は、関数の評価の前に INTEGER にキャストされます。値は 1 から 32 672 の範囲でなければなりません (SQLSTATE 42815)。この式は定数でなければなりません (SQLSTATE 428I9)。

length の値を指定しない場合に結果の長さがどのように決まるかを以下の表にまとめます。

表 1. 結果の長さの決定
string-expression のデータ・タイプ	結果データ・タイプの長さ
CHAR(n) または VARCHAR(n)	12n バイトと 32 672 バイトのうちの最小値
GRAPHIC(n) または VARGRAPHIC(n)	12n バイトと 32 672 バイトのうちの最小値

length を指定するかどうかにかかわりなく、照合キーの長さが結果のデータ・タイプの長さよりも長い場合は、エラーが戻されます (SQLSTATE 42815)。照合キーの最終的な実際の長さは、UTF-16 に変換された後、string-expression の長さの約 6 倍になります。

string-expression が空ストリングの場合は、結果は、ゼロ以外の長さを持つ可能性がある有効な照合キーです。

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

例

次の照会は、コード・ページ 923 のドイツ語の言語対応型照合順序を使用して、従業員を姓の順序で並べます。
```
   SELECT FIRSTNME, LASTNAME
      FROM EMPLOYEE
         ORDER BY COLLATION_KEY (LASTNAME, 'SYSTEM_923_DE')
```

次の照会では、ケベック州にある従業員の部門を検索するために言語文化的に正しい比較が使用されます。

   SELECT E.WORKDEPT
      FROM EMPLOYEE AS E INNER JOIN SALES AS S
      ON COLLATION_KEY(E.LASTNAME, 'CLDR181_LFR') =
         COLLATION_KEY(S.SALES_PERSON, 'CLDR181_LFR')
         WHERE S.REGION = 'Quebec'