Enterprise Postgres 12 アプリケーション開発ガイド

D.6.1 名前付きSQL記述子領域

名前付きSQL記述子領域は、記述子全体に関する情報を持つヘッダと、基本的に結果行内の1つの列を記述する、1つ以上の項目記述子領域から構成されます。

SQL記述子領域を使用可能にするためには、それを以下のように割り当てなければなりません。

EXEC SQL ALLOCATE DESCRIPTOR identifier END-EXEC.

この識別子は記述子領域の"変数名"として使用されます。 記述子が不要になったら、以下のように解放してください。

EXEC SQL DEALLOCATE DESCRIPTOR identifier END-EXEC.

記述子領域を使用するには、INTO句内の格納対象として、ホスト変数を列挙するのではなく、記述子領域を指定してください。

EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc END-EXEC.

結果セットが空の場合であっても、記述子領域には問い合わせのメタデータ、つまりフィールド名、が含まれます。

まだ実行されていないプリペアード・クエリでは、結果セットのメタデータを入手するためにDESCRIBEを使用することができます。

EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 SQL-STMT PIC X(30) VARYING.
EXEC SQL END DECLARE SECTION END-EXEC.

MOVE "SELECT * FROM table1" TO ARR OF SQL-STMT.
COMPUTE LEN OF SQL-STMT = FUNCTION STORED-CHAR-LENGTH ( ARR OF SQL-STMT ) .
EXEC SQL PREPARE STMT1 FROM :SQL-STMT END-EXEC.
EXEC SQL DESCRIBE STMT1 INTO SQL DESCRIPTOR MYDESC END-EXEC.

PostgreSQL 9.0より前では、SQLキーワードは省略可能でした。 このためDESCRIPTORおよびSQL DESCRIPTORは名前付きSQL記述子領域を生成しました。 これは強制事項になり、SQLキーワードを省略すると、SQLDA記述子領域を生成する構文とみなされますが、ecobpgではSQLDAに対応していないため、エラーになります。

DESCRIBEおよびFETCH文では、INTOおよびUSINGキーワードを同じように使用することができます。 これらは結果セットと記述子領域内のメタデータを生成します。

さて、どうやって記述子領域からデータを取り出すのでしょうか。 この記述子領域を名前付きフィールドを持つ集団項目とみなすことができます。 ヘッダからフィールド値を取り出し、それをホスト変数に格納するには、以下のコマンドを使用します。

EXEC SQL GET DESCRIPTOR name :hostvar = field END-EXEC.

今のところ、COUNTというヘッダフィールドが1つだけ定義されています。 これは、記述子領域に存在する項目数を表すものです （つまり、結果内に含まれる列数です）。 このホスト変数はPIC S9(9) COMP-5の整数型でなければなりません。 項目記述子領域からフィールドを取り出すには、以下のコマンドを使用します。

EXEC SQL GET DESCRIPTOR name VALUE num :hostvar = field END-EXEC.

numはPIC S9(9) COMP-5形式の整数を持つホスト変数を取ることができます。 取り得るフィールドは以下の通りです。

CARDINALITY (整数)

結果セット内の行数です。

DATA

実際のデータ項目です （したがってこのフィールドのデータ型は問い合わせに依存します）。

DATETIME_INTERVAL_CODE (整数)

TYPEが9の場合、DATETIME_INTERVAL_CODEは、DATEでは1、TIMEでは2、TIMESTAMPでは3、TIME WITH TIME ZONEでは4、TIMESTAMP WITH TIME ZONEでは5という値を取ります。

DATETIME_INTERVAL_PRECISION (整数)

未実装です。

INDICATOR (整数)

（NULL値や値の切り詰めを示す）指示子です。

KEY_MEMBER (整数)

実装されていません。

LENGTH (整数)

データの文字列の長さです。

NAME (文字列)

列名です。

NULLABLE (整数)

実装されていません。

OCTET_LENGTH (整数)

データの文字表現のバイト長です。

PRECISION (整数)

（numeric型用の）精度です。

RETURNED_LENGTH (整数)

データの文字数です。

RETURNED_OCTET_LENGTH (整数)

データの文字表現のバイト長です。

SCALE (整数)

（numeric型用の）桁です。

TYPE (整数)

列のデータ型の数値コードです。

EXECUTE、DECLAREおよびOPEN文では、INTOおよびUSINGの効果は異なります。 また、問い合わせやカーソル用の入力パラメータを提供するために記述子領域は手作業で構築することができます。 USING SQL DESCRIPTOR nameは入力パラメータをパラメータ付きの問い合わせに渡す方法です。 名前付きSQL記述子領域を構築するSQL文は以下の通りです。

EXEC SQL SET DESCRIPTOR name VALUE num field = :hostvar END-EXEC.

PostgreSQLは、1つのFETCH文内の1レコードを複数取り出し、ホスト変数に格納することをサポートします。 この場合ホスト変数は配列であると仮定されます。

EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 GROUP-ITEM.
    05 IDNUM PIC S9(9) COMP OCCURS 5.
EXEC SQL END DECLARE SECTION END-EXEC.

EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc END-EXEC.

EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :IDNUM = DATA END-EXEC.