REC2XML スカラー関数

REC2XML 関数は、XML タグで形式設定されて列名と列データを収めたストリングを戻します。

スキーマは SYSIBM です。

Unicode データベースでは、指定した引数が GRAPHIC ストリングであると、まず文字ストリングに変換されてから、関数が実行されます。

10 進定数 (decimal-constant)列データ文字の置換用の拡張係数。この 10 進値は 0.0 より大きく、6.0 以下でなければなりません (SQLSTATE 42820)。

decimal-constant は、関数の結果の長さを計算するために使われます。文字データ・タイプのそれぞれの列ごとに、列の長さ属性が結果の長さに挿入される前に、長さ属性にこの拡張係数を掛けます。

拡張しないことを指定するには、値 1.0 を使用します。 1.0 より小さい値を指定すると、結果の長さが短く計算されます。結果ストリングの実際の長さが、関数の計算された結果の長さよりも長い場合には、エラーが発生します (SQLSTATE 22001)。

フォーマット・ストリング関数を実行する際、どのフォーマットを使用するかを指定するストリング定数。

format-string は大文字小文字を区別するため、以下に示す値が認識されるようにするには、大文字で指定する必要があります。

COLATTVAL または COLATTVAL_XML: これらのフォーマットは、列を属性値とするストリングを戻します。

列名は、有効な XML 属性値である場合と、そうでない場合があります。列名が有効な XML 属性値ではない場合、列名が結果ストリングに挿入される前に、列名の文字置換が行われます。

列の値は、有効な XML エレメント名である場合と、そうでない場合があります。 format-string に COLATTVAL を指定すると、列名が有効な XML エレメント値ではない場合、列値が結果ストリングに挿入される前に、列値の文字置換が行われます。 format-string に COLATTVAL_XML を指定すると、列値の文字置換は行われません (ただし、列名の文字置換は行われます)。

行タグ・ストリング各行に使用するタグを指定するストリング定数。空ストリングを指定すると、値 row が想定されます。

1 つまたは複数のブランク文字の入ったストリングを指定すると、結果ストリングには、最初の row-tag-string も最後の row-tag-string も表示されません (不等号括弧の区切り文字を含む)。

column-name表列の名前 (修飾子付きまたは修飾子なし)。列のデータ・タイプは、以下のいずれかでなければなりません (SQLSTATE 42815)。

数値 (SMALLINT、INTEGER、BIGINT、DECIMAL、REAL、DOUBLE)
文字ストリング (CHAR、VARCHAR サブタイプ BIT DATA の文字ストリングは使用できません。)
日時 (DATE、TIME、TIMESTAMP)
上記のいずれかのデータ・タイプに基づくユーザー定義タイプ

同じ列名を 2 度以上指定することはできません (SQLSTATE 42734)。

関数の結果は、環境のストリング単位や指定した列に関係なく、OCTETS の VARCHAR です。最大長は 32 672 バイトです (SQLSTATE 54006)。

以下のような呼び出しの場合、

   REC2XML (dc, fs, rt, c₁, c₂, ..., c_n)

fs の値が COLATTVAL または COLATTVAL_XML のいずれかである場合、結果は次の式と同じになります。

'<' CONCAT rt CONCAT '>' CONCAT y₁ CONCAT y₂
CONCAT ... CONCAT y_n CONCAT '</' CONCAT rt CONCAT '>'

ここで y_n は以下と同等です。

'<column name="' CONCAT xvc_n CONCAT vn

さらに vn は以下と同等です。

'">' CONCAT r_n CONCAT '</column>'

(列が非 NULL の場合)

'" null="true"/>'

(列値が NULL の場合)

xvc_n は、c_nの列名のストリング表現に相当します。ここで、表 2 に示す文字は、対応する表現に置き換えられます。これによって、結果ストリングは必ず有効な XML 属性またはエレメント値のトークンになります。

r_n は、表 1 に示されているストリング表現と同等です。

表 1. 列値のストリング結果
c_n のデータ・タイプ	r_n
CHAR、VARCHAR	値はストリングです。 format-string が文字 _XMLで終わっていない場合、c_n の各文字は、示されているように、表 2の対応する置換表現に置き換えられます。長さ属性は、[dc] に [c_n の長さ属性] を乗算したものになります。
SMALLINT、 INTEGER、 BIGINT、 DECIMAL、 NUMERIC、 REAL、 DOUBLE	値は LTRIM(RTRIM(CHAR(c_n))) です。長さ属性は、CHAR(c_n) の結果の長さです。小数点文字は必ずピリオド (.) 文字です。
日数	値は CHAR(c_n,ISO) です。長さ属性は、CHAR(c_n,ISO) の結果の長さです。
時刻	値は CHAR(c_n,JIS) です。長さ属性は、CHAR(c_n,JIS) の結果の長さです。
TIMESTAMP	値は CHAR(c_n) です。長さ属性は、CHAR(c_n) の結果の長さです。

