33.9. 記述子領域の使用

33.9.1. 名前付きSQL記述子領域

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

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

EXEC SQL ALLOCATE DESCRIPTOR identifier;

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

EXEC SQL DEALLOCATE DESCRIPTOR identifier;

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

EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;

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

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

 
EXEC SQL BEGIN DECLARE SECTION;
char *sql_stmt = "SELECT * FROM table1";
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE stmt1 FROM :sql_stmt;
EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;

PostgreSQL 9.0より前では、SQLキーワードは省略可能でした。 このためDESCRIPTORおよびSQL DESCRIPTORは名前付きSQL記述子領域を生成しました。 これは強制事項になり、SQLキーワードを省略すると、SQLDA記述子領域を生成します。 項33.9.2を参照してください。

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

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

EXEC SQL GET DESCRIPTOR name :hostvar = field;

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

EXEC SQL GET DESCRIPTOR name VALUE num :hostvar = field;

numはリテラル整数、もしくは整数を持つホスト変数を取ることができます。 取り得るフィールドは以下の通りです。

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

EXEC SQL SET DESCRIPTOR name VALUE num field = :hostvar;

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

EXEC SQL BEGIN DECLARE SECTION;
int id[5];
EXEC SQL END DECLARE SECTION;

EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;

EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;

33.9.2. SQLDA記述子領域

SQLDA記述子領域は、問い合わせの結果セットとメタデータを取り出すために使用可能なC言語の構造体です。 1つの構造体には結果セットの1レコードが格納されます。

EXEC SQL include sqlda.h;
sqlda_t         *mysqlda;

EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;

SQLキーワードが省略されていることに注意してください。 項33.9.1のINTOおよびUSINGの使用状況に関する段落はここで多少追加して適用します。 DESCRIBE文では、INTOが使用されている場合DESCRIPTORキーワードは完全に省略可能です。

EXEC SQL DESCRIBE prepared_statement INTO mysqlda;

SQLDA構造体を以下に示します。

#define NAMEDATALEN 64

struct sqlname
{
        short           length;
        char            data[NAMEDATALEN];
};

struct sqlvar_struct
{
        short           sqltype;
        short           sqllen;
        char       *sqldata;
        short      *sqlind;
        struct sqlname sqlname;
};

struct sqlda_struct
{
        char            sqldaid[8];
        long            sqldabc;
        short           sqln;
        short           sqld;
        struct sqlda_struct *desc_next;
        struct sqlvar_struct    sqlvar[1];
};

typedef struct sqlvar_struct    sqlvar_t;
typedef struct sqlda_struct     sqlda_t;

結果セット内のフィールド数に依存しますし、レコード内の文字列データ値の長さにも依存しますので、SQLDA構造体に割り当てられたデータは可変です。 SQLDA構造体の個々のフィールドを以下に示します。