文字の置換:

format-string に指定される値によっては、列名を有効な XML 属性値にして、列値を有効な XML エレメント値にするために、列名と列値の一部の文字が置換されます。

表 2. XML 属性値およびエレメント値の文字置換
文字	置換
<	<
>	>
"	"
&	&
'	'

例

注: REC2XML は、出力にブランク・スペースや改行文字を挿入しません。例の出力はすべて、読みやすくするために書式を整えています。

例 1: サンプル・データベースの DEPARTMENT 表を使用して、部門 'D01' の部門表の行 (DEPTNAME 列と LOCATION 列を除く) を、 XML ストリングにフォーマット設定します。データの中には置換の必要な文字が入っていないため、拡張係数は 1.0 (拡張なし) です。さらに、この行の MGRNO 値が NULL であることに注意してください。
```
   SELECT REC2XML (1.0, 'COLATTVAL', '', DEPTNO, MGRNO, ADMRDEPT)
     FROM DEPARTMENT
     WHERE DEPTNO = 'D01'
```
この例は、以下の VARCHAR(117) ストリングを戻します。
```
   <row>
   <column name="DEPTNO">D01</column>
   <column name="MGRNO" null="true"/>
   <column name="ADMRDEPT">A00</column>
   </row>
```
例 2: 5 日制の大学スケジュールで、&43<FIE という名前の授業を CLASS_CODE 列用の新しいフォーマットを使用して、表 CL_SCHED に追加します。この例では REC2XML 関数を使用して、この新しい授業のデータの入った XML ストリングを形式設定します (授業の終了時刻を除く)。
拡張係数が 1.0 の REC2XML 呼び出しの長さ属性は 128 になります (<row> と </row> のオーバーヘッドに 11、列名に 21、<column name=、>、</column> および二重引用符に合わせて 75、CLASS_CODE データに 7、DAY データに 6、STARTING データに 8)。 & 文字と < 文字は置き換えられるため、拡張係数 1.0 では十分ではありません。関数の長さ属性は、新しいフォーマットの CLASS_CODE データ用に 7 バイトから 14 バイトへの増加をサポートする必要があるでしょう。
しかし、DAY 値が決して 1 桁より多くならないことがわかっているので、使用されない余分な 5 単位の長さが合計に加えられます。したがって、拡張で扱う必要があるのは、2 の増加のみということになります。 CLASS_CODE は引数リスト内の唯一の文字ストリング列であるため、これが、拡張係数が適用される唯一の列データです。長さを 2 だけ増加させるには、拡張係数 9/7 (約 1.2857) が必要でしょう。そこで、拡張係数 1.3 を使用します。
```
   SELECT REC2XML (1.3, 'COLATTVAL', 'record', CLASS_CODE, DAY, STARTING)
     FROM CL_SCHED
     WHERE CLASS_CODE = '&43<FIE'
```
この例は、以下の VARCHAR(167) ストリングを戻します。
```
   <record>
   <column name="CLASS_CODE">&amp;43&lt;FIE</column>
   <column name="DAY">5</column>
   <column name="STARTING">06:45:00</column>
   </record>
```
例 3: サンプル・データベースの EMP_RESUME 表に新しい行が追加されたとします。新しい行は、履歴書を有効な (妥当な) XML ストリングとして保管します。文字置換が実行されないように、format-string には COLATTVAL_XML を使用します。履歴書の長さは、3500 バイトを超えることはありません。以下の照会を使用して、EMP_RESUME 表から履歴書の XML バージョンを選択し、それを XML 文書の一部としてフォーマット設定します。
```
   SELECT REC2XML (1.0, 'COLATTVAL_XML', 'row', EMPNO, RESUME_XML)
     FROM (SELECT EMPNO, CAST(RESUME AS VARCHAR(3500)) AS RESUME_XML
       FROM EMP_RESUME
       WHERE RESUME_FORMAT = 'XML')
     AS EMP_RESUME_XML
```
この例は、XML フォーマットの履歴書がある各従業員ごとに、行を戻します。戻される各行は、次のフォーマットのストリングになります。
```
   <row>
   <column name="EMPNO">{employee number}</column>
   <column name="RESUME_XML">{resume in XML}</column>
   </row>
```
ここで、{employee number} は列の実際の EMPNO 値であり、{resume in XML} は履歴書である実際の XML フラグメント・ストリング値です。